http://developer.apple.com/wwdc2006/

Input Method Kit Overview

Lee CollinsManager, OS Engineering AsiaJohn HarveyOS Engineering Asia

Developing Input Methods

• InputMethodKit■ New framework for developing input methods

• Using keyboard layout overrides• Data-driven input methods• Delivery and installation

Input Method Kit• Foundation-based API for input method development• Easy to develop and port input method code• Less code

■ 28 files in old sample■ 8 files in IMKit sample

• Runs as background application■ Separate address space

• No need for 64-bit work• Fully integrated with TSM• Carbon and Cocoa apps

Input Method Kit — Division of Labor

• IMKit manages■ Communication with client apps■ Candidate window■ input method modes

• Developer supplies■ Text from a conversion engine written in any programming

language■ Key-bindings and optional event handling■ Optional menu with additional settings

■ preferences settings■ input mode specific commands

■ Information about input method in an extended info.plist

IMKit Classes

IMKServer

IMKCandidatesIMKInputController (1)

IMKInputController (2)

IMKInputController (n)

IMKit Classes• IMKServer

■ Manages client connections to your input method■ Create in input method application’s main()

• IMKCandidates■ Presents candidates to user■ Notifies appropriate IMKInputController when a candidate has

been selected

• IMKInputController■ Provides a base class for custom input controller classes■ Events and text from application■ Converted text from input method engine■ One controller per input session created by the IMKServer object

IMKit: Handling Text Events• Three different approaches

■ Keybinding: IMKit will map events to actions you implement■ -(BOOL)inputText:(NSString*)string client:(id)sender;■ -(BOOL)didCommandBySelector:(SEL)aSelector client:(id)sender;

■ Text data only■ -(BOOL)inputText:(NSString*)string key:(NSInteger)keyCode modifiers:

(NSUInteger)flags client:(id)sender;■ Handle all events

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

IMKit: Candidate Window

• Candidates = list of alternate input choices• Developer supplies candidate list • IMKit handles display and selection• 3 flavors of window:

■ Horizontal (kIMKSingleRowSteppingCandiatePanel)■ Vertical (kIMKSingleColumnScrollingCandiatePanel)■ Grid (kIMKScrollingGridCandidatePanel)

Using IMKCandidates• In IMKInputController delegate or subclass, implement these:

■ -(NSArray*) candidates■ supply candidate list to the IMKCandidates object

■ -(void) candidateSelected:(NSAttributedString*)string■ Update your state when a candidate is selected

• Create an IMKCandidates object with preferred window shape

• Set and show the candidates

• IMKit calls candidateSelected: when a candidate is selected

myCandidates = [[IMKCandidates alloc] initWithServer:server panelType:kIMKSingleColumnScrollingCandidatePanel];

[myCandidates updateCandidates];[myCandidates showCandidates:kIMKLocateCandidatesBelowHint];

IMKit: Mode Support• Means of packaging related input sources

■ E.g. Hiragana, Katakana and Romaji

• IMKit handes mode switching for you■ Just provide mode information in plist

■ “ComponentInputModeDict”■ IMKit tells you mode has been selected by sending

■ [ IMKInputController setValue:(id) valueforTag:(unsigned long) tag client:(id) sender ];

IMKit: plist Additions• Add ComponentInputModeDict for modes• Set LSBackgroundOnly to 1

• Add InputMethodServerControllerClass key & value■ Enables IMKServer to find your IMKController class

• Add the InputMethodConnectionName key & value■ Enables IMKit framework to find your server

<key> LSBackgroundOnly </key><string>1</string>

http://developer.apple.com/wwdc2006/

Input Method Hands On

Install the Project Template• Install Template InputMethod Application in:

■ /Library/Application Support/Apple/Developer Tools/Project Templates/Application

• Open XCode

• Select New Project from File Menu

• Select Input Method Application

Create the Project• Name the project Numbers• Save it to /Users/Shared/Numbers/

Modifying the plist• The Info.plist file has 6 important Keys(red required, green optional)

■ LSBackGroundOnly■ Background applicatons don’t show in he Dock or Apple Menu.

■ InputMethodSessionController■ Names your controller class.

