---

NSTokenField Class Reference

Overview

NSTokenField is a subclass of NSTextField that provides tokenized editing similar to the address field in Mail.app.

NSTokenField uses an NSTokenFieldCell to implement much of the control’s functionality. NSTokenField provides cover methods for most of NSTokenFieldCell’s methods, which invoke the corresponding cell method.

Tasks

Configuring the Token Style

• – setTokenStyle:
• – tokenStyle

Configuring the Tokenizing Character Set

• – setTokenizingCharacterSet:
• – tokenizingCharacterSet
• + defaultTokenizingCharacterSet

Configuring the Completion Delay

• – setCompletionDelay:
• – completionDelay
• + defaultCompletionDelay

Displaying a Tokenized String

• – tokenField:displayStringForRepresentedObject:  delegate method
• – tokenField:styleForRepresentedObject:  delegate method

Editing a Tokenized String

• – tokenField:completionsForSubstring:indexOfToken:indexOfSelectedItem:  delegate method
• – tokenField:editingStringForRepresentedObject:  delegate method
• – tokenField:representedObjectForEditingString:  delegate method
• – tokenField:shouldAddObjects:atIndex:  delegate method

Reading To and Writing From the Pasteboard

• – tokenField:readFromPasteboard:  delegate method
• – tokenField:writeRepresentedObjects:toPasteboard:  delegate method

Providing a Menu

• – tokenField:hasMenuForRepresentedObject:  delegate method
• – tokenField:menuForRepresentedObject:  delegate method

Class Methods

defaultCompletionDelay

Returns the default completion delay.

+ (NSTimeInterval)defaultCompletionDelay

Discussion

The default completion delay is 0.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

defaultTokenizingCharacterSet

Returns the default tokenizing character set.

+ (NSCharacterSet *)defaultTokenizingCharacterSet

Discussion

The default tokenizing character set is “,”.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

Instance Methods

completionDelay

Returns the receiver’s completion delay.

- (NSTimeInterval)completionDelay

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setCompletionDelay:
• + defaultCompletionDelay

Declared In

NSTokenField.h

setCompletionDelay:

Sets the receiver’s completion delay.

- (void)setCompletionDelay:(NSTimeInterval)delay

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – completionDelay

Declared In

NSTokenField.h

setTokenizingCharacterSet:

Sets the recevier’s tokenizing character set to characterSet.

- (void)setTokenizingCharacterSet:(NSCharacterSet *)characterSet

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – tokenizingCharacterSet

Declared In

NSTokenField.h

setTokenStyle:

Returns the token style of the receiver.

- (void)setTokenStyle:(NSTokenStyle)style

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – tokenStyle

Declared In

NSTokenField.h

tokenizingCharacterSet

Returns the receiver’s tokenizing character set.

- (NSCharacterSet *)tokenizingCharacterSet

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTokenizingCharacterSet:
• + defaultTokenizingCharacterSet

Declared In

NSTokenField.h

tokenStyle

Returns the receiver’s token style.

- (NSTokenStyle)tokenStyle

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTokenStyle:

Declared In

NSTokenField.h

Delegate Methods

tokenField:completionsForSubstring:indexOfToken:indexOfSelectedItem:

Allows the delegate to provide an array of appropriate completions for the contents of the receiver.

- (NSArray *)tokenField:(NSTokenField *)tokenField completionsForSubstring:(NSString *)substring indexOfToken:(NSInteger)tokenIndex indexOfSelectedItem:(NSInteger *)selectedIndex

Parameters

tokenField

The token field where editing is occurring.

substring

The partial string that is to be completed.

tokenIndex

The index of the token being edited.

selectedIndex

Optionally, you can return by-reference an index into the returned array that specifies which of the completions should be initially selected. If none are to be selected, return NULL.

Return Value

An array of possible completions.

Discussion

The default behavior of this method provides no completions.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:displayStringForRepresentedObject:

