NSTokenFieldDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Declared in
NSTokenField.h
Related sample code

Overview

The NSTokenFieldDelegate protocol defines the optional methods implemented by delegates of NSTokenField objects.

Tasks

Displaying Tokenized Strings

Editing a Tokenized Strings

Reading To and Writing From the Pasteboard

Managing Menus for Represented Objects

Instance 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 by reference -1.

Return Value

An array of strings that are possible completions.

Discussion

If the delegate does not implement this method, no completions are provided.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 that sent the message.

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.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTokenField.h

tokenField:editingStringForRepresentedObject:

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

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

The token field that sent the message.

representedObject

A represented object of the token field.

Return Value

A string that’s an editable proxy of the represented object, or nil if the token should not be editable.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 that sent the message.

representedObject

A represented object of the token field.

Return Value

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

Discussion

By default tokens in a token field have no menus.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 that sent the message.

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 in a token field do not return menus.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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
Parameters
tokenField

The token field that sent the message.

pboard

The pasteboard from which to read the represented objects.

Return Value

An array of represented objects created from the pasteboard data.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTokenField.h

tokenField:representedObjectForEditingString:

Allows the delegate to provide a represented object for the given editing string.

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

The token field that sent the message.

editingString

The edited string representation of a represented object.

Return Value

A represented object that is displayed rather than the editing string.

Discussion

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 OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 that sent the message.

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

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 OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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
Parameters
tokenField

The token field that sent the message.

representedObject

A represented object of the token field.

Return Value

The style that should be used to display the representedObject. Possible values are shown in NSTokenStyle Values.

Discussion

If the delegate implements this method and returns an NSTokenStyle that differs from the style set by setTokenStyle:, the value the delegate returns is preferred.

If the delegate does not implement this method, the token field’s tokenStyle is used.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTokenField.h

tokenField:writeRepresentedObjects:toPasteboard:

Sent so the delegate can write represented objects to the pasteboard corresponding to a given array of display strings.

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

The token field that sent the message.

objects

An array of represented objects associated with the token field.

pboard

The pasteboard to which to write the represented objects.

Return Value

YES if the delegate writes the represented objects to the pasteboard, NO otherwise. If NO, the token field writes the display strings to the NSStringPboardType pasteboard.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTokenField.h