Next Page >

Hide TOC

NSDictionaryController Class Reference

Inherits from	NSArrayController : NSObjectController : NSController : NSObject
Conforms to	NSCoding (NSController) NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in Mac OS X v10.5 and later.
Companion guide	Cocoa Bindings Programming Topics
Declared in	NSDictionaryController.h NSKeyValueBinding.h

Overview

NSDictionaryController is a bindings compatible class that manages display and editing of the contents of an NSDictionary object. NSDictionaryController transforms the contents of a dictionary into an array of key-value pairs that can be bound to user interface items such as the columns of an NSTableView.

The content of an NSDictionaryController instance is specified using the inherited method setContent: or by binding an NSDictionary instance to the contentDictionary binding. New key/value pairs inserted into the dictionary are created using the newObject method. The initial key name is set to the string returned by initialKey (specified using setInitialKey: or the initialKey binding). The initial value object is set to the object returned by initialValue (specified using setInitialValue: or the initialValue binding). The initial key name is copied to the newly inserted object, while the object returned by initialValue is simply retained. As new items are inserted the controller enumerates the initial key name, resulting in key names such as “key”, “key1”, “key2”, and so on. This behavior can be customized by overriding newObject.

An NSDictionaryController instance can be configured to exclude specified keys in a dictionary from being returned by arrangedObjects using the setExcludedKeys: method or by binding an array of key names to the excludedKeys binding. Similarly, you can specify an array of key names that are always included in the arranged objects, even if they are not present in the content dictionary, using the setIncludedKeys: method or the includedKeys binding.

NSDictionaryController supports providing localized key names for the keys in the dictionary, allowing a user-friendly representation of the key name to be displayed. The localized key names are specified by a dictionary (using setLocalizedKeyDictionary: or the localizedKeyDictionary binding) or by providing a strings table (using setLocalizedKeyTable:).

The arrangedObjects method returns an array of objects that implement the NSDictionaryControllerKeyValuePair informal protocol. User interface controls are bound to the arranged objects array using key paths such as: arrangedObjects.key (displays the key name), arrangedObjects.value (displays the value for the key), or arrangedObjects.localizedKey (displays the localized key name). See NSDictionaryControllerKeyValuePair Protocol Reference for more information.

Note: You must enable the “Validates Immediately” option for the value binding of all controls that edit the key names or values returned by arrangedObjects.

Adopted Protocols

NSCoding

Tasks

Arranging Objects

Creating New Entries

Localizing Key Names

Keys to Display

Setting Initial Key and Values

Instance Methods

arrangedObjects

Returns an array containing the objects that represent the receiver’s content.

This method is invoked for insertions of new key-value pairs, as well as transforming existing dictionary entries into key-value pairs for display. Objects returned by this method must implement the NSDictionaryControllerKeyValuePair informal protocol.

Special Considerations

Subclass implementations must ensure that the object returned by newObject is not autorelased.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

setExcludedKeys:

Sets the key names that are never displayed in the user interface items bound to the receiver.

- (void)setExcludedKeys:(NSArray *)keys

Parameters

keys: An array containing the key names.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

setIncludedKeys:

Sets the key names that are represented by a key-value pair, even if they are not present in the receiver’s content dictionary.

- (void)setIncludedKeys:(NSArray *)keys

Parameters

keys: An array containing the key names.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

setInitialKey:

Sets the string used as the initial key name for a newly inserted item.

- (void)setInitialKey:(NSString *)key

Parameters

key: The key name. The string is copied by the receiver.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

setInitialValue:

Sets the string used as the initial value for a newly inserted item.

- (void)setInitialValue:(id)value

Parameters

value: The initial value.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

setLocalizedKeyDictionary:

Sets the localized key names that are displayed by the receiver in place of the key names.

- (void)setLocalizedKeyDictionary:(NSDictionary *)dictionary

Parameters

dictionary: A dictionary containing the localized key name strings.

Discussion

The dictionary contains the key names as the keys, and the localized key names as the corresponding values.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

setLocalizedKeyTable:

Specifies the strings file used to localize key names.

- (void)setLocalizedKeyTable:(NSString *)stringsFile

Parameters

stringsFile: Specifies the string table to use when localizing key names.

Discussion

The string table must reside within the application’s resource . See Strings Files in Introduction to Internationalization Programming Topics.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSDictionaryController.h

Constants

Exposed Bindings

The following constants are used to specify a binding to bind:toObject:withKeyPath:options:, infoForBinding:, unbind:, and valueClassForBinding:. See the Cocoa Bindings Reference for more information.

NSString *NSContentDictionaryBinding;
NSString *NSIncludedKeysBinding;
NSString *NSExcludedKeysBinding;
NSString *NSLocalizedKeyDictionaryBinding;
NSString *NSInitialKeyBinding;
NSString *NSInitialValueBinding;