■ InputMethodServerDelegateClass■ Names your delegate class

■ ComponentInputModeDict■ List your input method’s modes

■ InputMethodConnectionName■ Names your server’s connection

■ tsInputMethodIconFileKey■ Displayed in Text Input Menu and International Preferences

■ tsInputMethodCharacterRepertoire■ Names ISO 15924 scripts your input method supports.

Controllers and Delegates• What is a Controller object

■ Is in charge of something.

• What is a delegate■ An object that implements a method declared in a protocol.■ Exactly what kind of object implements the method is not

important.

• In the InputMethodKit. Your controller manages the buffer and converting text. The Delegate receives text and handles specific events.

• Delegate and Controller are not necessarily separate objects.

InputMethodSessionController• Names your controller class

■ Necessary if you override IMKInputController■ And you initialize IMKServer with:

■ -(id)initWithName:(NSString*)name bundleIdentifier:(NSString*)bundleIdentifier

InputMethodServerDelegateClass• This key names your delegate class.

■ Include this key if you provide a delegate class that implements methods in the protocols defined in IMKInputController■ IMKServerInput■ IMKStateSetting■ IMKMouseHandling

• Your controller class can also serve as you delegate class.

ComponentInputModeDict• Include this dictionary if your input method includes input

modes.■ For all the details read Tech Note 2128

■ <http://developer.apple.com/technotes/tn2005/tn2128.html>■ An input method should include input modes when it uses

multiple ways of processing keyboard text input.

• Dictionary contains two keys■ tsInputModeListKey

■ A dictionary which defines each mode.■ tsVisibleInputModeOrderedArrayKey

■ Array of strings that define how your modes are displayed by the System.

InputMethodConnectionName• IMKServer uses this to create an NSConnection

■ Client applications communicate to the server via the named NSConnection.

■ Do not include spaces in the name or periods.■ Good

■ BasicInputMethodServer_1_Connection■ Bad

■ BasicInputMethodServer.1.Connection■ BasicInputMethodServer 1 Connection

tsInputMethodIconFileKey• Name of the file that contains the icon used to display your

input method in the Text Input Menu or the International Preferences Panel.

• The file itself is part of the Input Method’s bundle

tsInputMethodCharacterRepertoire• List the ISO 15924 script codes that your input method supports

■ Alphabetical script codes.■ http://www.unicode.org/iso15924/codelists.html

• This example indicates an input method that supports the Latin script.

<key>tsInputMethodCharacterRepertoireKey</key><array> <string>Latn</string></array>

Personalizing the Project• Rename the controller class to NumbersInputController.[hm]

■ Be sure and rename the class interface inside the .h file.

■ The class implementation

■ Change #import as well.

• Open the Info.plist file■ Change the string InputMethodSessionController to

NumbersInputController<string>InputMethodSessionController</string>

<string>NumbersInputController</string>

@interface NumbersInputController

@interface InputMethodSessionController

@implementation NumbersInputController@implementation InputMethodSessionController

#import "NumbersInputController.h"

#import "NumbersInputController.h"

Adding the Input Modes• Our example looks for a number and then formats the number. • Each type of formatting supported is an input mode.• The modes are:

■ no style■ decimal■ currency■ percent■ spellout

• The modes are specified in the ComponentInputModeDict• Open a modified ComponentInputModeDict

■ /Users/Shared/Beijing/Files/NumbersModeList.txt

• Copy every thing there and replace the old ComponentInputModeDict and the old tsVisibleInputModeOrderedArrayKey with what you copied.

tsVisibleInputModeOrderedArrayKey• List of keys that are used to look up localizable strings.• The localizable strings are located in the InfoPlist.strings file.

■ Open the Numbers InfoPlist.strings file.■ Open /Users/Shared/Beijing/Files/NewModesStrings.txt■ Replace the mode strings in InfoPlist.strings with the new strings.

Adding Your Icons• For this example we have 6 icons

■ The Input Method Icon■ The 6 mode icons

• Note that you still have the normal application icons that will be seen in the Finder.

• In XCode add the .tiff files in /Users/Shared/Beijing/Images/Icons.

