# NSKeyValueCoding informal protocol reference

rfm@gnu.org
Generated at 2025-12-02 21:52:00 +0000
2000,2002 Free Software Foundation, Inc.
Software documentation for the NSObject(NSKeyValueCoding) informal protocol
Foundation/NSKeyValueCoding.h

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.

accessInstanceVariablesDirectly
Controls whether the NSKeyValueCoding methods may attempt to access instance variables directly. NSObject's implementation returns `YES`.
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`.
dictionaryWithValuesForKeys:
keys
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:
aKey
Deprecated... use -valueForUndefinedKey: instead.
handleTakeValue:
anObject
forUnboundKey:
aKey
Deprecated, use -setValue:forUndefinedKey: instead.
mutableArrayValueForKey:
aKey
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:
aKey
Returns a mutable array value for the given key path.
mutableSetValueForKey:
aKey
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:
aKey
Returns a mutable set value for the given key path.
setNilValueForKey:
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.)
setValue:
anObject
forKey:
aKey
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:
anObject
forKeyPath:
aKey
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:
anObject
forUndefinedKey:
aKey
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:
aDictionary
Uses -setValue:forKey: to place the values from aDictionary in the receiver.
storedValueForKey:
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: _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:
anObject
forKey:
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: _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:
aDictionary
Iterates over the dictionary invoking -takeStoredValue:forKey: on the receiver for each key-value pair, converting NSNull to `nil`.
takeValue:
anObject
forKey:
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: 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:
anObject
forKeyPath:
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 delimited by '.'. If the key path doesn't contain any '.', this method simply invokes -takeValue:forKey: .
Deprecated... use -setValue:forKeyPath: instead.
takeValuesFromDictionary:
aDictionary
Iterates over the dictionary invoking -takeValue:forKey: on the receiver for each key-value pair, converting NSNull to `nil`.
Deprecated... use -setValuesForKeysWithDictionary: instead.
unableToSetNilForKey:
aKey
Deprecated... use -setNilValueForKey: instead.
validateValue:
aValue
forKey:
aKey
error:
anError
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:
aValue
forKeyPath:
aKey
error:
anError
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:
aKey
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:
aKey
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:
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 NSUndefinedKeyException, with a userInfo dictionary containing NSTargetObjectUserInfoKey with the receiver an NSUnknownUserInfoKey with the supplied key entries.
valuesForKeys:
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.