< Previous PageNext Page > Hide TOC

Formatters and User Interface Elements

This article describes how to associate a formatter with a cell in Cocoa.

Contents:

Interface Builder
Associating a Formatter With a Cell
Delegation Methods for Error Handling

Interface Builder

The easiest way to use a formatter is in Interface Builder to drag it from the palette onto a control such as a text field or a column in a table view. You can then configure the behavior you want using the inspector—typically you should use v10.4 behavior.

Associating a Formatter With a Cell

To create a formatter object programmatically and attach it to a cell, you allocate an instance of the formatter and set its format or style as you wish. You then use the NSCell setFormatter: method to associate the formatter instance with a cell. The following code example creates an instance of NSNumberFormatter, sets its formatting for positive, zero, and negative values, and applies it to the cell of an NSTextField object using the setFormatter: method.

NSNumberFormatter *numberFormatter =

    [[[NSNumberFormatter alloc] init] autorelease];

[numberFormatter setFormat:@"$#,###.00;0.00;($#,##0.00)"];

[[textField cell] setFormatter:numberFormatter];

Similarly you can create an instance of NSDateFormatter object programmatically. The following example creates a date formatter with the format string %b %1d %Y (to give a date format like “Jan 2 2001”) and then associates the formatter with the cells of a form (contactsForm).

NSDateFormatter *dateFormat = [[NSDateFormatter alloc]

         initWithDateFormat:@"%b %1d %Y" allowNaturalLanguage:NO];

[[contactsForm cells] makeObjectsPerformSelector:@selector(setFormatter:)

         withObject:dateFormat]

Note that instances of formatter objects are immutable. In addition, when a cell with a formatter object is copied, the new cell retains the formatter object instead of copying it.

The value (that you retrieve using the method objectValue) of a cell (NSCell) is represented by an object, which in the number formatter code example above is a number object. Using Mac OS X version 10.0 behavior it would be a NSDecimalNumber object; using Mac OS X v10.4 behavior it would be by default a NSNumber object. In the case of the NSDateFormatter code example above, the cell’s value would be, using Mac OS X version 10.0 behavior it would be a NSCalendarDate object, using Mac OS X v10.4 behavior it would be by default a NSDate object.

When the cell needs to display or edit its value, it passes its object to the formatter which returns the formatted string. When the user enters a string, or when a string is programmatically written in a cell (using setStringValue), the cell obtains the corresponding object from the formatter.

Delegation Methods for Error Handling

NSControl has delegation methods for handling errors returned in implementations of NSFormatter's getObjectValue:forString:errorDescription:, isPartialStringValid:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:, and isPartialStringValid:newEditingString:errorDescription: methods. These delegation methods are, respectively, control:didFailToFormatString:errorDescription: and control:didFailToValidatePartialString:errorDescription:.

< Previous PageNext Page > Hide TOC