---

IMKCandidates Class Reference

Overview

The IMKCandidates class presents candidates to users and notifies the appropriate IMKInputController object when the user selects a candidate. Candidates are alternate characters for a given input sequence. The IMKCandidates class supports using a candidates window in your input method; using IMKCandidates is optional. Not all input methods require them.

When you create an IMKCandidates object, you attach it to the IMKServer object for your input method. You then need to override the IMKInputController methods candidateSelectionChanged: and candidateSelected: as well as implement a candidates method in your delegate object. The IMKInputController subclass supplies candidates to the IMKCandidates object by implementing the candidates method. When you are ready to display a candidates window, call the candidates method to update candidates and to show the candidates window.

Tasks

Initializing a Candidates Window

• – initWithServer:panelType:

Managing Selection Keys

• – setSelectionKeys:
• – selectionKeys
• – setSelectionKeysKeylayout:
• – selectionKeysKeylayout

Managing Window Visibility and Behavior

• – show:
• – hide
• – isVisible
• – setDismissesAutomatically:
• – dismissesAutomatically
• – updateCandidates

Managing Window Type and Text Attributes

• – panelType
• – setPanelType:
• – setAttributes:
• – attributes

Showing an Annotation Window

• – showAnnotation:

Instance Methods

attributes

Returns a dictionary of the style attributes used for the candidates window..

- (NSDictionary *)attributes

Return Value

The dictionary that contains the keys and values for the styles.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setAttributes:

Declared In

IMKCandidates.h

dismissesAutomatically

Returns the state of the flag that determines whether the candidates window dismisses automatically.

- (BOOL)dismissesAutomatically

Return Value

YES if the candidates window dismisses automatically; otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setDismissesAutomatically:

Declared In

IMKCandidates.h

hide

Hides a candidates window, if it is visible.

- (void)hide

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – show:
• – isVisible

Declared In

IMKCandidates.h

initWithServer:panelType:

Returns the initialized IMKCandidates object.

- (id)initWithServer:(IMKServer *)server panelType:(IMKCandidatePanelType)panelType

Parameters

server

The IMKServer object that manages the candidate and the panel type.

panelType

A panel type for the candidate window.

Return Value

The initialized IMKCandidates object.

Discussion

When an input method allocates an IMKCandidates object it should initialize that object by calling this method.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

IMKCandidates.h

isVisible

Returns whether or not the candidates window is visible.

- (BOOL)isVisible

Return Value

YES if the candidates window is visible; otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – hide
• – show:

Declared In

IMKCandidates.h

panelType

Returns the style of the candidates window.

- (IMKCandidatePanelType)panelType

Return Value

A “IMKCandidatePanelType” constant that represents the style of the candidates window.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setPanelType:

Declared In

IMKCandidates.h

selectionKeys

Returns an array of NSNumber objects where each NSNumber object represents a virtual key code.

- (NSArray *)selectionKeys

Return Value

The array of NSNumber objects. This array is an autorelease object. Do not release it unless you first retain it.

Discussion

Selection keys are keys that can be used to select one of the candidates. They are displayed next to the candidate that will be selected when the user types that key.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setSelectionKeys:

Declared In

IMKCandidates.h

selectionKeysKeylayout

Returns the key layout that maps virtual key codes to selection keys.

- (TISInputSourceRef)selectionKeysKeylayout

Return Value

The key layout in use. By default this is the key layout whose source id is com.apple.keylayout.US. This object is an autorelease object. Do not release it unless you first retain it.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setSelectionKeysKeylayout:

Declared In

IMKCandidates.h

setAttributes:

Sets the style attributes for the candidates window.

- (void)setAttributes:(NSDictionary *)attributes

Parameters

attributes

A dictionary that contains keys and values for the styles to use. You can supply the keys and values listed in the following table:

