Up

NSKeyValueCoding informal protocol reference

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Version: 27183

Date: 2008-12-01 18:38:58 +0000 (Mon, 01 Dec 2008)

Copyright: (C) 2000,2002 Free Software Foundation, Inc.

Software documentation for the NSObject(NSKeyValueCoding) informal protocol

NSObject(NSKeyValueCoding)

Declared in:
Foundation/NSKeyValueCoding.h
Availability: MacOS-X 10.0.0

This describes an informal protocol for key-value coding, a mechanism whereby the fields of an object may be accessed and set using generic methods in conjunction with string keys rather than field-specific methods. Key-based access loses compile-time validity checking, but can be convenient in certain kinds of situations.

The basic methods are implemented as a category of the NSObject class, but other classes override those default implementations to perform more specific operations.

Method summary

accessInstanceVariablesDirectly 

+ (BOOL) accessInstanceVariablesDirectly;
Availability: MacOS-X 10.0.0

Controls whether the NSKeyValueCoding methods may attempt to access instance variables directly. NSObject's implementation returns YES.

useStoredAccessor 

+ (BOOL) useStoredAccessor;
Availability: MacOS-X 10.0.0

Controls whether -storedValueForKey: and -takeStoredValue:forKey: may use the stored accessor mechanism. If not the calls get redirected to -valueForKey: and -takeValue:forKey: effectively changing the search order of private/public accessor methods and instance variables. NSObject's implementation returns YES.

dictionaryWithValuesForKeys: 

- (NSDictionary*) dictionaryWithValuesForKeys: (NSArray*)keys;
Availability: MacOS-X 10.0.0

Returns a dictionary built from values obtained for the specified keys.
By default this is derived by calling -valueForKey: for each key. Any nil values obtained are represented by an NSNull instance.

handleQueryWithUnboundKey: 

- (id) handleQueryWithUnboundKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Deprecated... use -valueForUndefinedKey: instead.

handleTakeValue: forUnboundKey: 

- (void) handleTakeValue: (id)anObject forUnboundKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Deprecated, use -setValue:forUndefinedKey: instead.

mutableArrayValueForKey: 

- (NSMutableArray*) mutableArrayValueForKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns a mutable array value for a given key. This method:
  • Searches the receiver for methods matching the patterns insertObject:in<Key>AtIndex: and removeObjectFrom<Key>AtIndex:. If both methods are found, each message sent to the proxy array will result in the invocation of one or more of these methods. If replaceObjectIn<Key>AtIndex:withObject: is also found in the receiver it will be used when appropriate for better performance.
  • If the set of methods is not found, searches the receiver for a the method set<Key>:. Each message sent to the proxy array will result in the invocation of set<Key>:
  • If the previous do not match, and accessInstanceVariablesDirectly returns YES, searches for an instance variable matching _<key> or <key> (in that order). If the instance variable is found, messages sent to the proxy object will be forwarded to the instance variable.
  • If none of the previous are found, raises an NSUndefinedKeyException

mutableArrayValueForKeyPath: 

- (NSMutableArray*) mutableArrayValueForKeyPath: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns a mutable array value for the given key path.

mutableSetValueForKey: 

- (NSMutableSet*) mutableSetValueForKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns a mutable set value for a given key. This method:
  • Searches the receiver for methods matching the patterns add<Key>Object:, remove<Key>Object:, add<Key>:, and remove<Key>:, which correspond to the NSMutableSet methods addObject:, removeObject:, unionSet:, and minusSet:, respectively. If at least one addition and one removal method are found, each message sent to the proxy set will result in the invocation of one or more of these methods. If intersect<Key>: or set<Key>: is also found in the receiver, the method(s) will be used when appropriate for better performance.
  • If the set of methods is not found, searches the receiver for a the method set<Key>:. Each message sent to the proxy set will result in the invocation of set<Key>:
  • If the previous do not match, and accessInstanceVariablesDirectly returns YES, searches for an instance variable matching _<key> or <key> (in that order). If the instance variable is found, messages sent to the proxy object will be forwarded to the instance variable.
  • If none of the previous are found, raises an NSUndefinedKeyException

