2.2 Key-Value Coding

Key-value coding lets you access the properties of an object (such as the instance variables) indirectly by using strings referred to as keys. Although key-value coding can access instance variables directly, it first tries to use accessor methods to access a property. However, accessor methods are not necessarily mapped to instance variables, which means that an accessor may provide a property value that is computed (perhaps from instance variables).

Key-value coding is a powerful feature of Cocoa that forms the basis of many important technologies. For example, Cocoa's scripting capability is heavily based on the functionality of key-value coding.

The methods that provide an interface to key-value coding are declared in the Foundation framework's NSKeyValueCoding protocol. The principal methods are valueForKey: and takeValue:forKey:, which get and set the instance variable associated with the specified key. NSObject provides default implementations of the methods of NSKeyValueCoding. These default implementations associate keys with instance variables based on a simple set of rules. The methods that return a value, valueForKey: for instance, attempt to access the property specified by the string @"key" using the following means:

A public accessor of either the form key or getKey.
A private accessor method of either the form _key or _getKey.
An instance variable named either key or _key.
Finally, if none of these first three attempts results in anything, the method invokes handleQueryWithUnboundKey:. The default implementation raises an exception; classes may choose to provide another implementation suitable to their needs.

Methods that set the values of properties, such as takeValue:forKey:, attempt to access those properties in a similar fashion, assuming again that the key is the string @"key":

A public accessor of the form setKey:.
A private accessor of the form _setKey:.
An instance variable named either key or _key.
Finally, if none of these first three rules results in anything, the methods invoke handleTakeValue:forKey:. The default implementation raises an exception; classes may choose to provide another implementation suitable to their needs.

Example 2-24 shows the interface for a class with three instance variables, a public accessor to one of the instance variables, and a private accessor to another.

Example 2-24. Using key-value coding in a class called KVExample

@interface KVExample : NSObject {
    id property1;
    id property2;
    id property3;
}
- (id)property1;    // Public accessor; could be getProperty1
- (id)_property2;   // The private accessor; could be _getProperty2
@end

@implementation KVExample
- (id)init
{
    self = [super init];
    
    if ( self ) {
        property1 = @"Property 1";
        property2 = @"Property 2";
        property3 = @"Property 3";
    }
    return self;
}

// These two methods return instance variable values
- (id)property1
{
    return property1;
}

- (id)_property2
{
    return property2;
}

// This method returns a property value that is computed,
// rather than stored in an instance variable
-(NSArray *)allProperties
{
    return [NSArray arrayWithObjects:property1, property2, property3, nil];
}
@end

Example 2-25 shows how to access each accessor using the key-value coding interface.

Example 2-25. Accessing properties of a class using key-value coding

id kv = [[KVExample alloc] init];

NSLog( [kv valueForKey:@"property1"];    // Prints "Property 1"
NSLog( [kv valueForKey:@"property2"];    // Prints "Property 2"
NSLog( [kv valueForKey:@"property3"];    // Prints "Property 3"

// Prints "{Property1, Property2, Property 3}"
NSLog( [kv valueForKey:@"allProperties"]);