---

NSFormatter

Overview

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.

Subclassing Notes

NSFormatter is similar to other abstract classes such as NSView or NSDocument in that it 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 NSGregorianDateFormatter and NSNumberFormatter to satisfy your requirements.

For instructions on how to create your own custom formatter, see “Creating A Custom Formatter”.

Tasks

Constructors

• NSFormatter

Textual Representation of Cell Content

• stringForObjectValue
• attributedStringForObjectValue
• editingStringForObjectValue

Object Equivalent to Textual Representation

• objectValueForString

Dynamic Cell Editing

• isPartialStringValid
• replacementStringForString

Instance Methods

attributedStringForObjectValue

This method is an abstract method that you must override in your subclass.

public abstract NSAttributedString attributedStringForObjectValue(Object anObject, NSDictionary attributes)

Discussion

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 nonattributed string. Then create an NSAttributedString with it. The default attributes for text in the cell are 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 NSAttributedString class.

See Also

• editingStringForObjectValue

editingStringForObjectValue

The default implementation of this method invokes stringForObjectValue.

public String editingStringForObjectValue(Object anObject)

Discussion

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

Since this method is invoked each time the user presses a key while the cell has the keyboard focus, it lets you verify the cell text as the user types it. partialString is the text currently in the cell.

public boolean isPartialStringValid(String partialString)

Discussion

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

This method is an abstract method that you must override in your subclass.

public abstract Object objectValueForString(String aString)

Discussion

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

The default implementation of this method returns aString.

public String replacementStringForString(String aString)

Discussion

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

This method is an abstract method that you must override in your subclass. The default implementation of this method throws an exception.

public abstract String stringForObjectValue(Object anObject)

Discussion

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

---