mutableSetValueForKeyPath: 

- (NSMutableSet*) mutableSetValueForKeyPath: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns a mutable set value for the given key path.

setNilValueForKey: 

- (void) setNilValueForKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

This method is invoked by the NSKeyValueCoding mechanism when an attempt is made to set an null value for a scalar attribute. This implementation raises an NSInvalidArgument exception. Subclasses my override this method to do custom handling. (E.g. setting the value to the equivalent of 0.)

setValue: forKey: 

- (void) setValue: (id)anObject forKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Sets the value if the attribute associated with the key in the receiver. The object is converted to a scalar attribute where applicable (and -setNilValueForKey: is called if a nil value is supplied). Tries to use a standard accessor of the form setKey: where 'Key' is the supplied argument with the first letter converted to uppercase.
If the receiver's class allows +accessInstanceVariablesDirectly it continues with instance variables:
  • _key
  • _isKey
  • key
  • isKey
Invokes -setValue:forUndefinedKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accessor method doesn't take exactly one argument or the type is unsupported (e.g. structs). If the receiver expects a scalar value and the value supplied is the NSNull instance or nil, this method invokes -setNilValueForKey: .

setValue: forKeyPath: 

- (void) setValue: (id)anObject forKeyPath: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Retrieves the object returned by invoking -valueForKey: on the receiver with the first key component supplied by the key path. Then invokes -setValue:forKeyPath: recursively on the returned object with rest of the key path. The key components are delimited by '.'. If the key path doesn't contain any '.', this method simply invokes -setValue:forKey: .

setValue: forUndefinedKey: 

- (void) setValue: (id)anObject forUndefinedKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Invoked when -setValue:forKey: / -takeStoredValue:forKey: are called with a key which can't be associated with an accessor method or instance variable. Subclasses may override this method to add custom handling. NSObject raises an NSUndefinedKeyException, with a userInfo dictionary containing NSTargetObjectUserInfoKey with the receiver an NSUnknownUserInfoKey with the supplied key entries.
Called when the key passed to -setValue:forKey: cannot be used.

setValuesForKeysWithDictionary: 

- (void) setValuesForKeysWithDictionary: (NSDictionary*)aDictionary;
Availability: MacOS-X 10.0.0

Uses -setValue:forKey: to place the values from aDictionary in the receiver.

storedValueForKey: 

- (id) storedValueForKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns the value associated with the supplied key as an object. Scalar attributes are converted to corresponding objects. Uses private accessors in favor of the public ones, if the receiver's class allows +useStoredAccessor . Otherwise this method invokes -valueForKey: . The search order is:
Private accessor methods:
  • _getKey
  • _key
If the receiver's class allows +accessInstanceVariablesDirectly it continues with instance variables:
  • _key
  • key
Public accessor methods:
  • getKey
  • key
Invokes -handleTakeValue:forUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accessor method takes takes any arguments or the type is unsupported (e.g. structs).

takeStoredValue: forKey: 

- (void) takeStoredValue: (id)anObject forKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Sets the value associated with the supplied in the receiver. The object is converted to the scalar attribute where applicable. Uses the private accessors in favor of the public ones, if the receiver's class allows +useStoredAccessor . Otherwise this method invokes -takeValue:forKey: . The search order is:
Private accessor methods:
  • _setKey:
If the receiver's class allows accessInstanceVariablesDirectly it continues with instance variables:
  • _key
  • key
Public accessor methods:
  • setKey:
Invokes -handleTakeValue:forUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accessor method doesn't take exactly one argument or the type is unsupported (e.g. structs). If the receiver expects a scalar value and the value supplied is the NSNull instance or nil, this method invokes -unableToSetNilForKey: .

takeStoredValuesFromDictionary: 

- (void) takeStoredValuesFromDictionary: (NSDictionary*)aDictionary;
Availability: MacOS-X 10.0.0

Iterates over the dictionary invoking -takeStoredValue:forKey: on the receiver for each key-value pair, converting NSNull to nil.

