<!--
{
  "availability" : [
    "macOS: 10.5.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "InputMethodKit",
  "identifier" : "/documentation/InputMethodKit/IMKCandidates",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "InputMethodKit"
    ],
    "preciseIdentifier" : "c:objc(cs)IMKCandidates"
  },
  "title" : "IMKCandidates"
}
-->

# IMKCandidates

The `IMKCandidates` class presents candidates to users and notifies the appropriate [`IMKInputController`](/documentation/InputMethodKit/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.

```
class IMKCandidates
```

## Overview

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.

## Topics

### Initializing a Candidates Window

[`init(server:panelType:)`](/documentation/InputMethodKit/IMKCandidates/init(server:panelType:))

Returns the initialized `IMKCandidates` object.

### Managing Selection Keys

[`setSelectionKeys(_:)`](/documentation/InputMethodKit/IMKCandidates/setSelectionKeys(_:))

Sets the selection keys for the candidates.

[`selectionKeys()`](/documentation/InputMethodKit/IMKCandidates/selectionKeys())

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

[`setSelectionKeysKeylayout(_:)`](/documentation/InputMethodKit/IMKCandidates/setSelectionKeysKeylayout(_:))

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

[`selectionKeysKeylayout()`](/documentation/InputMethodKit/IMKCandidates/selectionKeysKeylayout())

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

### Managing Window Visibility and Behavior

[`show(_:)`](/documentation/InputMethodKit/IMKCandidates/show(_:))

Shows the candidates window.

[`hide()`](/documentation/InputMethodKit/IMKCandidates/hide())

Hides a candidates window, if it is visible.

[`isVisible()`](/documentation/InputMethodKit/IMKCandidates/isVisible())

Returns whether or not the candidates window is visible.

[`setDismissesAutomatically(_:)`](/documentation/InputMethodKit/IMKCandidates/setDismissesAutomatically(_:))

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

[`dismissesAutomatically()`](/documentation/InputMethodKit/IMKCandidates/dismissesAutomatically())

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

[`update()`](/documentation/InputMethodKit/IMKCandidates/update())

Updates the candidates that are displayed in the candidates window.

### Managing Window Type and Text Attributes

[`panelType()`](/documentation/InputMethodKit/IMKCandidates/panelType())

Returns the style of the candidates window.

[`setPanelType(_:)`](/documentation/InputMethodKit/IMKCandidates/setPanelType(_:))

Sets the style of the candidates window.

[`setAttributes(_:)`](/documentation/InputMethodKit/IMKCandidates/setAttributes(_:))

Sets the style attributes for the candidates window.

[`attributes()`](/documentation/InputMethodKit/IMKCandidates/attributes())

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

### Showing an Annotation Window

[`showAnnotation(_:)`](/documentation/InputMethodKit/IMKCandidates/showAnnotation(_:))

Displays an annotation string in an annotation window.

### Constants

[`IMKCandidatePanelType`](/documentation/InputMethodKit/IMKCandidatePanelType)

Types of candidates windows provide by the Input Method Kit.

[`IMKCandidatesLocationHint`](/documentation/InputMethodKit/IMKCandidatesLocationHint)

Hints that suggest where to place the candidates window.

  <doc:imkcandidatesopacityattributename>

### Initializers

[`init(server:panelType:styleType:)`](/documentation/InputMethodKit/IMKCandidates/init(server:panelType:styleType:))

### Instance Methods

[`attachChild(_:toCandidate:type:)`](/documentation/InputMethodKit/IMKCandidates/attachChild(_:toCandidate:type:))

[`candidateFrame()`](/documentation/InputMethodKit/IMKCandidates/candidateFrame())

[`candidateIdentifier(atLineNumber:)`](/documentation/InputMethodKit/IMKCandidates/candidateIdentifier(atLineNumber:))

[`candidateStringIdentifier(_:)`](/documentation/InputMethodKit/IMKCandidates/candidateStringIdentifier(_:))

[`clearSelection()`](/documentation/InputMethodKit/IMKCandidates/clearSelection())

[`detachChild(_:)`](/documentation/InputMethodKit/IMKCandidates/detachChild(_:))

[`hideChild()`](/documentation/InputMethodKit/IMKCandidates/hideChild())

[`lineNumberForCandidate(withIdentifier:)`](/documentation/InputMethodKit/IMKCandidates/lineNumberForCandidate(withIdentifier:))

[`selectCandidate(_:)`](/documentation/InputMethodKit/IMKCandidates/selectCandidate(_:))

[`selectCandidate(withIdentifier:)`](/documentation/InputMethodKit/IMKCandidates/selectCandidate(withIdentifier:))

[`selectedCandidate()`](/documentation/InputMethodKit/IMKCandidates/selectedCandidate())

[`selectedCandidateString()`](/documentation/InputMethodKit/IMKCandidates/selectedCandidateString())

[`setCandidateData(_:)`](/documentation/InputMethodKit/IMKCandidates/setCandidateData(_:))

[`setCandidateFrameTopLeft(_:)`](/documentation/InputMethodKit/IMKCandidates/setCandidateFrameTopLeft(_:))

[`show()`](/documentation/InputMethodKit/IMKCandidates/show())

[`showChild()`](/documentation/InputMethodKit/IMKCandidates/showChild())

[`showSublist(_:subListDelegate:)`](/documentation/InputMethodKit/IMKCandidates/showSublist(_:subListDelegate:))


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)