---

NSTokenFieldCell Class Reference

Overview

NSTokenFieldCell is a subclass of NSTextFieldCell that provides tokenized editing of an array of objects similar to the address field in Mail.app. The objects may be strings or objects that can be represented as strings.

Tasks

Managing the Token Style

• – setTokenStyle:
• – tokenStyle

Managing the Tokenizing Character Set

• + defaultTokenizingCharacterSet
• – setTokenizingCharacterSet:
• – tokenizingCharacterSet

Configuring the Completion Delay

• – setCompletionDelay:
• – completionDelay
• + defaultCompletionDelay

Managing the Delegate

• – delegate
• – setDelegate:

Displaying Tokenized Strings

• – tokenFieldCell:displayStringForRepresentedObject:  delegate method
• – tokenFieldCell:styleForRepresentedObject:  delegate method

Editing Tokenized Strings

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

Reading From and Writing to the Pasteboard

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

Managing Menus for Represented Objects

• – tokenFieldCell:hasMenuForRepresentedObject:  delegate method
• – tokenFieldCell:menuForRepresentedObject:  delegate method

Class Methods

defaultCompletionDelay

Returns the default completion delay.

+ (NSTimeInterval)defaultCompletionDelay

Return Value

The default completion delay.

Discussion

The default completion delay is 0.

Availability

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

Declared In

NSTokenFieldCell.h

defaultTokenizingCharacterSet

Returns the default tokenizing character set.

+ (NSCharacterSet *)defaultTokenizingCharacterSet

Return Value

The default tokenizing character set.

Discussion

The default tokenizing character set contains the single character “,”.

Availability

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

Declared In

NSTokenFieldCell.h

Instance Methods

completionDelay

Returns the receiver’s completion delay.

- (NSTimeInterval)completionDelay

Return Value

The receiver’s completion delay.

Availability

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

See Also

• – setCompletionDelay:
• + defaultCompletionDelay

Declared In

NSTokenFieldCell.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver’s delegate.

Availability

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

See Also

• – setDelegate:

Declared In

NSTokenFieldCell.h

setCompletionDelay:

Sets the receiver’s completion delay to a given delay.

- (void)setCompletionDelay:(NSTimeInterval)delay

Parameters

delay

The delay for the receiver.

Availability

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

See Also

• – completionDelay

Declared In

NSTokenFieldCell.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Parameters

anObject

The delegate for the receiver.

Availability

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

See Also

• – delegate

Declared In

NSTokenFieldCell.h

setTokenizingCharacterSet:

Sets the receiver’s tokenizing character set to a given character set.

- (void)setTokenizingCharacterSet:(NSCharacterSet *)characterSet

Parameters

characterSet

The tokenizing character set for the receiver.

Availability

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

See Also

• – tokenizingCharacterSet

Declared In

NSTokenFieldCell.h

setTokenStyle:

Sets the token style of the receiver.

- (void)setTokenStyle:(NSTokenStyle)style

Parameters

style

The token style for the receiver.

Availability

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

See Also

• – tokenStyle

Declared In

NSTokenFieldCell.h

tokenizingCharacterSet

Returns the receiver’s tokenizing character set.

- (NSCharacterSet *)tokenizingCharacterSet

Return Value

The receiver’s tokenizing character set.

Availability

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

See Also

• – setTokenizingCharacterSet:
• + defaultTokenizingCharacterSet

Declared In

NSTokenFieldCell.h

tokenStyle

Returns the receiver’s token style.

- (NSTokenStyle)tokenStyle

Return Value

The receiver’s token style.

Availability

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

See Also

• – setTokenStyle:

Declared In

NSTokenFieldCell.h

Delegate Methods

tokenFieldCell:completionsForSubstring:indexOfToken:indexOfSelectedItem:

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

- (NSArray *)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell completionsForSubstring:(NSString *)substring indexOfToken:(NSInteger)tokenIndex indexOfSelectedItem:(NSInteger *)selectedIndex

Parameters

tokenFieldCell

The token field cell sending the message to the delegate.

substring

The partial string that to be completed.

tokenIndex

The index of the token being edited.

selectedIndex

You may return by reference an index in the returned array that specifies which of the completions should be initially selected. If you do not want an initial selection, return NULL.

