Key-Value Coding Extensions
Core Animation extends the NSKeyValueCoding
protocol as it pertains to the CAAnimation
and CALayer
classes. This extension adds default values for some keys, expands wrapping conventions, and adds key path support for CGPoint
, CGRect
, CGSize
, and CATransform3D
types.
Key-Value Coding Compliant Container Classes
The CAAnimation
and CALayer
classes are key-value coding compliant container classes, which means that you can set values for arbitrary keys. Even if the key someKey
is not a declared property of the CALayer
class, you can still set a value for it as follows:
[theLayer setValue:[NSNumber numberWithInteger:50] forKey:@"someKey"]; |
You can also retrieve the value for arbitrary keys like you would retrieve the value for other key paths. For example, to retrieve the value of the someKey
path set previously, you would use the following code:
someKeyValue=[theLayer valueForKey:@"someKey"]; |
Default Value Support
Core Animation adds a convention to key value coding whereby a class can provide a default value for a key that has no set value. The CAAnimation
and CALayer
classes support this convention using the defaultValueForKey:
class method.
To provide a default value for a key, create a subclass of the desired class and override its defaultValueForKey:
method. Your implementation of this method should examine the key parameter and return the appropriate default value. Listing C-1 shows a sample implementation of the defaultValueForKey:
method for a layer object that provides a default value for the masksToBounds
property.
Listing C-1 Example implementation of defaultValueForKey:
+ (id)defaultValueForKey:(NSString *)key |
{ |
if ([key isEqualToString:@"masksToBounds"]) |
return [NSNumber numberWithBool:YES]; |
return [super defaultValueForKey:key]; |
} |
Wrapping Conventions
When the data for a key consists of a scalar value or C data structure, you must wrap that type in an object before assigning it to the layer. Similarly, when accessing that type, you must retrieve an object and then unwrap the appropriate values using the extensions to the appropriate class. Table C-1 lists the C types commonly used and the Objective-C class you use to wrap them.
C type | Wrapping class |
---|---|
| |
| |
| |
|
Key Path Support for Structures
The CAAnimation
and CALayer
classes lets you access the fields of selected data structures using key paths. This feature is a convenient way to specify the field of a data structure that you want to animate. You can also use these conventions in conjunction with the setValue:forKeyPath:
and valueForKeyPath:
methods to set and get those fields.
CATransform3D Key Paths
You can use the enhanced key path support to retrieve specific transformation values for a property that contains a CATransform3D
data type. To specify the full key path for a layer’s transforms, you would use the string value transform
or sublayerTransform
followed by one of the field key paths in Table C-2. For example, to specify a rotation factor around the layer’s z axis, you would specify the key path transform.rotation.z
.
Field Key Path | Description |
---|---|
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
| Set to an |
translation | Set to an |
The following example shows how you can modify a layer using the setValue:forKeyPath:
method. The example sets the translation factor for the x axis to 10 points, causing the layer to shift by that amount along the indicated axis.
[myLayer setValue:[NSNumber numberWithFloat:10.0] forKeyPath:@"transform.translation.x"]; |
CGPoint Key Paths
If the value of a given property is a CGPoint
data type, you can append one of the field names in Table C-3 to the property to get or set that value. For example, to change the x component of a layer’s position
property, you could write to the key path position.x
.
Structure Field | Description |
---|---|
| The x component of the point. |
| The y component of the point. |
CGSize Key Paths
If the value of a given property is a CGSize
data type, you can append one of the field names in Table C-4 to the property to get or set that value.
Structure Field | Description |
---|---|
| The width component of the size. |
| The height component of the size. |
CGRect Key Paths
If the value of a given property is a CGRect
data type, you can append the following field names in Table C-3 to the property to get or set that value. For example, to change the width component of a layer’s bounds
property, you could write to the key path bounds.size.width
.
Structure Field | Description |
---|---|
| The origin of the rectangle as a |
| The x component of the rectangle origin. |
| The y component of the rectangle origin. |
| The size of the rectangle as a |
| The width component of the rectangle size. |
| The height component of the rectangle size. |
Copyright © 2015 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2015-03-09