• Put them in the Resources group.■ You may want to add an Images group inside

Build Your Do Nothing Input Method

Getting Input• The IMKServerInput informal protocol provides 3 different

approaches for receiving client input■ Receive text as an NSString, and use keybinding to “parse” the

input context.

■ Receive text as an NSString. The IMKServer extracts the context.

■ Receive events as NSEvents.

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

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

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

Why Three Choices• Three is a special number in the west.• Seriously

■ We want to accommodate where different developers are coming from.■ -(BOOL)inputText:client:

■ The most Cocoa approach.■ -(BOOL)inputText:key:modifiers:client:

■ Would like to see every keydown, but don’t really want to parse NSEvents.

■ -(BOOL)handleEvent:client:■ Porting an old component based input method.

Keybinding• Modeled after the NSResponder class.

■ You can implement a method from a set of standard key event handlers. ■ deleteBackward:■ insertNewline:■ See documentation for NSResponder for other action messages.

■ You can also specify your own keybinding in a dictionary.■ InputMethodKeysDictionary.dict<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict> <key>~ß</key> <string>showAlternatives:</string></dict></plist>

Client Architecture• Means you don’t need to manage input sessions.

• InputMethodKit maps clients to appropriate input controllers.

• One input controller is allocated for each input session.

• The sender parameter is used to communicate back to the client.

IMKTextInput Protocol • Used to communicate with the client application.

■ Send the message to the client parameter■ i.e. [sender insertText:aString replacementRange:aRange];

• Sending Text■ Formerly kEventTextInputUpdateActiveInputArea CarbonEvent

• Fix Text

• Mark Text

- (void)insertText:(id)string replacementRange:(NSRange)replacementRange;

- (void)setMarkedText:(id)string selectionRange:(NSRange)selectionRange replacementRange:(NSRange)replacementRange;

selectionRange & replacementRange• selectionRange

■ Location is relative to the inline session.

• replacementRange■ Location is relative to the client document.

• Insert at current selection■ Set replacementRange.location = NSNotFound

document text 等きょうselectionRange (4,0)

document text 等きょうmore document text

selectionRange (4,0)replacementRange(13,0)

Positioning Methods• Mapping a character index to screen position

(kEventTextInputOffsetToPos)

■ Returned rectangle contains screen relative coordinates

• Map screen position to character index (kEventTextInputPosToOffset)

■ mappingMode■ Set to IMKMouseTrackingMode when your input method is tracking

the mouse.■ When placing the cursor set to IMKNearestBoundaryMode.

- (NSInteger)characterIndexForPoint:(NSPoint)point tracking:(IMKLocationToOffsetMappingMode)mappingMode inMarkedRange:(BOOL*)inMarkedRange

- (NSRect)firstRectForCharacterRange:(NSRange)theRange;

Overriding the Current Keyboard• Your Input Method can contain keyboards• To force the system to use your keyboard use:

• The keyboard name should be a DNS type name:

-(void)overrideKeyboardWithKeyboardNamed:(NSString*)keyboardUniqueName

com.companyname.inputmethodname.keyboardname

Document Access Based Methods• Document Access

■ Client document regarded as a CFStringRef

• Find the current selection.

• Find the document length.

• Find an attributed string for a given range in the document.

• Not all clients support the Document access protocol■ Be prepared for ranges of NSNotFound or a string value of nil.

- (NSRange)selectedRange

- (NSInteger)length

- (NSAttributedString*)attributedSubstringFromRange:(NSRange)range;

Managing Global Resources• What is a global resource?

■ Dictionary■ Menu■ UI Elements■ Conversion Engine

• An IMKit input method is an application .■ Global data

■ You may want to write or use a container object.■ We will use the Application delegate object.

Sample Architecture

Global Resources contained in Application delegate

NSNumberFormater (conversion engine)

InputEngine

Multiple NumberInputControllers which access global resources.These are managed by the IMKServer.

NumbersInputController

NumbersInputController

NumbersInputController

NumbersInputController

What We Need From You

Tell us where the InputMethodKit doesn’t meet your needs.

Contacts:

jharvey@apple.comlcollins@apple.com

Beijing Kitchen 2006