Introduction to Token Field Programming Guide for Cocoa

This document discusses the role of token fields in a user interface, explains how they work, describes how to configure them, and shows how to integrate them into your application.

Token Fields at a Glance

A token field is a text field with tokens as content. A token represents a string or other object.

• Construction: Single-cell control

• Classes and inheritance:

  • Control: NSTokenField : NSTextField : NSControl : NSView : NSResponder : NSObject

  • Cell: NSTokenFieldCell : NSTextFieldCell : NSActionCell : NSCell : NSObject

• Design patterns: Target-action, delegation, key-value observing

• Object attributes: Tokenizing character set, completion delay, token style

• Important methods: objectValue (NSControl), tokenField:completionsForSubstring:indexOfToken:indexOfSelectedItem: (delegate), tokenField:representedObjectForEditingString: (delegate), tokenField:displayStringForRepresentedObject:d (delegate), tokenField:menuForRepresentedObject: (delegate)

• Important bindings: value

• Usage guidelines: Under “Text Controls” in “UI Element Guidelines: Controls" (Apple Human Interface Guidelines)

Organization of This Document

This document consists of the following chapters:

• About Token Fields describes what token fields are designed to do in a user interface and offers some guidelines for their usage.

• How Token Fields Work discusses the central concepts and mechanisms of token fields.

• Configuring Token Fields explains how to configure token fields and connect them to other objects in an application.

• Displaying the Completion List describes how to display a list of possible completions for the currently entered substring.

• Returning Represented Objects shows how to return an array of represented objects for the tokens in a token field.

• Getting and Setting Token-Field Values shows how to extract and set the contents of a token field.

• Implementing Menus for Tokens discusses how to associate menus with tokens in a token field.