PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSFormatter


Inherits from:
NSObject
Package:
com.apple.yellow.foundation


Class Description


NSFormatter 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 NSFormatter to generate these objects: NSNumberFormatter and NSGregorianDateFormatter.

Cells, which are instances of NSCell and its subclasses, can have any arbitrary object as their content. However, when cells are to be displayed or edited, they must convert this object to a String. If no formatting object is associated with a cell, the cell displays its content by invoking the localized description method of the object it contains. But if the cell has a formatting object, the cell invokes this object's stringForObjectValue method to obtain the correctly formatted string. Conversely, when the user enters text into a cell, the cell needs to convert the text to the underlying object; formatting objects handle this conversion as well.

To use a formatting object, you must create an instance of NSNumberFormatter, NSGregorianDateFormatter, or a custom NSFormatter subclass and associate the object with a cell. The cell invokes the formatting behavior of this instance every time it needs to display its object or have it edited, and every time it needs to convert a textual representation to its object. See the class description of NSGregorianDateFormatter for the details of using formatting objects.

Instances of NSFormatter subclasses are immutable. In addition, when a cell with a formatter object is copied, the new cell uses the existing formatter object instead of copying it.


Making a Subclass of NSFormatter


There are many possibilities for custom subclasses of NSFormatter. You might find use for a custom formatter of telephone numbers, or a custom formatter of part numbers.

To subclass NSFormatter, you must, at the least, override the three primitive methods stringForObjectValue , objectValueForString, and attributedStringForObjectValue. In the first method you convert the cell's object to a string representation; in the second method you convert the string to the object associated with the cell.

In attributedStringForObjectValue , you convert the object to a string that has attributes associated with it. For example, if you want negative financial amounts to appear in red, you would return a string with an attribute of red text. In attributedStringForObjectValue get the non-attributed String by invoking stringForObjectValue and then apply the proper attributes to that String.

If the string for editing is different than the string for display-for example, the display version of a currency field should show a dollar sign but the editing version shouldn't-implement editingStringForObjectValue in addition to stringForObjectValue.

The methods isPartialStringValid and replacementStringForString let you edit the textual contents of a cell at each key press or to prevent entry of invalid characters. Invoke isPartialStringValid with a string to see if it's valid. If isPartialStringValid returns false, invoke replacementStringForString with the string to get the corrected string. You might apply this on-the-fly editing to things like telephone numbers or social security numbers; the person entering data only needs to enter the number since the formatter automatically inserts the separator characters.




Method Types


Constructors
NSFormatter
Textual representation of cell content
stringForObjectValue
attributedStringForObjectValue
editingStringForObjectValue
Object equivalent to textual representation
objectValueForString
Dynamic cell editing
isPartialStringValid
replacementStringForString


Constructors



NSFormatter

public NSFormatter()

Description forthcoming.


Instance Methods



attributedStringForObjectValue

public abstract NSAttributedString attributedStringForObjectValue( Object anObject, NSDictionary attributes)

This is an abstract method that you must override in your subclass. When implementing a subclass, return an NSAttributedString if the string for display should have some attributes. For instance, you might want negative values in a financial application to appear in red text. Invoke your implementation of stringForObjectValue to get the non-attributed string. Then create an NSAttributedString with it. The default attributes for text in the cell is passed in with attributes; use this NSDictionary to reset the attributes of the string when a change in value warrants it (for example, a negative value becomes positive) If a NSAttributedString cannot be created for anObject, an NSFormatter.FormattingException is thrown. For information on creating attributed strings, see the specification for the NSAttributedString class.

See Also: editingStringForObjectValue



editingStringForObjectValue

public String editingStringForObjectValue(Object anObject)

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 a String 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.

See Also: attributedStringForObjectValue



isPartialStringValid

public boolean isPartialStringValid(String partialString)

Since this method is invoked each time the user presses a key in the cell, it lets you verify the cell text as the user types it. partialString is the text currently in the cell. Return true if it is acceptable and false if it is not. If you return false, the cell displays partialString minus the last character typed.

See Also: replacementStringForString



objectValueForString

public abstract Object objectValueForString(String aString)

This is an abstract method that you must override in your subclass. When implementing a subclass, return an object you've created from aString. If an object cannot be created from aString, an NSFormatter.ParsingException is thrown.

See Also: stringForObjectValue



replacementStringForString

public String replacementStringForString(String aString)

The default implementation of this method returns aString. When implementing a subclass, check whether aString is a valid string for the cell. If it is, return it unmodified. Otherwise, correct it and return the modified string. For example, you might convert all lowercase letters to uppercase, or insert separator characters in a telephone number.

See Also: isPartialStringValid



stringForObjectValue

public abstract String stringForObjectValue(Object anObject)

This is an abstract method that you must override in your subclass. The default implementation of this method throws an exception. When implementing a subclass, return the String that textually represents the cell'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 null; but if it is of the right class return a properly formatted and, if necessary, localized string. If a string cannot be created for anObject, an NSFormatter.FormattingException is thrown.

See Also: attributedStringForObjectValue, editingStringForObjectValue, objectValueForString




Table of Contents