NSTokenFieldCellDelegate Protocol Reference
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.6 and later. |
| Companion guide | |
| Declared in | NSTokenFieldCell.h |
Overview
The NSTokenFieldCellDelegate protocol defines the optional methods implemented by delegates of NSTokenFieldCell objects.
Tasks
Displaying Tokenized Strings
Editing a Tokenized Strings
-
– tokenFieldCell:completionsForSubstring:indexOfToken:indexOfSelectedItem: -
– tokenFieldCell:editingStringForRepresentedObject: -
– tokenFieldCell:representedObjectForEditingString: -
– tokenFieldCell:shouldAddObjects:atIndex:
Reading To and Writing From the Pasteboard
Managing Menus for Represented Objects
Instance Methods
tokenFieldCell:completionsForSubstring:indexOfToken:indexOfSelectedItem:
Allows the delegate to provide an array of appropriate completions for the contents of the receiver.
Parameters
- tokenFieldCell
The token field cell that sent the message.
- 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
NSTokenFieldCell.htokenFieldCell:displayStringForRepresentedObject:
Allows the delegate to provide a string to be displayed as a proxy for the represented object.
Parameters
- tokenFieldCell
The token field cell that sent the message.
- representedObject
A represented object of the token field cell.
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
NSTokenFieldCell.htokenFieldCell:editingStringForRepresentedObject:
Allows the delegate to provide a string to be edited as a proxy for the represented object.
Parameters
- tokenFieldCell
The token field cell 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
NSTokenFieldCell.htokenFieldCell:hasMenuForRepresentedObject:
Allows the delegate to specify whether the represented object provides a menu.
Parameters
- tokenFieldCell
The token field cell 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 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
NSTokenFieldCell.htokenFieldCell:menuForRepresentedObject:
Allows the delegate to provide a menu for the specified represented object.
Parameters
- tokenFieldCell
The token field cell 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 cell 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
NSTokenFieldCell.htokenFieldCell:readFromPasteboard:
Allows the delegate to return an array of objects representing the data read from pboard.
Parameters
- tokenFieldCell
The token field cell 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
NSTokenFieldCell.htokenFieldCell:representedObjectForEditingString:
Allows the delegate to provide a represented object for the string being edited.
Parameters
- tokenFieldCell
The token field cell 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
NSTokenFieldCell.htokenFieldCell:shouldAddObjects:atIndex:
Allows the delegate to validate the tokens to be added to the receiver at a given index.
Parameters
- tokenFieldCell
The token field cell 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
NSTokenFieldCell.htokenFieldCell:styleForRepresentedObject:
Allows the delegate to return the token style for editing the specified represented object.
Parameters
- tokenFieldCell
The token field cell that sent the message.
- representedObject
A represented object of the token field cell.
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 cell’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
NSTokenFieldCell.htokenFieldCell:writeRepresentedObjects:toPasteboard:
Allows the delegate the opportunity to write custom pasteboard types to the pasteboard for the represented objects in objects.
Parameters
- tokenFieldCell
The token field cell that sent the message.
- objects
An array of represented objects associated with the token field cell.
- 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
NSTokenFieldCell.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-05-06)