Allows the delegate to provide a string to be displayed as a proxy for the given represented object.

- (NSString *)tokenField:(NSTokenField *)tokenField displayStringForRepresentedObject:(id)representedObject

Parameters

tokenField

The token field.

representedObject

A represented object of the token field.

Return Value

The string to be used as a proxy for representedObject. If you return nil or do not implement this method, then representedObject is displayed as the string.

Discussion

The represented object must implement the NSCoding protocol.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:editingStringForRepresentedObject:

Allows the delegate to provide a string to be edited as a proxy for the representedObject.

- (NSString *)tokenField:(NSTokenField *)tokenField editingStringForRepresentedObject:(id)representedObject

Discussion

If you return nil or do not implement this method, then the value returned by tokenField:displayStringForRepresentedObject: is used for editing. The represented object must implement the NSCoding protocol.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:hasMenuForRepresentedObject:

Allows the delegate to specify whether the given represented object provides a menu.

- (BOOL)tokenField:(NSTokenField *)tokenField hasMenuForRepresentedObject:(id)representedObject

Parameters

tokenField

The token field.

representedObject

A represented object of the token field.

Return Value

YES if the represented object has a menu, NO otherwise.

Discussion

By default tokens have no menus.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:menuForRepresentedObject:

Allows the delegate to provide a menu for the specified represented object.

- (NSMenu *)tokenField:(NSTokenField *)tokenField menuForRepresentedObject:(id)representedObject

Parameters

tokenField

The token field.

representedObject

A represented object of the token field.

Return Value

The menu associated with the represented object.

Discussion

The returned menu should be autoreleased. By default tokens do not return menus.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:readFromPasteboard:

Allows the delegate to return an array of objects representing the data read from the specified pasteboard.

- (NSArray *)tokenField:(NSTokenField *)tokenField readFromPasteboard:(NSPasteboard *)pboard

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:representedObjectForEditingString:

Allows the delegate to provide a represented object for editingString.

- (id)tokenField:(NSTokenField *)tokenField representedObjectForEditingString:(NSString *)editingString

Discussion

The represented object must implement the NSCoding protocol. If your application uses some object other than an NSString for their represented objects, you should return a new, autoreleased instance of that object from this method.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:shouldAddObjects:atIndex:

Allows the delegate to validate the tokens to be added to the receiver at a particular location.

- (NSArray *)tokenField:(NSTokenField *)tokenField shouldAddObjects:(NSArray *)tokens atIndex:(NSUInteger)index

Parameters

tokenField

The token field being validated.

tokens

An array of tokens to be inserted in the receiver at index.

index

The index of the receiver in which the array of tokens to be validated (tokens) will be inserted.

Return Value

The array of tokens to be inserted.

Discussion

The delegate can return the array unchanged or return a modified array of tokens. To reject the add completely, return an empty array. Returning nil causes an error.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:styleForRepresentedObject:

Allows the delegate to return the token style for editing the specified represented object.

- (NSTokenStyle)tokenField:(NSTokenField *)tokenField styleForRepresentedObject:(id)representedObject

Discussion

The delegate should return NSDefaultTokenStyle, NSPlainTextTokenStyle or NSRoundedTokenStyle.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

tokenField:writeRepresentedObjects:toPasteboard:

Sent so the delegate can write custom pasteboard types to the pasteboard for the given represented objects.

- (BOOL)tokenField:(NSTokenField *)tokenField writeRepresentedObjects:(NSArray *)objects toPasteboard:(NSPasteboard *)pboard

Parameters

tokenField

The token field.

objects

An array of represented objects associated with the token field.

pboard

The pasteboard to which to write the custom pasteboard types.

Return Value

YES if the operation succeeded, NO otherwise.

Discussion

The display strings for the represented objects have already been placed on the pasteboard as both NSStringPboardType and an array of NSString objects.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSTokenField.h

---