Mac Developer Library

Developer

InputMethodKit Framework Reference IMKInputController Class Reference

Options
Deployment Target:

On This Page
Language:

IMKInputController

Inheritance


Conforms To


Import Statement


Swift

import InputMethodKit

Objective-C

@import InputMethodKit;

Availability


Available in OS X v10.5 and later.

The IMKInputController class provides a base class for custom input controller classes. The IMKServer class, which is allocated in the main function of an input method, creates an input controller object for each input session created by a client application. For every input session there is a corresponding IMKInputController object.

An IMKInputController object controls text input on the input method side. It manages events and text from the applications and converted text from the input method engine. IMKInputController implements fully the IMKStateSetting and IMKMouseHandling protocols. Typically you do not need to override this class, but you do need to provide a delegate object that implements the methods that your are interested in. The IMKInputController versions of the protocol methods check whether the delegate object implements a method, and calls the delegate version if it exists.

  • Initializes the input control by setting the delegate.

    Declaration

    Swift

    init!(server server: IMKServer!, delegate delegate: AnyObject!, client inputClient: AnyObject!)

    Objective-C

    - (id)initWithServer:(IMKServer *)server delegate:(id)delegate client:(id)inputClient

    Parameters

    server

    The server object for the controller.

    delegate

    The delegate object.

    inputClient

    The client object that will send messages to the controller using the server object. The client object must confirm to the IMKTextInput protocol.

    Return Value

    The initialized input controller object.

    Discussion

    Methods in the IMKStateSetting and IMKMouseHandling protocols that are implemented by the delegate object always include a client parameter. Methods in the IMKInputController class do not need to take a client because the initWithServer:delegate:client: method stores the client object you supply as an ivar when it initializes the IMKInputController object.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns a dictionary of text attributes.

    Declaration

    Swift

    func compositionAttributesAtRange(_ range: NSRange) -> NSMutableDictionary!

    Objective-C

    - (NSMutableDictionary *)compositionAttributesAtRange:(NSRange)range

    Parameters

    range

    The range of text whose attributes you want to obtain.

    Return Value

    The dictionary of text attributes. The default implementation returns an empty dictionary.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns where the range of the selection that should be placed inside marked text.

    Declaration

    Swift

    func selectionRange() -> NSRange

    Objective-C

    - (NSRange)selectionRange

    Return Value

    The range of the selection.

    Discussion

    This method is called by updateComposition to obtain the selection range for marked text. The default implementation sets the selection range at the end of the marked text. You should override this method if your input method provides font or glyph information.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the range in the client document that the text should replace.

    Declaration

    Swift

    func replacementRange() -> NSRange

    Objective-C

    - (NSRange)replacementRange

    Return Value

    The range to replace.

    Discussion

    This method is called by updateComposition to obtain the range in the client document where marked text should be placed. The default implementation returns an NSRange object whose location and length are NSNotFound. That indicates that the marked text should be placed at the current insertion point. Input methods that insert marked text somewhere other than at the current insertion point should override this method.

    An example of an input method that might override this method would be one replaces words with synonyms. That input method would watch for certain words and when it detects such a word it would replaced the word by marked text that was a synonym of the word.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns a dictionary of text attributes that can mark a range of an attributed string to send to a client.

    Declaration

    Swift

    func markForStyle(_ style: Int, atRange range: NSRange) -> [NSObject : AnyObject]!

    Objective-C

    - (NSDictionary *)markForStyle:(NSInteger)style atRange:(NSRange)range

    Parameters

    style

    A style, which should be one of the following values: kTSMHiliteSelectedRawText, kTSMHiliteConvertedText, or kTSMHiliteSelectedConvertedText. See the AERegistry.h header file for the definition of these values.

    range

    The range (that is, a clause) to mark.

    Return Value

    The dictionary of text attributes.

    Discussion

    This utility function can be called by input methods to mark each range (i.e. clause ) of marked text. T

    The default implementation first calls the method compositionAttributesAtRange: to obtain the additional attributes that an input method wants to include, such as font or glyph information. Then, it adds the appropriate underline and underline color information to the attributes dictionary for the style parameter. Finally it adds the style value as the dictionary value. The key for the style value is NSMarkedClauseSegmentAttributeName.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the delegate for input controller object.

    Declaration

    Objective-C

    - (id)delegate

    Return Value

    The delegate object.

  • Sets the delegate for input controller object.

    Declaration

    Swift

    func setDelegate(_ newDelegate: AnyObject!)

    Objective-C

    - (void)setDelegate:(id)newDelegate

    Parameters

    newDelegate

    The delegate object to set.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – delegate;

  • Returns the server object that manages the input controller.

    Declaration

    Swift

    func server() -> IMKServer!

    Objective-C

    - (IMKServer *)server

    Return Value

    The server object.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the client object associated with the input controller.

    Declaration

    Swift

    func client() -> protocol<IMKTextInput, NSObjectProtocol>!

    Objective-C

    - (id<IMKTextInput,NSObject>)client

    Return Value

    The client object.

    Discussion

    The client object conforms to the IMKTextInput protocol.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Sends the selected candidate string and annotation string to the input controller.

    Declaration

    Swift

    func annotationSelected(_ annotationString: NSAttributedString!, forCandidate candidateString: NSAttributedString!)

    Objective-C

    - (void)annotationSelected:(NSAttributedString *)annotationString forCandidate:(NSAttributedString *)candidateString

    Parameters

    annotationString

    The annotation string associated with the candidate.

    candidateString

    The candidate string that the user moved to.

    Discussion

    This method is called when the user moves to a candidate.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Informs an input controller that the current candidate selection in the candidate window has changed.

    Declaration

    Swift

    func candidateSelectionChanged(_ candidateString: NSAttributedString!)

    Objective-C

    - (void)candidateSelectionChanged:(NSAttributedString *)candidateString

    Parameters

    candidateString

    The changed candidate string.

    Discussion

    Note this method is called to indicate user activity in the candidate window. The candidate object might not be the user’s final selection.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Informs an input controller that a new candidate is selected.

    Declaration

    Swift

    func candidateSelected(_ candidateString: NSAttributedString!)

    Objective-C

    - (void)candidateSelected:(NSAttributedString *)candidateString

    Parameters

    candidateString

    The changed candidate string.

    Discussion

    The candidate object is the user’s final choice from the candidate window. The candidate window is closed before this method is called.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Informs the input controller that the composition has changed.

    Declaration

    Swift

    func updateComposition()

    Objective-C

    - (void)updateComposition

    Discussion

    This method calls the protocol method composedString: to obtain the current composition. The current composition is sent to the client by a call to the method setMarkedText:selectionRange:replacementRange:.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Stops the current composition and replaces marked text with the original text.

    Declaration

    Swift

    func cancelComposition()

    Objective-C

    - (void)cancelComposition

    Discussion

    This method calls the method originalString: to obtain the original text and sends that text to the client using a call to the IMKTextInput protocol method insertText:replacementRange:

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Informs an input method that it should close any visible user interface.

    Declaration

    Swift

    func hidePalettes()

    Objective-C

    - (void)hidePalettes

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Passes commands that are not generated as part of the text input process.

    Declaration

    Swift

    func doCommandBySelector(_ aSelector: Selector, commandDictionary infoDictionary: [NSObject : AnyObject]!)

    Objective-C

    - (void)doCommandBySelector:(SEL)aSelector commandDictionary:(NSDictionary *)infoDictionary

    Parameters

    aSelector

    A selector that represents a command from the text input menu.

    infoDictionary

    A dictionary that contains two key-value pairs:

    Discussion

    The default implementation checks if the input controller object (that is, self) responds to the selector. If so, it sends the message performSelector:withObject: to the input controller class. The object parameter in that case is the infoDictionary parameter.

    This method is called when a user selects a command from the text input menu. To support this, an input method must provide actions for each menu item that is placed in the menu. For example, (void)menuAction:(id)sender. Note that the sender in this instance is the info dictionary.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – menu

  • Returns a menu of commands that are specific to an input method.

    Declaration

    Swift

    func menu() -> NSMenu!

    Objective-C

    - (NSMenu *)menu

    Return Value

    The menu object.

    Discussion

    This method is called whenever the menu needs to be drawn so that an input method can update the menu to reflect the current state.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.