takeValue: forKey: 

- (void) takeValue: (id)anObject forKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Sets the value if the attribute associated with the key in the receiver. The object is converted to a scalar attribute where applicable. Uses the public accessors in favor of the private ones. The search order is:
Accessor methods:
  • setKey:
  • _setKey:
If the receiver's class allows +accessInstanceVariablesDirectly it continues with instance variables:
  • key
  • _key
Invokes -handleTakeValue:forUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accessor method doesn't take exactly one argument or the type is unsupported (e.g. structs). If the receiver expects a scalar value and the value supplied is the NSNull instance or nil, this method invokes -unableToSetNilForKey: .
Deprecated... use -setValue:forKey: instead.

takeValue: forKeyPath: 

- (void) takeValue: (id)anObject forKeyPath: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Retrieves the object returned by invoking -valueForKey: on the receiver with the first key component supplied by the key path. Then invokes -takeValue:forKeyPath: recursively on the returned object with rest of the key path. The key components are delimited by '.'. If the key path doesn't contain any '.', this method simply invokes -takeValue:forKey: .
Deprecated... use -setValue:forKeyPath: instead.

takeValuesFromDictionary: 

- (void) takeValuesFromDictionary: (NSDictionary*)aDictionary;
Availability: MacOS-X 10.0.0

Iterates over the dictionary invoking -takeValue:forKey: on the receiver for each key-value pair, converting NSNull to nil.
Deprecated... use -setValuesForKeysWithDictionary: instead.

unableToSetNilForKey: 

- (void) unableToSetNilForKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Deprecated... use -setNilValueForKey: instead.

validateValue: forKey: error: 

- (BOOL) validateValue: (id*)aValue forKey: (NSString*)aKey error: (NSError**)anError;
Availability: MacOS-X 10.0.0

Returns a boolean indicating whether the object pointed to by aValue is valid for setting as an attribute of the receiver using the name aKey. On success (YES response) it may return a new value to be used in aValue. On failure (NO response) it may return an error in anError.
The method works by calling a method of the receiver whose name is of the form validateKey:error: if the receiver has implemented such a method, otherwise it simply returns YES.

validateValue: forKeyPath: error: 

- (BOOL) validateValue: (id*)aValue forKeyPath: (NSString*)aKey error: (NSError**)anError;
Availability: MacOS-X 10.0.0

Returns the result of calling -validateValue:forKey:error: on the receiver using aPath to determine the key value in the same manner as the -valueForKeyPath: method.

valueForKey: 

- (id) valueForKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns the value associated with the supplied key as an object. Scalar attributes are converted to corresponding objects.
The search order is:
Accessor methods:
  • getKey
  • key
If the receiver's class allows +accessInstanceVariablesDirectly it continues with private accessors:
  • _getKey
  • _key
and then instance variables:
  • key
  • _key
Invokes -setValue:forUndefinedKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accessor method takes any arguments or the type is unsupported (e.g. structs).

valueForKeyPath: 

- (id) valueForKeyPath: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Returns the object returned by invoking -valueForKeyPath: recursively on the object returned by invoking -valueForKey: on the receiver with the first key component supplied by the key path. The key components are delimited by '.'. If the key path doesn't contain any '.', this method simply invokes -valueForKey: .

valueForUndefinedKey: 

- (id) valueForUndefinedKey: (NSString*)aKey;
Availability: MacOS-X 10.0.0

Invoked when -valueForKey: / -storedValueForKey: are called with a key, which can't be associated with an accessor method or instance variable. Subclasses may override this method to add custom handling. NSObject raises an NSUndefinedKeyException, with a userInfo dictionary containing NSTargetObjectUserInfoKey with the receiver an NSUnknownUserInfoKey with the supplied key entries.

valuesForKeys: 

- (NSDictionary*) valuesForKeys: (NSArray*)keys;
Availability: MacOS-X 10.0.0

Iterates over the array sending the receiver -valueForKey: for each object in the array and inserting the result in a dictionary. All nil values returned by -valueForKey: are replaced by the NSNull instance in the dictionary.


Up