NSDictionaryController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.5 and later.
Companion guide
Declared in
NSDictionaryController.h
NSKeyValueBinding.h
Related sample code

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.

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.

- (id)arrangedObjects
Return Value

An array of objects that implement the NSDictionaryControllerKeyValuePair informal protocol. See NSDictionaryControllerKeyValuePair Protocol Reference for more information.

excludedKeys

Returns an array containing the key names that are never displayed in the user interface items bound to the receiver.

- (NSArray *)excludedKeys
Return Value

An array containing the key names.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSDictionaryController.h

includedKeys

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

- (NSArray *)includedKeys
Return Value

An array containing the key names.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSDictionaryController.h

initialKey

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

- (NSString *)initialKey
Return Value

The key name.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSDictionaryController.h

initialValue

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

- (id)initialValue
Return Value

The value.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSDictionaryController.h

localizedKeyDictionary

Returns the receiver’s localization dictionary.

- (NSDictionary *)localizedKeyDictionary
Return Value

A dictionary containing localized string values for the key names.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSDictionaryController.h

localizedKeyTable

Returns the strings file used to localize key names.

- (NSString *)localizedKeyTable
Return Value

A string that specifies the string table to use when localizing key names.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSDictionaryController.h

newObject

Creates and returns a new key-value pair to represent an entry in the content dictionary.

- (id)newObject
Return Value

An object that represents the key-value pair. The object must not be autoreleased, and must implement the NSDictionaryControllerKeyValuePair informal protocol

Discussion

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 autoreleased.

Availability
  • Available in 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 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 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 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 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 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 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;
Constants
NSContentDictionaryBinding

A dictionary used as the content dictionary.

Available in OS X v10.5 and later.

Declared in NSKeyValueBinding.h.

NSIncludedKeysBinding

An array containing the key-value pairs always represented by the receiver.

Available in OS X v10.5 and later.

Declared in NSKeyValueBinding.h.

NSExcludedKeysBinding

An array containing the key names that are never displayed in the user interface items bound to the receiver.

Available in OS X v10.5 and later.

Declared in NSKeyValueBinding.h.

NSLocalizedKeyDictionaryBinding

A dictionary containing the localized key names that are displayed by the receiver in place of the key names.

Available in OS X v10.5 and later.

Declared in NSKeyValueBinding.h.

NSInitialKeyBinding

A string used as the initial key name for newly inserted items.

Available in OS X v10.5 and later.

Declared in NSKeyValueBinding.h.

NSInitialValueBinding

A string used as the initial value for newly inserted items.

Available in OS X v10.5 and later.

Declared in NSKeyValueBinding.h.

Declared In
AppKit/NSDictionaryController.h