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 |
Overview
The NSTokenFieldDelegate protocol defines the optional methods implemented by delegates of NSTokenField objects.
Tasks
Displaying Tokenized Strings
Editing a Tokenized Strings
-
– tokenField:completionsForSubstring:indexOfToken:indexOfSelectedItem: -
– tokenField:editingStringForRepresentedObject: -
– tokenField:representedObjectForEditingString: -
– tokenField:shouldAddObjects:atIndex:
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.
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.htokenField:displayStringForRepresentedObject:
Allows the delegate to provide a string to be displayed as a proxy for the given represented object.
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.htokenField:editingStringForRepresentedObject:
Allows the delegate to provide a string to be edited as a proxy for a represented object.
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.htokenField:hasMenuForRepresentedObject:
Allows the delegate to specify whether the given represented object provides a menu.
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.htokenField:menuForRepresentedObject:
Allows the delegate to provide a menu for the specified represented object.
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.htokenField:readFromPasteboard:
Allows the delegate to return an array of objects representing the data read from the specified pasteboard.
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.htokenField:representedObjectForEditingString:
Allows the delegate to provide a represented object for the given editing string.
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.htokenField:shouldAddObjects:atIndex:
Allows the delegate to validate the tokens to be added to the receiver at a particular location.
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.htokenField:styleForRepresentedObject:
Allows the delegate to return the token style for editing the specified represented object.
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.htokenField:writeRepresentedObjects:toPasteboard:
Sent so the delegate can write represented objects to the pasteboard corresponding to a given array of display strings.
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.
See Also
Declared In
NSTokenField.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-05-25)