Up
Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Date: 2006-05-15 06:07:35 -0600 (Mon, 15 May 2006)
Copyright: (C) 2000,2002 Free Software Foundation, Inc.
- 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
+ (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
.
+ (BOOL)
useStoredAccessor;
Availability: MacOS-X 10.0.0
- (
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.
- (id)
handleQueryWithUnboundKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (void)
handleTakeValue: (id)anObject
forUnboundKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (
NSMutableArray*)
mutableArrayValueForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Not implemented... I don't know what this method is good for... do we need to copy MacOS-X and implement it?
- (
NSMutableArray*)
mutableArrayValueForKeyPath: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
Not implemented... I don't know what this method is good for... do we need to copy MacOS-X and implement it?
- (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.)
- (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:
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:
.
- (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:
.
- (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.
- (void)
setValuesForKeysWithDictionary: (
NSDictionary*)aDictionary;
Availability: MacOS-X 10.0.0
- (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:
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 accessor method takes takes any arguments or the type is unsupported (e.g. structs).
- (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:
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 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:
.
- (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
.
- (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:
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 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.
- (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.
- (void)
takeValuesFromDictionary: (
NSDictionary*)aDictionary;
Availability: MacOS-X 10.0.0
- (void)
unableToSetNilForKey: (
NSString*)aKey;
Availability: MacOS-X 10.0.0
- (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
.
- (BOOL)
validateValue: (id*)aValue
forKeyPath: (
NSString*)aKey
error: (
NSError**)anError;
Availability: MacOS-X 10.0.0
- (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:
If the receiver's class allows
+accessInstanceVariablesDirectly
it continues with private accessors:
and then instance variables:
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).
- (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:
.
- (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.
- (
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