NSTokenField Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.4 and later. |
| Companion guide | |
| Declared in | NSTokenField.h |
Overview
NSTokenField is a subclass of NSTextField that provides tokenized editing similar to the address field in the Mail application.
NSTokenField uses an NSTokenFieldCell to implement much of the control’s functionality. NSTokenField provides cover methods for most methods of NSTokenFieldCell, which invoke the corresponding cell method.
Notes: In Mac OS X v10.4 and earlier, represented objects associated with token fields had to conform to NSCoding. Starting with Mac OS X v10.5, they no longer need to.
NSTokenField trims whitespace around tokens but it does not trim whitespace in Mac OS X versions 10.5.0 and 10.5.1. In Mac OS X v10.5.2, you get whitespace-trimming behavior by either linking against the v10.4 binary or linking against the v10.5 binary and not implementing the tokenField:representedObjectForEditingString: method. If you do not want the whitespace-trimming behavior, link against the v10.5 binary and implement this method, returning the editing string if you have no represented object. Tasks
Configuring the Token Style
Configuring the Tokenizing Character Set
Configuring the Completion Delay
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.hInstance Methods
completionDelay
Returns the receiver’s completion delay.
- (NSTimeInterval)completionDelay
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSTokenField.hsetCompletionDelay:
Sets the receiver’s completion delay.
- (void)setCompletionDelay:(NSTimeInterval)delay
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSTokenField.hsetTokenizingCharacterSet:
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
Declared In
NSTokenField.hsetTokenStyle:
Returns the token style of the receiver.
- (void)setTokenStyle:(NSTokenStyle)style
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSTokenField.htokenizingCharacterSet
Returns the receiver’s tokenizing character set.
- (NSCharacterSet *)tokenizingCharacterSet
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSTokenField.htokenStyle
Returns the receiver’s token style.
- (NSTokenStyle)tokenStyle
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSTokenField.hDelegate 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 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.htokenField: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.
Availability
- Available in Mac OS X v10.4 and later.
Declared In
NSTokenField.htokenField: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
Discussion
If you return nil from this method, the token field is not editable.
Availability
- Available in Mac OS X v10.4 and later.
Declared In
NSTokenField.htokenField: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.htokenField: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.htokenField: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.htokenField:representedObjectForEditingString:
Allows the delegate to provide a represented object for the given editing string.
- (id)tokenField:(NSTokenField *)tokenField representedObjectForEditingString:(NSString *)editingString
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.
Note: In Mac OS X v10.4, NSTokenField trims whitespace around tokens but it does not trim whitespace in Mac OS X versions 10.5.0 and 10.5.1. In Mac OS X v10.5.2, you get whitespace-trimming behavior by either linking against the v10.4 binary or linking against the v10.5 binary and not implementing the this method. If you do not want the whitespace-trimming behavior, link against the v10.5 binary and implement this method, returning the editing string if you have no represented object.
Availability
- Available in Mac OS X v10.4 and later.
Declared In
NSTokenField.htokenField: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.htokenField: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.htokenField: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.
- 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 Mac OS X v10.4 and later.
Declared In
NSTokenField.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)