Mac Developer Library

Developer

Foundation Framework Reference NSKeyValueCoding Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSKeyValueCoding

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

  • Sets the value for the property identified by a given key path to a given value.

    Declaration

    Swift

    func setValue(_ value: AnyObject?, forKeyPath keyPath: String)

    Objective-C

    - (void)setValue:(id)value forKeyPath:(NSString *)keyPath

    Parameters

    value

    The value for the property identified by keyPath.

    keyPath

    A key path of the form relationship.property (with one or more relationships): for example “department.name” or “department.manager.lastName.”

    Discussion

    The default implementation of this method gets the destination object for each relationship using valueForKey:, and sends the final object a setValue:forKey: message.

    Special Considerations

    When using this method, and the destination object does not implement an accessor for the value, the default behavior is for that object to retain value rather than copy or assign value.

    Availability

    Available in OS X v10.3 and later.

  • Sets properties of the receiver with values from a given dictionary, using its keys to identify the properties.

    Declaration

    Swift

    func setValuesForKeysWithDictionary(_ keyedValues: [String : AnyObject])

    Objective-C

    - (void)setValuesForKeysWithDictionary:(NSDictionary<NSString *,id> *)keyedValues

    Parameters

    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.

    Discussion

    The default implementation invokes setValue:forKey: for each key-value pair, substituting nil for NSNull values in keyedValues.

    Availability

    Available in OS X v10.3 and later.

  • Invoked by setValue:forKey: when it’s given a nil value for a scalar value (such as an int or float).

    Declaration

    Swift

    func setNilValueForKey(_ key: String)

    Objective-C

    - (void)setNilValueForKey:(NSString *)key

    Parameters

    key

    The name of one of the receiver's properties.

    Discussion

    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.

    Availability

    Available in OS X v10.3 and later.

  • Sets the property of the receiver specified by a given key to a given value.

    Declaration

    Swift

    func setValue(_ value: AnyObject?, forKey key: String)

    Objective-C

    - (void)setValue:(id)value forKey:(NSString *)key

    Parameters

    value

    The value for the property identified by key.

    key

    The name of one of the receiver's properties.

    Discussion

    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.

    In a reference-counted environment, if the instance variable is accessed directly, value is retained.

    Availability

    Available in OS X v10.3 and later.

  • Invoked by setValue:forKey: when it finds no property for a given key.

    Declaration

    Swift

    func setValue(_ value: AnyObject?, forUndefinedKey key: String)

    Objective-C

    - (void)setValue:(id)value forUndefinedKey:(NSString *)key

    Parameters

    value

    The value for the key identified by key.

    key

    A string that is not equal to the name of any of the receiver's properties.

    Discussion

    Subclasses can override this method to handle the request in some other way. The default implementation raises an NSUndefinedKeyException.

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    class func accessInstanceVariablesDirectly() -> Bool

    Objective-C

    + (BOOL)accessInstanceVariablesDirectly

    Return Value

    YEStrue if the key-value coding methods should access the corresponding instance variable directly on finding no accessor method for a property, otherwise NOfalse.

    Discussion

    The default returns YEStrue. Subclasses can override it to return NOfalse, in which case the key-value coding methods won’t access instance variables.

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the value specified by a given pointer is valid for the property identified by a given key.

    Declaration

    Swift

    func validateValue(_ ioValue: AutoreleasingUnsafeMutablePointer<AnyObject?>, forKey inKey: String) throws

    Objective-C

    - (BOOL)validateValue:(inout id _Nullable *)ioValue forKey:(NSString *)key error:(out NSError * _Nullable *)outError

    Parameters

    ioValue

    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.

    key

    The name of one of the receiver's properties. The key must specify an attribute or a to-one relationship.

    outError

    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.

    Return Value

    YES if *ioValue is a valid value for the property identified by key, or if the method is able to modify the value to *ioValue to make it valid; otherwise NOfalse.

    Discussion

    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, YEStrue is returned.

    The sender of the message is never given responsibility for releasing ioValue or outError.

    See Key-Value Validation for more information.

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func validateValue(_ ioValue: AutoreleasingUnsafeMutablePointer<AnyObject?>, forKeyPath inKeyPath: String) throws

    Objective-C

    - (BOOL)validateValue:(inout id _Nullable *)ioValue forKeyPath:(NSString *)key error:(out NSError * _Nullable *)outError

    Parameters

    ioValue

    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.

    key

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

    outError

    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.

    Discussion

    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.

    Availability

    Available in OS X v10.3 and later.

  • Returns YEStrue if the stored value methods storedValueForKey: and takeStoredValue:forKey: should use private accessor methods in preference to public accessors.

    Deprecation Statement

    This method has no direct replacement, although see accessInstanceVariablesDirectly.

    Declaration

    Objective-C

    + (BOOL)useStoredAccessor

    Discussion

    Returning NOfalse causes the stored value methods to use the same accessor method or instance variable search order as the corresponding basic key-value coding methods (valueForKey: and takeValue:forKey:). The default implementation returns YEStrue.

    Applications should use the valueForKey: and setValue:forKey: methods instead of storedValueForKey: and takeStoredValue:forKey:.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

  • Invoked by valueForKey: when it finds no property corresponding to key.

    Deprecation Statement

    Use valueForUndefinedKey: instead.

    Declaration

    Objective-C

    - (id)handleQueryWithUnboundKey:(NSString *)key

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • Invoked by takeValue:forKey: when it finds no property binding for key.

    Deprecation Statement

    Use setValue:forUndefinedKey: instead.

    Declaration

    Objective-C

    - (void)handleTakeValue:(id)value forUnboundKey:(NSString *)key

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • Returns the property identified by a given key.

    Deprecation Statement

    If you are using the NSManagedObject class, use primitiveValueForKey: instead.

    Declaration

    Objective-C

    - (id)storedValueForKey:(NSString *)key

    Discussion

    This method is used when the value is retrieved for storage in an object store (generally, this storage is ultimately in a database) or for inclusion in a snapshot. The default implementation is similar to the implementation of valueForKey:, but it resolves key with a different method/instance variable search order:

    1. Searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of “lastName”, storedValueForKey: looks for a method named _getLastName or _lastName.

    2. If a private accessor is not found, searches for an instance variable based on key and returns its value directly. For example, with a key of “lastName”, storedValueForKey: looks for an instance variable named _lastName or lastName.

    3. If neither a private accessor nor an instance variable is found, storedValueForKey: searches for a public accessor method based on key. For the key “lastName”, this would be getLastName or lastName.

    4. If key is unknown, storedValueForKey: calls handleTakeValue:forUnboundKey:.

    This different search order allows an object to bypass processing that is performed before returning a value through a public API. However, if you always want to use the search order in valueForKey:, you can implement the class method useStoredAccessor to return NOfalse. And as with valueForKey:, you can prevent direct access of an instance variable with the class method accessInstanceVariablesDirectly.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

  • Sets the value of the property identified by a given key.

    Deprecation Statement

    If you are using the NSManagedObject class, use setPrimitiveValue:forKey: instead.

    Declaration

    Objective-C

    - (void)takeStoredValue:(id)value forKey:(NSString *)key

    Discussion

    This method is used to initialize the receiver with values from an object store (generally, this storage is ultimately from a database) or to restore a value from a snapshot. The default implementation is similar to the implementation of takeValue:forKey:, but it resolves key with a different method/instance variable search order:

    1. Searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of “lastName”, takeStoredValue:forKey: looks for a method named _setLastName:.

    2. If a private accessor is not found, searches for an instance variable based on key and sets its value directly. For example, with a key of “lastName”, takeStoredValue:forKey: looks for an instance variable named _lastName or lastName.

    3. If neither a private accessor nor an instance variable is found, takeStoredValue:forKey: searches for a public accessor method based on key. For the key “lastName”, this would be setLastName:.

    4. If key is unknown, takeStoredValue:forKey: calls handleTakeValue:forUnboundKey:.

    This different search order allows an object to bypass processing that is performed before setting a value through a public API. However, if you always want to use the search order in takeValue:forKey:, you can implement the class method useStoredAccessor to return NOfalse. And as with valueForKey:, you can prevent direct access of an instance variable with the class method accessInstanceVariablesDirectly.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

  • Sets properties of the receiver with values from a given dictionary, using its keys to identify the properties

    Deprecation Statement

    Use setValuesForKeysWithDictionary: instead.

    Declaration

    Objective-C

    - (void)takeValuesFromDictionary:(NSDictionary *)properties

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • Sets the value for the property identified by keyPath to value.

    Deprecation Statement

    Use setValue:forKeyPath: instead.

    Declaration

    Objective-C

    - (void)takeValue:(id)value forKeyPath:(NSString *)keyPath

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • Sets the value for the property identified by key to value.

    Deprecation Statement

    Use setValue:forKey: instead.

    Declaration

    Objective-C

    - (void)takeValue:(id)value forKey:(NSString *)key

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • Invoked if key is represented by a scalar attribute.

    Deprecation Statement

    Use setNilValueForKey: instead.

    Declaration

    Objective-C

    - (void)unableToSetNilForKey:(NSString *)key

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • - valuesForKeys: (OS X v10.3)

    Returns a dictionary containing as keys the property names in keys, with corresponding values being the corresponding property values.

    Deprecation Statement

    Use dictionaryWithValuesForKeys: instead.

    Declaration

    Objective-C

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.3.

  • This constant defines the name of an exception raised when a key value coding operation fails.

    Declaration

    Swift

    let NSUndefinedKeyException: String

    Objective-C

    extern NSString *NSUndefinedKeyException;

    Constants

    • NSUndefinedKeyException

      NSUndefinedKeyException

      Raised when a key value coding operation fails. userInfo keys are described in NSUndefinedKeyException userInfo Keys

      Available in OS X v10.3 and later.

  • These constants are keys into an NSUndefinedKeyException userInfo dictionary

    Declaration

    Objective-C

    extern NSString *NSTargetObjectUserInfoKey; extern NSString *NSUnknownUserInfoKey;

    Constants

    • NSTargetObjectUserInfoKey

      The object on which the key value coding operation failed.

    • NSUnknownUserInfoKey

      The key for which the key value coding operation failed.

    Discussion

    For additional information see Key Value Coding Exception Names.

  • These constants define the available array operators. See Set and Array Operators for more information.

    Declaration

    Swift

    let NSAverageKeyValueOperator: String let NSCountKeyValueOperator: String let NSDistinctUnionOfArraysKeyValueOperator: String let NSDistinctUnionOfObjectsKeyValueOperator: String let NSDistinctUnionOfSetsKeyValueOperator: String let NSMaximumKeyValueOperator: String let NSMinimumKeyValueOperator: String let NSSumKeyValueOperator: String let NSUnionOfArraysKeyValueOperator: String let NSUnionOfObjectsKeyValueOperator: String let NSUnionOfSetsKeyValueOperator: String

    Objective-C

    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;

    Constants

    • NSAverageKeyValueOperator

      NSAverageKeyValueOperator

      The @avg array operator.

      Available in OS X v10.4 and later.

    • NSCountKeyValueOperator

      NSCountKeyValueOperator

      The @count array operator.

      Available in OS X v10.4 and later.

    • NSDistinctUnionOfArraysKeyValueOperator

      NSDistinctUnionOfArraysKeyValueOperator

      The @distinctUnionOfArrays array operator.

      Available in OS X v10.4 and later.

    • NSDistinctUnionOfObjectsKeyValueOperator

      NSDistinctUnionOfObjectsKeyValueOperator

      The @distinctUnionOfObjects array operator.

      Available in OS X v10.4 and later.

    • NSDistinctUnionOfSetsKeyValueOperator

      NSDistinctUnionOfSetsKeyValueOperator

      The @distinctUnionOfSets array operator.

      Available in OS X v10.4 and later.

    • NSMaximumKeyValueOperator

      NSMaximumKeyValueOperator

      The @max array operator.

      Available in OS X v10.4 and later.

    • NSMinimumKeyValueOperator

      NSMinimumKeyValueOperator

      The @min array operator.

      Available in OS X v10.4 and later.

    • NSSumKeyValueOperator

      NSSumKeyValueOperator

      The @sum array operator.

      Available in OS X v10.4 and later.

    • NSUnionOfArraysKeyValueOperator

      NSUnionOfArraysKeyValueOperator

      The @unionOfArrays array operator.

      Available in OS X v10.4 and later.

    • NSUnionOfObjectsKeyValueOperator

      NSUnionOfObjectsKeyValueOperator

      The @unionOfObjects array operator.

      Available in OS X v10.4 and later.

    • NSUnionOfSetsKeyValueOperator

      NSUnionOfSetsKeyValueOperator

      The @unionOfSets array operator.

      Available in OS X v10.4 and later.

    Availability

    Available in OS X version 10.4 and later.