(informal protocol)
Framework | /System/Library/Frameworks/Foundation.framework |
Companion guide | |
Declared in | NSKeyValueCoding.h |
The NSKeyValueCoding
informal protocol defines a mechanism by which you can access the properties of an object indirectly by name (or key), rather than directly through invocation of an accessor method or as instance variables. Thus, all of an object’s properties can be accessed in a consistent manner.
The basic methods for accessing an object’s values are setValue:forKey:
, which sets the value for the property identified by the specified key, and valueForKey:
, which returns the value for the property identified by the specified key. The default implementation uses the accessor methods normally implemented by objects (or to access instance variables directly if need be).
– valueForKey:
– valueForKeyPath:
– dictionaryWithValuesForKeys:
– valueForUndefinedKey:
– mutableArrayValueForKey:
– mutableArrayValueForKeyPath:
– mutableSetValueForKey:
– mutableSetValueForKeyPath:
– setValue:forKeyPath:
– setValuesForKeysWithDictionary:
– setNilValueForKey:
– setValue:forKey:
– setValue:forUndefinedKey:
– handleQueryWithUnboundKey:
Deprecated in Mac OS X v10.3
– handleTakeValue:forUnboundKey:
Deprecated in Mac OS X v10.3
– takeValue:forKey:
Deprecated in Mac OS X v10.3
– takeValue:forKeyPath:
Deprecated in Mac OS X v10.3
– takeValuesFromDictionary:
Deprecated in Mac OS X v10.3
– unableToSetNilForKey:
Deprecated in Mac OS X v10.3
– valuesForKeys:
Deprecated in Mac OS X v10.3
+ useStoredAccessor
Deprecated in Mac OS X v10.4
– storedValueForKey:
Deprecated in Mac OS X v10.4
– takeStoredValue:forKey:
Deprecated in Mac OS X v10.4
Returns a Boolean value that indicates whether the key-value coding methods should access the corresponding instance variable directly on finding no accessor method for a property.
+ (BOOL)accessInstanceVariablesDirectly
YES
if the key-value coding methods should access the corresponding instance variable directly on finding no accessor method for a property, otherwise NO
.
The default returns YES
. Subclasses can override it to return NO
, in which case the key-value coding methods won’t access instance variables.
NSKeyValueCoding.h
Returns a dictionary containing the property values identified by each of the keys in a given array.
- (NSDictionary *)dictionaryWithValuesForKeys:(NSArray *)keys
An array containing NSString
objects that identify properties of the receiver.
A dictionary containing as keys the property names in keys, with corresponding values being the corresponding property values.
The default implementation invokes valueForKey:
for each key in keys and substitutes NSNull
values in the dictionary for returned nil
values.
NSKeyValueCoding.h
Returns a mutable array proxy that provides read-write access to an ordered to-many relationship specified by a given key.
- (NSMutableArray *)mutableArrayValueForKey:(NSString *)key
The name of an ordered to-many relationship.
A mutable array proxy that provides read-write access to the ordered to-many relationship specified by key.
Objects added to the mutable array become related to the receiver, and objects removed from the mutable array become unrelated. The default implementation recognizes the same simple accessor methods and array accessor methods as valueForKey:
, and follows the same direct instance variable access policies, but always returns a mutable collection proxy object instead of the immutable collection that valueForKey:
would return.
The search pattern that mutableArrayValueForKey:
uses is described in Accessor Search Implementation Details in Key-Value Coding Programming Guide.
NSKeyValueCoding.h
Returns a mutable array that provides read-write access to the ordered to-many relationship specified by a given key path.
- (NSMutableArray *)mutableArrayValueForKeyPath:(NSString *)keyPath
A key path, relative to the receiver, to an ordered to-many relationship.
A mutable array that provides read-write access to the ordered to-many relationship specified by keyPath.
See mutableArrayValueForKey:
for additional details.
NSKeyValueCoding.h
Returns a mutable set proxy that provides read-write access to the unordered to-many relationship specified by a given key.
- (NSMutableSet *)mutableSetValueForKey:(NSString *)key
The name of an unordered to-many relationship.
A mutable set that provides read-write access to the unordered to-many relationship specified by key.
Objects added to the mutable set proxy become related to the receiver, and objects removed from the mutable set become unrelated. The default implementation recognizes the same simple accessor methods and set accessor methods as valueForKey:
, and follows the same direct instance variable access policies, but always returns a mutable collection proxy object instead of the immutable collection that valueForKey:
would return.
The search pattern that mutableSetValueForKey:
uses is described in Accessor Search Implementation Details in Key-Value Coding Programming Guide.
NSKeyValueCoding.h
Returns a mutable set that provides read-write access to the unordered to-many relationship specified by a given key path.
- (NSMutableSet *)mutableSetValueForKeyPath:(NSString *)keyPath
A key path, relative to the receiver, to an unordered to-many relationship.
A mutable set that provides read-write access to the unordered to-many relationship specified by keyPath.
See mutableSetValueForKey:
for additional details.
NSKeyValueCoding.h
Invoked by setValue:forKey:
when it’s given a nil
value for a scalar value (such as an int
or float
).
- (void)setNilValueForKey:(NSString *)key
The name of one of the receiver's properties.
Subclasses can override this method to handle the request in some other way, such as by substituting 0
or a sentinel value for nil
and invoking setValue:forKey:
again or setting the variable directly. The default implementation raises an NSInvalidArgumentException
.
NSKeyValueCoding.h
Sets the property of the receiver specified by a given key to a given value.
- (void)setValue:(id)value forKey:(NSString *)key
The value for the property identified by key.
The name of one of the receiver's properties.
If key identifies a to-one relationship, relate the object specified by value to the receiver, unrelating the previously related object if there was one. Given a collection object and a key that identifies a to-many relationship, relate the objects contained in the collection to the receiver, unrelating previously related objects if there were any.
The search pattern that setValue:forKey:
uses is described in Accessor Search Implementation Details in Key-Value Coding Programming Guide.
NSKeyValueCoding.h
Sets the value for the property identified by a given key path to a given value.
- (void)setValue:(id)value forKeyPath:(NSString *)keyPath
The value for the property identified by keyPath.
A key path of the form relationship.property (with one or more relationships): for example “department.name” or “department.manager.lastName.”
The default implementation of this method gets the destination object for each relationship using valueForKey:
, and sends the final object a setValue:forKey:
message.
NSKeyValueCoding.h
Invoked by setValue:forKey:
when it finds no property for a given key.
- (void)setValue:(id)value forUndefinedKey:(NSString *)key
The value for the key identified by key.
A string that is not equal to the name of any of the receiver's properties.
Subclasses can override this method to handle the request in some other way. The default implementation raises an NSUndefinedKeyException
.
NSKeyValueCoding.h
Sets properties of the receiver with values from a given dictionary, using its keys to identify the properties.
- (void)setValuesForKeysWithDictionary:(NSDictionary *)keyedValues
A dictionary whose keys identify properties in the receiver. The values of the properties in the receiver are set to the corresponding values in the dictionary.
The default implementation invokes setValue:forKey:
for each key-value pair, substituting nil
for NSNull
values in keyedValues.
NSKeyValueCoding.h
Returns a Boolean value that indicates whether the value specified by a given pointer is valid for the property identified by a given key.
- (BOOL)validateValue:(id *)ioValue forKey:(NSString *)key error:(NSError **)outError
A pointer to a new value for the property identified by key. This method may modify or replace the value in order to make it valid.
The name of one of the receiver's properties. The key must specify an attribute or a to-one relationship.
If validation is necessary and ioValue is not transformed into a valid value, upon return contains an NSError
object that describes the reason that ioValue is not a valid value.
YES if *ioValue is a valid value for the property identified by key, or of the method is able to modify the value to *ioValue to make it valid; otherwise NO
.
The default implementation of this method searches the class of the receiver for a validation method whose name matches the pattern validate
<Key>:error:
. If such a method is found it is invoked and the result is returned. If no such method is found, YES
is returned.
The sender of the message is never given responsibility for releasing ioValue or outError.
See “Key-Value Validation” for more information.
NSKeyValueCoding.h
Returns a Boolean value that indicates whether the value specified by a given pointer is valid for a given key path relative to the receiver.
- (BOOL)validateValue:(id *)ioValue forKeyPath:(NSString *)inKeyPath error:(NSError **)outError
A pointer to a new value for the property identified by keyPath. This method may modify or replace the value in order to make it valid.
The name of one of the receiver's properties. The key path must specify an attribute or a to-one relationship. The key path has the form relationship.property (with one or more relationships); for example “department.name” or “department.manager.lastName”.
If validation is necessary and ioValue is not transformed into a valid value, upon return contains an NSError
object that describes the reason that ioValue is not a valid value.
The default implementation gets the destination object for each relationship using valueForKey:
and returns the result of a validateValue:forKey:error:
message to the final object.
NSKeyValueCoding.h
Returns the value for the property identified by a given key.
- (id)valueForKey:(NSString *)key
The name of one of the receiver's properties.
The value for the property identified by key.
The search pattern that valueForKey:
uses to find the correct value to return is described in Accessor Search Implementation Details in Key-Value Coding Programming Guide.
NSKeyValueCoding.h
Returns the value for the derived property identified by a given key path.
- (id)valueForKeyPath:(NSString *)keyPath
A key path of the form relationship.property (with one or more relationships); for example “department.name” or “department.manager.lastName”.
The value for the derived property identified by keyPath.
The default implementation gets the destination object for each relationship using valueForKey:
and returns the result of a valueForKey:
message to the final object.
NSKeyValueCoding.h
Invoked by valueForKey:
when it finds no property corresponding to a given key.
- (id)valueForUndefinedKey:(NSString *)key
A string that is not equal to the name of any of the receiver's properties.
Subclasses can override this method to return an alternate value for undefined keys. The default implementation raises an NSUndefinedKeyException
.
NSKeyValueCoding.h
This constant defines the name of an exception raised when a key value coding operation fails.
extern NSString *NSUndefinedKeyException;
NSUndefinedKeyException
Raised when a key value coding operation fails. userInfo keys are described in “NSUndefinedKeyException userInfo Keys”
Available in Mac OS X v10.3 and later.
Declared in NSKeyValueCoding.h
.
NSKeyValueCoding.h
These constants are keys into an NSUndefinedKeyException
userInfo dictionary
extern NSString *NSTargetObjectUserInfoKey; extern NSString *NSUnknownUserInfoKey;
NSTargetObjectUserInfoKey
The object on which the key value coding operation failed.
NSUnknownUserInfoKey
The key for which the key value coding operation failed.
For additional information see “Key Value Coding Exception Names.”
NSKeyValueCoding.h
These constants define the available array operators. See Set and Array Operators for more information.
NSString *const NSAverageKeyValueOperator; NSString *const NSCountKeyValueOperator; NSString *const NSDistinctUnionOfArraysKeyValueOperator; NSString *const NSDistinctUnionOfObjectsKeyValueOperator; NSString *const NSDistinctUnionOfSetsKeyValueOperator; NSString *const NSMaximumKeyValueOperator; NSString *const NSMinimumKeyValueOperator; NSString *const NSSumKeyValueOperator; NSString *const NSUnionOfArraysKeyValueOperator; NSString *const NSUnionOfObjectsKeyValueOperator; NSString *const NSUnionOfSetsKeyValueOperator;
NSAverageKeyValueOperator
The @avg
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSCountKeyValueOperator
The @count
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSDistinctUnionOfArraysKeyValueOperator
The @distinctUnionOfArrays
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSDistinctUnionOfObjectsKeyValueOperator
The @distinctUnionOfObjects
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSDistinctUnionOfSetsKeyValueOperator
The @distinctUnionOfSets
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSMaximumKeyValueOperator
The @max
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSMinimumKeyValueOperator
The @min
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSSumKeyValueOperator
The @sum
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSUnionOfArraysKeyValueOperator
The @unionOfArrays
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSUnionOfObjectsKeyValueOperator
The @unionOfObjects
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSUnionOfSetsKeyValueOperator
The @unionOfSets
array operator.
Available in Mac OS X v10.4 and later.
Declared in NSKeyValueCoding.h
.
NSKeyValueCoding.h
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-02-04)