IMKInputController Class Reference

Inherits from
Conforms to
Framework
System/Library/Frameworks/InputMethodKit.framework
Availability
Available in OS X v10.5 and later.
Declared in
IMKInputController.h
Related sample code

Overview

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.

Tasks

Initializing an Input Controller

Working with Ranges

Managing the Delegate

Getting the Client and Server Objects

Tracking Selections

Managing Composition

Hiding the User Interface

Working with Custom Commands

Instance Methods

annotationSelected:forCandidate:

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

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

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

cancelComposition

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

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

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

candidateSelected:

Informs an input controller that a new candidate is selected.

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

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

candidateSelectionChanged:

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

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

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

client

Returns the client object associated with the input controller.

- (<IMKTextInput, NSObject>))client
Return Value

The client object.

Discussion

The client object conforms to the IMKTextInput protocol.

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

compositionAttributesAtRange:

Returns a dictionary of text attributes.

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

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

delegate;

Returns the delegate for input controller object.

- (id)delegate
Return Value

The delegate object.

doCommandBySelector:commandDictionary:

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

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

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

hidePalettes

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

- (void)hidePalettes
Availability
  • Available in OS X v10.5 and later.
Declared In
IMKInputController.h

initWithServer:delegate:client:

Initializes the input control by setting the delegate.

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

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

markForStyle:atRange:

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

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

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

menu

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

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

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

replacementRange

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

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

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

selectionRange

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

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

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

server

Returns the server object that manages the input controller.

- (IMKServer*)server
Return Value

The server object.

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

setDelegate:

Sets the delegate for input controller object.

- (void)setDelegate:(id)newDelegate
Parameters
newDelegate

The delegate object to set.

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

updateComposition

Informs the input controller that the composition has changed.

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

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