Mac Developer Library

Developer

InputMethodKit Framework Reference IMKCandidates Class Reference

Options
Deployment Target:

On This Page
Language:

IMKCandidates

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.

Inheritance


Conforms To


Import Statement


Swift

import InputMethodKit

Objective-C

@import InputMethodKit;

Availability


Available in OS X v10.5 and later.
  • Returns the initialized IMKCandidates object.

    Declaration

    Swift

    init!(server server: IMKServer!, panelType panelType: IMKCandidatePanelType)

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the selection keys for the candidates.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (void)setSelectionKeysKeylayout:(TISInputSourceRef)layout

    Parameters

    layout

    The key layout to use.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (TISInputSourceRef)selectionKeysKeylayout

    Return Value

    The key layout in use. By default this is the key layout whose source id is com.apple.keylayout.US.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

  • Shows the candidates window.

    Declaration

    Swift

    func show(_ locationHint: IMKCandidatesLocationHint)

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Hides a candidates window, if it is visible.

    Declaration

    Swift

    func hide()

    Objective-C

    - (void)hide

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns whether or not the candidates window is visible.

    Declaration

    Swift

    func isVisible() -> Bool

    Objective-C

    - (BOOL)isVisible

    Return Value

    YEStrue if the candidates window is visible; otherwise NOfalse.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (void)setDismissesAutomatically:(BOOL)flag

    Parameters

    flag

    YEStrue to have the candidates window dismiss automatically; otherwise NOfalse.

    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 NOfalse as the flag parameter to change the default dismissal behavior. The input controller still receives a candidatesSelected: message.

    When you set the flag to NOfalse, 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.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (BOOL)dismissesAutomatically

    Return Value

    YEStrue if the candidates window dismisses automatically; otherwise NOfalse.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

  • Updates the candidates that are displayed in the candidates window.

    Declaration

    Swift

    func updateCandidates()

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the style of the candidates window.

    Declaration

    Swift

    func panelType() -> IMKCandidatePanelType

    Objective-C

    - (IMKCandidatePanelType)panelType

    Return Value

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the style of the candidates window.

    Declaration

    Swift

    func setPanelType(_ panelType: IMKCandidatePanelType)

    Objective-C

    - (void)setPanelType:(IMKCandidatePanelType)panelType

    Parameters

    panelType

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – panelType

  • Sets the style attributes for the candidates window.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

    See Also

    – attributes

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

    Declaration

    Objective-C

    - (NSDictionary *)attributes

    Return Value

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Availability

    Available in OS X v10.5 and later.

  • Displays an annotation string in an annotation window.

    Declaration

    Swift

    func showAnnotation(_ annotationString: NSAttributedString!)

    Objective-C

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

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Types of candidates windows provide by the Input Method Kit.

    Declaration

    Swift

    typealias IMKCandidatePanelType = Int

    Objective-C

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

    Constants

    • kIMKSingleColumnScrollingCandidatePanel

      kIMKSingleColumnScrollingCandidatePanel

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

      Available in OS X v10.5 and later.

    • kIMKScrollingGridCandidatePanel

      kIMKScrollingGridCandidatePanel

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

      Available in OS X v10.5 and later.

    • kIMKSingleRowSteppingCandidatePanel

      kIMKSingleRowSteppingCandidatePanel

      A window that displays a single row.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • Hints that suggest where to place the candidates window.

    Declaration

    Swift

    typealias IMKCandidatesLocationHint = Int

    Objective-C

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

    Constants

    • kIMKLocateCandidatesAboveHint

      kIMKLocateCandidatesAboveHint

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

      Available in OS X v10.5 and later.

    • kIMKLocateCandidatesBelowHint

      kIMKLocateCandidatesBelowHint

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

      Available in OS X v10.5 and later.

    • kIMKLocateCandidatesLeftHint

      kIMKLocateCandidatesLeftHint

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

      Available in OS X v10.5 and later.

    • kIMKLocateCandidatesRightHint

      kIMKLocateCandidatesRightHint

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

      Available in OS X v10.5 and later.

    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.

    Import Statement

    Objective-C

    @import InputMethodKit;

    Swift

    import InputMethodKit

    Availability

    Available in OS X v10.5 and later.

  • The opacity level for a candidates window.

    Declaration

    Swift

    var IMKCandidatesOpacityAttributeName: NSString!

    Objective-C

    extern const *NSString IMKCandidatesOpacityAttributeName;

    Constants

    • IMKCandidatesOpacityAttributeName

      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.