Return Value

An array of strings for completing substring.

Discussion

The default behavior provides no completions.

Availability

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

Declared In

NSTokenFieldCell.h

tokenFieldCell:displayStringForRepresentedObject:

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

- (NSString *)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell displayStringForRepresentedObject:(id)representedObject

Discussion

If you return nil or do not implement this method, then representedObject is displayed as the string.

Availability

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

Declared In

NSTokenFieldCell.h

tokenFieldCell:editingStringForRepresentedObject:

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

- (NSString *)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell editingStringForRepresentedObject:(id)representedObject

Discussion

If you return nil or do not implement this method, then the value returned by tokenFieldCell:displayStringForRepresentedObject: is used for editing.

Availability

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

Declared In

NSTokenFieldCell.h

tokenFieldCell:hasMenuForRepresentedObject:

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

- (BOOL)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell hasMenuForRepresentedObject:(id)representedObject

Discussion

By default tokens have no menus.

Availability

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

Declared In

NSTokenFieldCell.h

tokenFieldCell:menuForRepresentedObject:

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

- (NSMenu *)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell menuForRepresentedObject:(id)representedObject

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

NSTokenFieldCell.h

tokenFieldCell:readFromPasteboard:

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

- (NSArray *)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell readFromPasteboard:(NSPasteboard *)pboard

Availability

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

Declared In

NSTokenFieldCell.h

tokenFieldCell:representedObjectForEditingString:

Allows the delegate to provide a represented object for the string being edited.

- (id)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell representedObjectForEditingString:(NSString *)editingString

Parameters

tokenFieldCell

The token field cell sending the message to the delegate.

editingString

The string being edited.

Return Value

A represented object associated with editingString.

Discussion

If your application uses some object other than an NSString object 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

NSTokenFieldCell.h

tokenFieldCell:shouldAddObjects:atIndex:

Allows the delegate to validate the tokens to be added to the receiver at a given index.

- (NSArray *)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell shouldAddObjects:(NSArray *)tokens atIndex:(NSUInteger)index

Parameters

tokenFieldCell

The token field cell sending the message to the delegate.

tokens

An array of tokens to be added to the receiver.

index

The index in the receiver where the tokens are to be added.

Return Value

An array of validated tokens.

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

NSTokenFieldCell.h

tokenFieldCell:styleForRepresentedObject:

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

- (NSTokenStyle)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell styleForRepresentedObject:(id)representedObject

Discussion

The delegate should return NSDefaultTokenStyle, NSPlainTextTokenStyle or NSRoundedTokenStyle.

Availability

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

Declared In

NSTokenFieldCell.h

tokenFieldCell:writeRepresentedObjects:toPasteboard:

Allows the delegate the opportunity to write custom pasteboard types to the pasteboard for the represented objects in objects.

- (BOOL)tokenFieldCell:(NSTokenFieldCell *)tokenFieldCell writeRepresentedObjects:(NSArray *)objects toPasteboard:(NSPasteboard *)pboard

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

NSTokenFieldCell.h

Constants

NSTokenStyle

The NSTokenStyle type provides storage for values defined in “NSTokenStyle Values”.

typedef NSUInteger NSTokenStyle;

Availability

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

Declared In

NSTokenFieldCell.h

NSTokenStyle Values

The NSTokenStyle constants define how tokens are displayed and editable in the NSTokenFieldCell. These values are used by tokenStyle, setTokenStyle: and the delegate method tokenFieldCell:styleForRepresentedObject:.

enum {
   NSDefaultTokenStyle,
   NSPlainTextTokenStyle,
   NSRoundedTokenStyle
};

Constants

NSDefaultTokenStyle

Style best used for keyword type tokens.

Available in Mac OS X v10.4 and later.

Declared in NSTokenFieldCell.h

NSPlainTextTokenStyle

Style to use for data you want represented as plain-text and without any token background.

Available in Mac OS X v10.4 and later.

Declared in NSTokenFieldCell.h

NSRoundedTokenStyle

Style best used for address type tokens.

Available in Mac OS X v10.4 and later.

Declared in NSTokenFieldCell.h

Declared In

NSTokenFieldCell.h

---