CPFormatter Class Reference

CPFormatter is an abstract class that declares an interface for objects that create, interpret, and validate the textual representation of cell contents. The Foundation framework provides two concrete subclasses of CPFormatter to generate these objects: CPNumberFormatter and CPDateFormatter. More...

#import <CPFormatter.h>

Inheritance diagram for CPFormatter:

Instance Methods
(CPString)	- editingStringForObjectValue:
(void)	- encodeWithCoder:
(BOOL)	- getObjectValue:forString:errorDescription:
(id)	- initWithCoder:
(BOOL)	- isPartialStringValid:newEditingString:errorDescription:
(BOOL)	- isPartialStringValid:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:
(CPString)	- stringForObjectValue:
Instance Methods inherited from CPObject
(void)	- addObserver:forKeyPath:options:context:
(void)	- applyChange:toKeyPath:
(id)	- autorelease
(id)	- awakeAfterUsingCoder:
(void)	- awakeFromCib
(void)	- bind:toObject:withKeyPath:options:
(Class)	- classForCoder
(Class)	- classForKeyedArchiver
(CPString)	- className
(id)	- copy
(void)	- dealloc
(CPString)	- description
(CPDictionary)	- dictionaryWithValuesForKeys:
(void)	- didChange:valuesAtIndexes:forKey:
(void)	- didChangeValueForKey:
(void)	- didChangeValueForKey:withSetMutation:usingObjects:
(void)	- doesNotRecognizeSelector:
(CPArray)	- exposedBindings
(id)	- forwardingTargetForSelector:
(void)	- forwardInvocation:
(unsigned)	- hash
(BOOL)	- implementsSelector:
(CPDictionary)	- infoForBinding:
(id)	- init
(BOOL)	- isEqual:
(BOOL)	- isKindOfClass:
(BOOL)	- isMemberOfClass:
(BOOL)	- isProxy
(IMP)	- methodForSelector:
(CPMethodSignature)	- methodSignatureForSelector:
(id)	- mutableArrayValueForKey:
(id)	- mutableArrayValueForKeyPath:
(id)	- mutableCopy
(id)	- mutableSetValueForKey:
(id)	- mutableSetValueForKeyPath:
(id)	- performSelector:
(id)	- performSelector:withObject:
(void)	- performSelector:withObject:afterDelay:
(void)	- performSelector:withObject:afterDelay:inModes:
(id)	- performSelector:withObject:withObject:
(id)	- performSelector:withObjects:
(void)	- release
(void)	- removeObserver:forKeyPath:
(id)	- replacementObjectForArchiver:
(id)	- replacementObjectForCoder:
(id)	- replacementObjectForKeyedArchiver:
(BOOL)	- respondsToSelector:
(id)	- retain
(id)	- self
(void)	- setValue:forKey:
(void)	- setValue:forKeyPath:
(void)	- setValue:forUndefinedKey:
(void)	- setValuesForKeysWithDictionary:
(CPString)	- UID
(void)	- unbind:
(Class)	- valueClassForBinding:
(id)	- valueForKey:
(id)	- valueForKeyPath:
(id)	- valueForUndefinedKey:
(void)	- willChange:valuesAtIndexes:forKey:
(void)	- willChangeValueForKey:
(void)	- willChangeValueForKey:withSetMutation:usingObjects:

Additional Inherited Members
Class Methods inherited from CPObject
(BOOL)	+ accessInstanceVariablesDirectly
(id)	+ alloc
(id)	+ allocWithCoder:
(BOOL)	+ automaticallyNotifiesObserversForKey:
(void)	+ cancelPreviousPerformRequestsWithTarget:
(void)	+ cancelPreviousPerformRequestsWithTarget:selector:object:
(Class)	+ class
(BOOL)	+ conformsToProtocol:
(void)	+ exposeBinding:
(void)	+ initialize
(IMP)	+ instanceMethodForSelector:
(BOOL)	+ instancesImplementSelector:
(BOOL)	+ instancesRespondToSelector:
(BOOL)	+ isBindingExclusive:
(BOOL)	+ isSubclassOfClass:
(CPSet)	+ keyPathsForValuesAffectingValueForKey:
(void)	+ load
(id)	+ new
(void)	+ object:performSelector:withObject:afterDelay:inModes:
(void)	+ setVersion:
(Class)	+ superclass
(int)	+ version

Detailed Description

CPFormatter is an abstract class that declares an interface for objects that create, interpret, and validate the textual representation of cell contents. The Foundation framework provides two concrete subclasses of CPFormatter to generate these objects: CPNumberFormatter and CPDateFormatter.

CPFormatter is intended for subclassing. A custom formatter can restrict the input and enhance the display of data in novel ways. For example, you could have a custom formatter that ensures that serial numbers entered by a user conform to predefined formats. Before you decide to create a custom formatter, make sure that you cannot configure the public subclasses CPDateFormatter and CPNumberFormatter to satisfy your requirements.

Definition at line 2 of file CPFormatter.h.

Method Documentation

editingStringForObjectValue:()

- (CPString) editingStringForObjectValue: (id)  anObject

implementation

The default implementation of this method invokes stringForObjectValue:.

When implementing a subclass, override this method only when the string that users see and the string that they edit are different. In your implementation, return an CPString object that is used for editing, following the logic recommended for implementing stringForObjectValue:. As an example, you would implement this method if you want the dollar signs in displayed strings removed for editing.

Parameters

anObject

the object for which to return an editing string

Returns

