rfm@gnu.org
)Version: 1.10
Date: 2004/09/19 23:24:36
Copyright: (C) 2000,2002 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSKeyValueCoding.h
Standards:
- MacOS-X
- NotOpenStep
- GNUstep
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
Controls whether the NSKeyValueCoding methods may
attempt to access instance variables directly.
NSObject's implementation returns
YES
.
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
.
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.
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.
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:
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:
nil
, this method
invokes
-unableToSetNilForKey:
.
Iterates over the dictionary invoking
-takeStoredValue:forKey:
on the receiver for each key-value pair, converting
NSNull to nil
.
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:
nil
, this method
invokes
-unableToSetNilForKey:
.
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: .
Iterates over the dictionary invoking
-takeValue:forKey:
on the receiver for each key-value pair, converting
NSNull to nil
.
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.)
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:
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: .
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.