Key	Value
NSFontAttributeName	An NSFont object. Setting the font attribute sets the font that is used to draw Candidates. It does not effect the selection keys which are always drawn in the same font. Note that to set the font size you should use this key/value pair.
IMKCandidatesOpacityAttributeName	An NSNumber object that represents a floating-point value between 0.0 (transparent) and 1.0 (completely opaque. The default opacity is 1.0.
NSForegroundColorAttributeName	An NSColor object to use for the candidate text color. The default color is black.
NSBackgroundColorDocumentAttribute	An NSColor object to use for the background color behind the candidate text.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – attributes

Declared In

IMKCandidates.h

setDismissesAutomatically:

Sets the state of the flag that determines whether the candidates window dismisses automatically.

- (void)setDismissesAutomatically:(BOOL)flag

Parameters

flag

YES to have the candidates window dismiss automatically; otherwise NO.

Discussion

By default, if the user presses the Return or Enter keys, the candidates are dismissed and a candidateSelected: message is sent to the input controller. You can call the setDismissesAutomatically: method, passing NO as the flag parameter to change the default dismissal behavior. The input controller still receives a candidatesSelected: message.

When you set the flag to NO, an input method processes text input while dynamically updating the content of the candidates as the user inputs text. When a session deactivates, candidate window is hidden regardless of the state of the flag.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – dismissesAutomatically

Declared In

IMKCandidates.h

setPanelType:

Sets the style of the candidates window.

- (void)setPanelType:(IMKCandidatePanelType)panelType

Parameters

panelType

A “IMKCandidatePanelType” constant that represents the style of the candidates window.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – panelType

Related Sample Code

• NumberInput_IMKit_Sample

Declared In

IMKCandidates.h

setSelectionKeys:

Sets the selection keys for the candidates.

- (void)setSelectionKeys:(NSArray *)keyCodes

Parameters

keyCodes

An array of NSNumber objects where each NSNumber object represents a virtual key code. The input controller maps these key codes to characters that are displayed either across the top of the candidates, if the candidates are laid out horizontally, or along the left edge of the candidates, if they are aligned vertically.

Discussion

Selection keys are keys that can be used to select one of the candidates. They are displayed next to the candidate that will be selected when the user types that key.

The number of selection keys determines how many candidates are displayed per page. For example, if you pass an array of four key codes, four candidates are displayed per page. If you pass eleven key codes, eleven candidates are displayed. By default, the key codes are mapped using the keyboard layout whose source id is com.apple.keylayout.US. You can replace the default layout by calling setSelectionKeysKeylayout:. The default selection keys are the digits 1 through 9 or, in terms of key codes, 18, 19, 20, 21, 23, 22, 26, 28, and 25.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – selectionKeys

Declared In

IMKCandidates.h

setSelectionKeysKeylayout:

Sets the key layout that is used to map virtual key codes to characters.

- (void)setSelectionKeysKeylayout:(TISInputSourceRef)layout

Parameters

layout

The key layout to use.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – selectionKeysKeylayout

Declared In

IMKCandidates.h

show:

Shows the candidates window.

- (void)show:(IMKCandidatesLocationHint)locationHint

Parameters

locationHint

A “IMKCandidatesLocationHint” constant that specifies the desired position of the candidates window. The Input Method Kit uses the hint to place the candidates window in a location that is in the vicinity of the hint location and ensures that the candidates window is fully visible.

Discussion

Your input method calls this method when it is appropriate during text conversion to display a list of candidates.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – hide
• – isVisible

Related Sample Code

• NumberInput_IMKit_Sample

Declared In

IMKCandidates.h

showAnnotation:

Displays an annotation string in an annotation window.

- (void)showAnnotation:(NSAttributedString *)annotationString

Parameters

annotationString

The string to display.

Discussion

An annotation string explains or comments on the candidate string in the candidates window. An annotation window is a small, borderless window that is aligned with the current candidates window. An input method calls showAnnotation: when the candidateSelectionChanged: method of the IMKInputController class is called, and the candidate string has annotations.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

IMKCandidates.h

updateCandidates

Updates the candidates that are displayed in the candidates window.

- (void)updateCandidates

Discussion

When you call this method, the Input Method Kit calls the candidates method of the IMKInputController class. Note that the candidates list is updated, but the visible state of the window does not change. In other words, if the window is hidden, it remains hidden. If the window is visible, it remains visible.

Availability

• Available in Mac OS X v10.5 and later.

Related Sample Code

• NumberInput_IMKit_Sample

Declared In

IMKCandidates.h

Constants

IMKCandidatePanelType

Types of candidates windows provide by the Input Method Kit.

enum {   kIMKSingleColumnScrollingCandidatePanel = 1,
   kIMKScrollingGridCandidatePanel = 2,
   kIMKSingleRowSteppingCandidatePanel = 3 };
typedef NSUInteger IMKCandidatePanelType;

Constants

kIMKSingleColumnScrollingCandidatePanel

A window that displays one column and can scroll if necessary.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKScrollingGridCandidatePanel

A window that displays a grid and can scroll if necessary.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKSingleRowSteppingCandidatePanel

A window that displays a single row.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

Declared In

IMKCandidates.h

IMKCandidatesLocationHint

Hints that suggest where to place the candidates window.

enum {   kIMKLocateCandidatesAboveHint = 1,
   kIMKLocateCandidatesBelowHint = 2,
   kIMKLocateCandidatesLeftHint = 3,
   kIMKLocateCandidatesRightHint = 4
};typedef NSUInteger IMKCandidatesLocationHint;

Constants

kIMKLocateCandidatesAboveHint

Place the candidates window above the start of the current text selection.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKLocateCandidatesBelowHint

Place the candidates window below the start of the current text selection.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKLocateCandidatesLeftHint

Place the candidates window to the left of the current text selection.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKLocateCandidatesRightHint

Place the candidates window to the right of the current text selection.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

Discussion

The Input Method Kit uses the hint to place the candidates window in a location that is in the vicinity of the hint location, but that also ensures that the candidates window is fully visible.

Declared In

IMKCandidates.h

IMKCandidatesOpacityAttributeName

The opacity level for a candidates window.

extern const *NSString IMKCandidatesOpacityAttributeName;

Constants

IMKCandidatesOpacityAttributeName

The opacity attribute for a candidates window. The associated value must be an NSNumber object that represents a value from 0 to 1.

Available in Mac OS X v10.5 and later.

Declared in IMKCandidates.h.

Declared In

IMKCandidates.h

---