Up

NSKeyValueCoding informal protocol reference

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Version: 1.11

Date: 2005/02/22 11:22:44

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

Software documentation for the NSObject(NSKeyValueCoding) informal protocol

NSObject(NSKeyValueCoding)

Declared in:
Foundation/NSKeyValueCoding.h
Standards:

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;

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


useStoredAccessor 

+ (BOOL) useStoredAccessor;

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.


handleQueryWithUnboundKey: 

- (id) handleQueryWithUnboundKey: (NSString*)aKey;

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 NSUnknownKeyException, with a userInfo dictionary containing NSTargetObjectUserInfoKey with the receiver an NSUnknownUserInfoKey with the supplied key entries.


handleTakeValue: forUnboundKey: 

- (void) handleTakeValue: (id)anObject forUnboundKey: (NSString*)aKey;

Invoked when -takeValue: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 NSUnknownKeyException, with a userInfo dictionary containing NSTargetObjectUserInfoKey with the receiver an NSUnknownUserInfoKey with the supplied key entries.


storedValueForKey: 

- (id) storedValueForKey: (NSString*)aKey;

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:

If the receiver's class allows +accessInstanceVariablesDirectly it continues with instance variables: Public accessor methods: Invokes -handleQueryWithUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accesor method takes takes any arguments or the type is unsupported (e.g. structs).


takeStoredValue: forKey: 

- (void) takeStoredValue: (id)anObject forKey: (NSString*)aKey;

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:

If the receiver's class allows accessInstanceVariablesDirectly it continues with instance variables: Public accessor methods: Invokes -handleTakeValue:forUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accesor 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;

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;

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:

If the receiver's class allows +accessInstanceVariablesDirectly it continues with instance variables: Invokes -handleTakeValue:forUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accesor 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: .


takeValue: forKeyPath: 

- (void) takeValue: (id)anObject forKeyPath: (NSString*)aKey;

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 delimated by '.'. If the key path doesn't contain any '.', this method simply invokes -takeValue:forKey: .


takeValuesFromDictionary: 

- (void) takeValuesFromDictionary: (NSDictionary*)aDictionary;

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


unableToSetNilForKey: 

- (void) unableToSetNilForKey: (NSString*)aKey;

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


valueForKey: 

- (id) valueForKey: (NSString*)aKey;

Returns the value associated with the supplied key as an object. Scalar attributes are converted to corresponding objects. The value-NSKeyValueCoding use the public accessors in favor of the private ones. The search order is:
Accessor methods:

If the receiver's class allows +accessInstanceVariablesDirectly it continues with instance variables: Invokes -handleQueryWithUnboundKey: if no accessor mechanism can be found and raises NSInvalidArgumentException if the accesor method takes any arguments or the type is unsupported (e.g. structs).


valueForKeyPath: 

- (id) valueForKeyPath: (NSString*)aKey;

Retuns 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 delimated by '.'. If the key path doesn't contain any '.', this method simply invokes -valueForKey: .


valuesForKeys: 

- (NSDictionary*) valuesForKeys: (NSArray*)keys;

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