CPString object that is used for editing the textual representation of an object

Reimplemented in CPNumberFormatter, and CPDateFormatter.

Definition at line 73 of file CPFormatter.j.

encodeWithCoder:()

- (void) encodeWithCoder: (CPCoder)  aCoder

implementation

Reimplemented in CPNumberFormatter, CPDateFormatter, and CPByteCountFormatter.

Definition at line 172 of file CPFormatter.j.

getObjectValue:forString:errorDescription:()

- (BOOL) getObjectValue: (idRef)  anObject forString: (CPString)  aString errorDescription: (CPStringRef)  anError

implementation

The default implementation of this method raises an exception.

When implementing a subclass, return by reference the object anObject after creating it from aString. Return YES if the conversion is successful. If you return NO, also return by reference (in anError) a localized user-presentable CPString object that explains the reason why the conversion failed; the delegate (if any) of the CPControl object can then respond to the failure in control:didFailToFormatString:errorDescription:. However, if anError is nil, the sender is not interested in the error description, and you should not attempt to assign one.

Parameters

anObject	if conversion is successful, upon return contains the object created from the string
aString	the string to parse.
anError	if non-nil, if there is an error during the conversion, upon return contains an CPString object that describes the problem.

Returns

BOOL YES if the conversion from the string to a view content object was successful, otherwise NO.

Reimplemented in CPNumberFormatter, CPDateFormatter, and CPByteCountFormatter.

Definition at line 93 of file CPFormatter.j.

initWithCoder:()

- (id) initWithCoder: (CPCoder)  aCoder

implementation

Reimplemented in CPNumberFormatter, CPDateFormatter, and CPByteCountFormatter.

Definition at line 167 of file CPFormatter.j.

isPartialStringValid:newEditingString:errorDescription:()

- (BOOL) isPartialStringValid: (CPString)  aPartialString newEditingString: (CPStringRef)  aNewString errorDescription: (CPStringRef)  anError

implementation

Returns a Boolean value that indicates whether a partial string is valid.

This method is invoked each time the user presses a key while the cell has the keyboard focus it lets you verify and edit the cell text as the user types it.

In a subclass implementation, evaluate aPartialString according to the context, edit the text if necessary, and return by reference any edited string in aNewString. Return YES if aPartialString is acceptable and NO if aPartialString is unacceptable. If you return NO and aNewString is nil, the control displays aPartialString minus the last character typed. If you return NO, you can also return by reference a CPString object (in anError) that explains the reason why the validation failed; the delegate (if any) of the CPControl can then respond to the failure in control:didFailToValidatePartialString:errorDescription:. The selection range will always be set to the end of the text if replacement occurs.

This method is a compatibility method. If a subclass overrides this method and does not override isPartialStringValid:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:, this method will be called as before (isPartialStringValid:proposedSelectedRange:originalString:originalSelectedRange:errorDescription: just calls this one by default).

Parameters

aPartialString	the text currently in the view.
aNewString	if aPartialString needs to be modified, upon return contains the replacement string.
anError	if non-nil, if validation fails contains a CPString object that describes the problem.

Returns

YES if aPartialString is an acceptable value, otherwise NO.

Definition at line 121 of file CPFormatter.j.

isPartialStringValid:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:()

- (BOOL) isPartialStringValid: (CPStringRef)  aPartialStringRef proposedSelectedRange: (CPRangeRef)  aProposedSelectedRangeRef originalString: (CPString)  originalString originalSelectedRange: (CPRange)  originalSelectedRange errorDescription: (CPStringRef)  anError

implementation

This method should be implemented in subclasses that want to validate user changes to a string in a field, where the user changes are not necessarily at the end of the string, and preserve the selection (or set a different one, such as selecting the erroneous part of the string the user has typed).

In a subclass implementation, evaluate aPartialStringRef according to the context. Return YES if aPartialStringRef is acceptable and NO if aPartialStringRef is unacceptable. Assign a new string by reference to aPartialStringRef and a new range by reference to aProposedSelectedRangeRef and return NO if you want to replace the string and change the selection range. If you return NO, you can also return by reference a CPString object (in anError) that explains the reason why the validation failed; the delegate (if any) of the CPControl can then respond to the failure in control:didFailToValidatePartialString:errorDescription:.

Parameters

aPartialStringRef	The new string to validate.
aProposedSelectedRangeRef	The selection range that will be used if the string is accepted or replaced.
originalString	The original string, before the proposed change.
originalSelectedRange	The selection range over which the change is to take place.
anError	If non-nil, if validation fails contains an CPString object that describes the problem.

Returns

YES if aPartialStringRef is acceptable, otherwise NO.

Definition at line 150 of file CPFormatter.j.

stringForObjectValue:()

- (CPString) stringForObjectValue: (id)  anObject

implementation

The default implementation of this method raises an exception.

When implementing a subclass, return the CPString object that textually represents the view's object for display and if editingStringForObjectValue: is unimplemented for editing. First test the passed-in object to see if it's of the correct class. If it isn't, return nil; but if it is of the right class, return a properly formatted and, if necessary, localized string. (See the specification of the CPString class for formatting and localizing details.)

Parameters

anObject

The object for which a textual representation is returned

Returns

CPSting a formatted string

Reimplemented in CPNumberFormatter, CPDateFormatter, and CPByteCountFormatter.

Definition at line 51 of file CPFormatter.j.

---

The documentation for this class was generated from the following files:

• Foundation/CPFormatter.h
• Foundation/CPFormatter.j