Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Key-value coding is a mechanism for indirectly accessing an object’s attributes and relationships using string identifiers. It underpins or is related to several mechanisms and technologies special to Cocoa programming, among them Core Data, application scriptability, the bindings technology, and the language feature of declared properties. (Scriptability and bindings are specific to Cocoa on OS X.) You can also use key-value coding to simplify your program code.
Object Properties and KVC
Central to key-value coding (or KVC) is the general notion of properties. A property refers to a unit of state that an object encapsulates. A property can be one of two general types: an attribute (for example,
textColor) or a relationship to other objects. Relationships can be either to-one or to-many. The value for a to-many relationship is typically an array or set, depending on whether the relationship is ordered or unordered.
KVC locates an object’s property through a key, which is a string identifier. A key usually corresponds to the name of an accessor method or instance variable defined by the object. The key must conform to certain conventions: It must be ASCII encoded, begin with a lowercase letter, and have no whitespace. A key path is a string of dot-separated keys that is used to specify a sequence of object properties to traverse. The property of the first key in the sequence is relative to a specific object (
employee1 in the following diagram), and each subsequent key is evaluated relative to the value of the previous property.
Making a Class KVC Compliant
NSKeyValueCoding informal protocol makes KVC possible. Two of its methods—
setValue:forKey:—are particularly important because they fetch and set a property’s value when given its key.
NSObject provides a default implementation of these methods, and if a class is compliant with key-value coding, it can rely on this implementation.
How you make a property KVC compliant depends on whether that property is an attribute, a to-one relationship, or a to-many relationship. For attributes and to-one relationships, a class must implement at least one of the following in the given order of preference (key refers to the property key):
The class has a declared property with the name key.
It implements accessor methods named key and, if the property is mutable,
:. (If the property is a Boolean attribute, the getter accessor method has the form
It declares an instance variable of the form key or
Implementing KVC compliance for a to-many relationship is a more complicated procedure. Refer to the document that definitively describes key-value coding to learn what this procedure is.