Mac Developer Library

Developer

InputMethodKit Framework Reference IMKServerInput Protocol Reference

Options
Deployment Target:

On This Page
Language:

IMKServerInput

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import InputMethodKit

Objective-C

@import InputMethodKit;

Availability


Available in OS X v10.5 and later.

IMKServerInput is an informal protocol that defines methods for receiving text events. This is intentionally not a formal protocol because there are three ways to receive events. An input method chooses one of the following approaches and implements the appropriate methods:

  • Key binding. In this approach the system tries to map each key-down event to an action method that the input method has implemented. If successful (action method found), the system calls didCommandBySelector:client:. If unsuccessful (action method not found), the system calls inputText:client:. For this approach you need to implement inputText:client: and didCommandBySelector:client:.

  • Text data only. In this approach, you opt to receive all key events without the key binding, and then unpack the relevant text data. Key events are broken down into the Unicodes, the key code that generated them, and modifier flags. This data is then sent to the inputText:key:modifiers:client: method, which you need to implement.

  • Handle all events. In this approach, you receive events directly from the Text Services Manager as NSEvent objects. You must implement handleEvent:client: method.

  • Handles key down events that do not map to an action method.

    Declaration

    Swift

    func inputText(_ string: String!, client sender: AnyObject!) -> Bool

    Objective-C

    - (BOOL)inputText:(NSString *)string client:(id)sender

    Parameters

    string

    The key down event, which is the text input by the client.

    sender

    The client object sending the key down events.

    Return Value

    YEStrue if the input is accepted; otherwise NOfalse.

    Discussion

    An input method should implement this method when using key binding (that is, it implements didCommandBySelector:client:).

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Processes a command generated by user action such as typing certain keys or pressing the mouse button.

    Declaration

    Swift

    func didCommandBySelector(_ aSelector: Selector, client sender: AnyObject!) -> Bool

    Objective-C

    - (BOOL)didCommandBySelector:(SEL)aSelector client:(id)sender

    Parameters

    aSelector

    The action associated with the key down event. The selector can be an action specified in the input method dictionary of keys and actions (that is, an action specific to the input method) or one of the NSResponder action methods such as insertNewline: or deleteBackward:. By definition such action methods do not return a value.

    sender

    The client object sending the key down event.

    Return Value

    YEStrue if the command is handled; NOfalse if the command is not handled. If not handled, the event passes to the client.

    Discussion

    This method is called when the system binds a key down event to an action method. If you implement this method you should test if it is appropriate to call the action method before actually calling it, because calling the action method implies that you agree to handle the command. Suppose you have implemented a version of insertNewline: that terminates the conversion session and sends the fully converted text to the client. However, if you conversion buffer is empty, you want the application to receive the return key that triggered the call to insertNewline:. In that case, when didCommandBySelector:client: is called you should test your buffer before calling your implementation of insertNewline:. If the buffer is empty, return NOfalse to indicate that the return key should be passed on to the application. If the buffer is not empty, call insertNewline: and then return YEStrue as the result of didCommandBySelector:client:.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Receives Unicode, the key code that generated it, and any modifier flags.

    Declaration

    Swift

    func inputText(_ string: String!, key keyCode: Int, modifiers flags: Int, client sender: AnyObject!) -> Bool

    Objective-C

    - (BOOL)inputText:(NSString *)string key:(NSInteger)keyCode modifiers:(NSUInteger)flags client:(id)sender

    Parameters

    string

    The text input by the client.

    keyCode

    The key code for the associated Unicode.

    flags

    The modifier flags.

    sender

    The client object.

    Return Value

    YEStrue if the input is accepted; otherwise NOfalse.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Handles key down and mouse events.

    Declaration

    Swift

    func handleEvent(_ event: NSEvent!, client sender: AnyObject!) -> Bool

    Objective-C

    - (BOOL)handleEvent:(NSEvent *)event client:(id)sender

    Parameters

    event

    The event to handle.

    sender

    The client object sending the event.

    Return Value

    YEStrue if the event is handled; otherwise NOfalse.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Informs the controller that the composition should be committed.

    Declaration

    Swift

    func commitComposition(_ sender: AnyObject!)

    Objective-C

    - (void)commitComposition:(id)sender

    Parameters

    sender

    The client object requesting the input method to commit the composition.

    Discussion

    If an input method implements this method, it is called when the client wants to end the composition session immediately. A typical response would be to call the insertText method of the client and then clean up any per-session buffers and variables. After receiving this message an input method should consider the given composition session finished.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Return the current composed string.

    Declaration

    Swift

    func composedString(_ sender: AnyObject!) -> AnyObject!

    Objective-C

    - (id)composedString:(id)sender

    Parameters

    sender

    The client object requesting the string.

    Return Value

    The current composed string, which can be an NSString or NSAttributedString object. The returned object should be an autoreleased object.

    Discussion

    A composed string refers to the buffer that an input method typically maintains to mirror the text contained in the active inline area. It is called the composed string to reflect the fact that the input method composed the string by converting the characters input by the user. In addition, using the term composed string makes it easier to differentiate between an input method buffer and the text in the active inline area that the user sees.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Return the a string that consists of the precomposed unicode characters.

    Declaration

    Swift

    func originalString(_ sender: AnyObject!) -> NSAttributedString!

    Objective-C

    - (NSAttributedString *)originalString:(id)sender

    Parameters

    sender

    The client object requesting the original string.

    Return Value

    The original string of precomposed unicode characters. If an input method stores the original input text, it returns that text. The return value is an attributed string so that the input method can restore changes they made to the font, and other attributes, if necessary. The returned object should be an autoreleased object.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of candidates.

    Declaration

    Swift

    func candidates(_ sender: AnyObject!) -> [AnyObject]!

    Objective-C

    - (NSArray *)candidates:(id)sender

    Parameters

    sender

    The client object requesting the candidates.

    Return Value

    An array of candidates. The returned array should be an autoreleased object.

    Discussion

    An input method should look up its currently composed string and return a list of candidate strings that that string might map to.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Constants for keys used to look up information in the info dictionary.

    Declaration

    Swift

    let kIMKCommandMenuItemName: String let kIMKCommandClientName: String

    Objective-C

    const NSString *kIMKCommandMenuItemName; const NSString *kIMKCommandClientName;

    Constants

    • kIMKCommandMenuItemName

      kIMKCommandMenuItemName

      Used to look up the NSMenuItem object that is passed to menu item actions.

      Available in OS X v10.5 and later.

    • kIMKCommandClientName

      kIMKCommandClientName

      Used to look up the client object; the client conforms to the IMKInputText and NSObject protocols.

      Available in OS X v10.5 and later.