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

---