textField(_:textCompletionFor:)

Declaration

@MainActor func textField(_ textField: NSTextField, textCompletionFor item: Self.Item) -> String?

Parameters

• textField:

  The text field whose suggestions item may be highlighted or selected.

• item:

  The item that may be highlighted or selected.

Return Value

The full text to insert, including the matched partial word and its potential completion, or nil if no text completion should be used.

Discussion

This function may be used by the control to display a preview of the text that would appear if the highlighted item is selected. Additionally, the default implementation of textField(_:didSelect:) uses this function to inform what changes are made to the control’s text.

For example, given a user interface with a text field and suggestions menu that looks like:

        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
Recipe: ┃ apple│                       ┃
        ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
        ┌────────────────┐
        │ Applesauce     │
        │ Apple juice    │
        │ Apple pie      │
        └────────────────┘

where “│” denotes the text insertion point.

If this function returns "Applesauce" for the first suggestion item, when the first suggestion item is highlighted, the user interface will look like:

        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
Recipe: ┃ apple│sauce|                 ┃
        ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
        ┌────────────────┐
        │|Applesauce    |│
        │ Apple juice    │
        │ Apple pie      │
        └────────────────┘

where the text between “|” is shown as a preview in the field

Upon selection of that first suggestion item:

        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
Recipe: ┃ Applesauce                   ┃
        ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