Next Page > Hide TOC

NSValueTransformer Class Reference

Overview

NSValueTransformer is an abstract class that is used by the Cocoa Bindings technology to transform values from one representation to another.

An application creates a subclass of NSValueTransformer, overriding the necessary methods to provide the required custom transformation.

Example

A relatively trivial value transformer takes an object of type id and returns a string based on the object’s class type. This transformer is not reversible as it’s probably unreasonable to transform a class name into an object. The value transformer class you write to accomplish this simple task could look like:

@interface ClassNameTransformer: NSValueTransformer {}

@end

@implementation ClassNameTransformer

+ (Class)transformedValueClass { return [NSString class]; }

+ (BOOL)allowsReverseTransformation { return NO; }

- (id)transformedValue:(id)value {

    return (value == nil) ? nil : NSStringFromClass([value class]);

}

@end

Tasks

Using Name-based Registry

• + setValueTransformer:forName:
• + valueTransformerForName:
• + valueTransformerNames

Getting Information About a Transformer

• + allowsReverseTransformation
• + transformedValueClass

Using Transformers

• – transformedValue:
• – reverseTransformedValue:

Class Methods

allowsReverseTransformation

Returns a Boolean value that indicates whether the receiver can reverse a transformation.

+ (BOOL)allowsReverseTransformation

Return Value

YES if the receiver supports reverse value transformations, otherwise NO.

The default is NO.

Discussion

A subclass should override this method to return YES if it supports reverse value transformations.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• CoreRecipes
• DerivedProperty

Declared In

setValueTransformer:forName:

Registers the value transformer a given transformer with a given identifier.

+ (void)setValueTransformer:(NSValueTransformer *)transformer forName:(NSString *)name

Parameters

transformer

The transformer to register.

name

The name for transformer.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + valueTransformerForName:

Related Sample Code

• CoreRecipes
• GridCalendar
• NewsReader
• RGB ValueTransformers
• TemperatureTester

Declared In

transformedValueClass

Returns the class of the value returned by the receiver for a forward transformation.

+ (Class)transformedValueClass

Return Value

The class of the value returned by the receiver for a forward transformation.

Discussion

A subclass should override this method to return the appropriate class.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• DerivedProperty
• GridCalendar
• RGB ValueTransformers
• StickiesExample

Declared In

valueTransformerForName:

Returns the value transformer identified by a given identifier.

+ (NSValueTransformer *)valueTransformerForName:(NSString *)name

Parameters

name

The transformer identifier.

Return Value

The value transformer identified by name in the shared registry, or nil if not found.

Discussion

If valueTransformerForName: does not find a registered transformer instance for name, it will attempt to find a class with the specified name. If a corresponding class is found an instance will be created and initialized using its init: method and then automatically registered with name.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + setValueTransformer:forName:

Related Sample Code

• BindingsJoystick
• RGB ValueTransformers
• TemperatureTester

Declared In

valueTransformerNames

Returns an array of all the registered value transformers.

+ (NSArray *)valueTransformerNames

Return Value

An array of all the registered value transformers.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

Instance Methods

reverseTransformedValue:

Returns the result of the reverse transformation of a given value.

- (id)reverseTransformedValue:(id)value

Parameters

value

The value to reverse transform.

Return Value

The reverse transformation of value.

Discussion

The default implementation raises an exception if allowsReverseTransformation returns NO; otherwise it will invoke transformedValue: with value.

A subclass should override this method if they require a reverse transformation that is not the same as simply reapplying the original transform (as would be the case with negation, for example). For example, if a value transformer converts a value in Fahrenheit to Celsius, this method would converts a value from Celsius to Fahrenheit.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – transformedValue:

Related Sample Code

• TemperatureTester

Declared In

transformedValue:

Returns the result of transforming a given value.

- (id)transformedValue:(id)value

Parameters

value

The value to transform.

Return Value

The result of transforming value.

The default implementation simply returns value.

Discussion

A subclass should override this method to transform and return an object based on value.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – reverseTransformedValue:

Related Sample Code

• BindingsJoystick
• CoreRecipes
• RGB ValueTransformers
• TemperatureTester

Declared In

Constants

Named Value Transformers

The following named value transformers are defined by NSValueTransformer:

NSString * const NSNegateBooleanTransformerName;
NSString * const NSIsNilTransformerName ;
NSString * const NSIsNotNilTransformerName ;
NSString * const NSUnarchiveFromDataTransformerName ;
NSString * const NSKeyedUnarchiveFromDataTransformerName ;

Constants

NSNegateBooleanTransformerName

This value transformer negates a boolean value, transforming YES to NO and NO to YES.

This transformer is reversible.

Available in Mac OS X v10.3 and later.

Declared in NSValueTransformer.h.

NSIsNilTransformerName

This value transformer returns YES if the value is nil.

This transformer is not reversible.

Available in Mac OS X v10.3 and later.

Declared in NSValueTransformer.h.

NSIsNotNilTransformerName

This value transformer returns YES if the value is non-nil.

This transformer is not reversible.

Available in Mac OS X v10.3 and later.

Declared in NSValueTransformer.h.

NSUnarchiveFromDataTransformerName

This value transformer returns an object created by attempting to unarchive the data in the NSData object passed as the value.

The reverse transformation returns an NSData instance created by archiving the value. The archived object must implement the NSCoding protocol using sequential archiving in order to be unarchived and archived with this transformer.

Available in Mac OS X v10.3 and later.

Declared in NSValueTransformer.h.

NSKeyedUnarchiveFromDataTransformerName

This value transformer returns an object created by attempting to unarchive the data in the NSData object passed as the value. The archived object must be created using keyed archiving in order to be unarchived and archived with this transformer.

The reverse transformation returns an NSData instance created by archiving the value using keyed archiving. The archived object must implement the NSCoding protocol using keyed archiving in order to be unarchived and archived with this transformer.

Available in Mac OS X v10.5 and later.

Declared in NSValueTransformer.h.

Declared In

Next Page > Hide TOC