---

IMKServerInput Protocol Reference

(informal protocol)

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:

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

Tasks

Supporting Key Binding

• – inputText:client:
• – didCommandBySelector:client:

Unpacking Text Data

• – inputText:key:modifiers:client:

Receiving Events Directly from the Text Services Manager

• – handleEvent:client:

Committing a Composition

• – commitComposition:

Getting Input Strings and Candidates

• – composedString:
• – originalString:
• – 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 Mac 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 Mac OS X v10.5 and later.

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 Mac 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 Mac OS X v10.5 and later.

See Also

• – inputText:client:

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

extern const NSString *kIMKCommandMenuItemName;
extern const NSString *kIMKCommandClientName;

Constants

kIMKCommandMenuItemName

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

Available in Mac 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 Mac OS X v10.5 and later.

Declared in IMKInputController.h.

---