IMKServerInput Protocol Reference

(informal protocol)

Framework
System/Library/Frameworks/InputMethodKit.framework
Availability
Available in OS X v10.5 and later.
Declared in
IMKInputController.h

Overview

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:

Tasks

Supporting Key Binding

Unpacking Text Data

Receiving Events Directly from the Text Services Manager

Committing a Composition

Getting Input Strings and Candidates

Instance Methods

candidates:

Returns an array of candidates.

- (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.

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

commitComposition:

Informs the controller that the composition should be committed.

- (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.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
IMKInputController.h

composedString:

Return the current composed string.

- (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.

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

didCommandBySelector:client:

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

- (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

YES if the command is handled; NO 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 NO to indicate that the return key should be passed on to the application. If the buffer is not empty, call insertNewline: and then return YES as the result of didCommandBySelector:client:.

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

handleEvent:client:

Handles key down and mouse events.

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

The event to handle.

sender

The client object sending the event.

Return Value

YES if the event is handled; otherwise NO.

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

inputText:client:

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

- (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

YES if the input is accepted; otherwise NO.

Discussion

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

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

inputText:key:modifiers:client:

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

- (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

YES if the input is accepted; otherwise NO.

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

originalString:

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

- (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.

Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

Constants

Info Dictionary Keys

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

const NSString *kIMKCommandMenuItemName;
const NSString *kIMKCommandClientName;
Constants
kIMKCommandMenuItemName

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

Available in OS X v10.5 and later.

Declared in IMKInputController.h.

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.

Declared in IMKInputController.h.