IMKCandidates Class Reference

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

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

Managing Selection Keys

Managing Window Visibility and Behavior

Managing Window Type and Text Attributes

Showing an Annotation Window

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 OS X v10.5 and later.
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 OS X v10.5 and later.
Declared In
IMKCandidates.h

hide

Hides a candidates window, if it is visible.

- (void)hide
Availability
  • Available in OS X v10.5 and later.
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 OS X v10.5 and later.
Related Sample Code
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 OS X v10.5 and later.
Declared In
IMKCandidates.h

panelType

Returns the style of the candidates window.

Return Value

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

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

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

Availability
  • Available in OS X v10.5 and later.
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 OS X v10.5 and later.
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 OS X v10.5 and later.
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 OS X v10.5 and later.
Related Sample Code
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 OS X v10.5 and later.
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 OS X v10.5 and later.
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 OS X v10.5 and later.
Related Sample Code
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 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 OS X v10.5 and later.
Related Sample Code
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 OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKScrollingGridCandidatePanel

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

Available in OS X v10.5 and later.

Declared in IMKCandidates.h.

kIMKSingleRowSteppingCandidatePanel

A window that displays a single row.

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

Declared in IMKCandidates.h.

Declared In
IMKCandidates.h