---

NSFormCell Class Reference

Overview

The NSFormCell class is used to implement text entry fields in a form. The left part of an NSFormCell object contains a title. The right part contains an editable text entry field.

An NSFormCell object implements the user interface of an NSForm object.

Tasks

Initializing an NSFormCell

• – initTextCell:

Asking About a Cell’s Appearance

• – isOpaque

Asking About a Cell’s Title

• – attributedTitle
• – title
• – titleAlignment
• – titleBaseWritingDirection
• – titleFont
• – titleWidth
• – titleWidth:

Changing the Cell’s Title

• – setAttributedTitle:
• – setTitle:
• – setTitleAlignment:
• – setTitleBaseWritingDirection:
• – setTitleFont:
• – setTitleWidth:

Setting a Keyboard Equivalent

• – setTitleWithMnemonic:

Asking About Placeholder Values

• – placeholderAttributedString
• – placeholderString
• – setPlaceholderAttributedString:
• – setPlaceholderString:

Instance Methods

attributedTitle

Returns the title of the cell as an attributed string.

- (NSAttributedString *)attributedTitle

Return Value

The title of the cell.

Availability

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

Declared In

NSFormCell.h

initTextCell:

Returns an NSFormCell object initialized with the specified title string.

- (id)initTextCell:(NSString *)aString

Parameters

aString

The title for the new form cell object.

Return Value

An initialized NSFormCell object.

Discussion

The contents of the cell's editable text entry field are set to the empty string (@“”). The font for both title and text is the user’s chosen system font in 12.0 point, and the text area is drawn with a bezel. This method is the designated initializer for the NSFormCell class.

Availability

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

See Also

• – setTitle:

Declared In

NSFormCell.h

isOpaque

Returns a Boolean value indicating whether the title is empty and an opaque bezel is set.

- (BOOL)isOpaque

Return Value

YES if the title is empty and an opaque bezel is set; otherwise, NO.

Availability

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

Declared In

NSFormCell.h

placeholderAttributedString

Returns the cell’s attributed placeholder string.

- (NSAttributedString *)placeholderAttributedString

Return Value

The attributed placeholder string, or nil if the cell has no attributed placeholder string.

Discussion

If this method returns nil, you can also call placeholderString to see if the cell has a plain text placeholder string.

Availability

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

See Also

• – placeholderString
• – setPlaceholderAttributedString:

Declared In

NSFormCell.h

placeholderString

Returns the cell’s plain text placeholder string.

- (NSString *)placeholderString

Return Value

The plain-text placeholder string, or nil if the cell has no plain-text placeholder string.

Discussion

If this method returns nil, you can also call placeholderAttributedString to see if the cell has an attributed placeholder string.

Availability

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

See Also

• – placeholderAttributedString
• – setPlaceholderString:

Declared In

NSFormCell.h

setAttributedTitle:

Sets the receiver’s title using an attributed string.

- (void)setAttributedTitle:(NSAttributedString *)anAttributedString

Parameters

anAttributedString

The formatted title of the cell.

Availability

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

Declared In

NSFormCell.h

setPlaceholderAttributedString:

Sets the attributed placeholder string for the cell.

- (void)setPlaceholderAttributedString:(NSAttributedString *)string

Parameters

string

The attributed placeholder string.

Discussion

Note that invoking this method clears out any plain text string set by calling the setPlaceholderString: method.

Availability

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

See Also

• – placeholderAttributedString
• – setPlaceholderString:

Declared In

NSFormCell.h

setPlaceholderString:

Sets the plain-text placeholder string for the cell.

- (void)setPlaceholderString:(NSString *)string

Parameters

string

The plain-text placeholder string.

Discussion

Note that invoking this method clears out any attributed string set by the setPlaceholderAttributedString: method.

Availability

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

See Also

• – placeholderString
• – setPlaceholderAttributedString:

Declared In

NSFormCell.h

setTitle:

Sets the receiver’s title to the specified plain-text string.

- (void)setTitle:(NSString *)aString

Parameters

aString

The plain-text title of the cell.

Availability

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

Declared In

NSFormCell.h

setTitleAlignment:

Sets the alignment of the title.

- (void)setTitleAlignment:(NSTextAlignment)alignment

Parameters

alignment

The alignment can be one of the following constants: NSRightTextAlignment, NSCenterTextAlignment, or NSLeftTextAlignment.

Availability

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

Declared In

NSFormCell.h

setTitleBaseWritingDirection:

Sets the default writing direction used to render the form cell’s title.

- (void)setTitleBaseWritingDirection:(NSWritingDirection)writingDirection

Parameters

writingDirection

This value can be one of the following constants: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft.

Availability

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

See Also

• – setTitleBaseWritingDirection:
• – baseWritingDirection (NSCell)

Declared In

NSFormCell.h

setTitleFont:

Sets the font of the receiver's title.

- (void)setTitleFont:(NSFont *)font

Parameters

font

The font to use.

Availability

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

Declared In

NSFormCell.h

setTitleWidth:

Sets the width of the title.

- (void)setTitleWidth:(CGFloat)width

Parameters

width

The width of the title, measured in points in the user coordinate space.

Discussion

You usually do not need to invoke this method. The Application Kit automatically sets the title width whenever the title changes. If the automatic width doesn’t suit your needs, though, you can use this method to set the width explicitly.

Once you have set the width this way, the Application Kit stops setting the width automatically; you must invoke this method every time the title changes. If you want the Application Kit to resume automatic width assignments, invoke this method with a negative width value.

Availability

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

Declared In

NSFormCell.h

setTitleWithMnemonic:

Sets the cell title and mnemonic character.

- (void)setTitleWithMnemonic:(NSString *)titleWithAmpersand

Parameters

titleWithAmpersand

The title of the cell, including a mnemonic identifier. To specify the mnemonic character, place an ampersand (&) in the front of the desired character.

Discussion

Mnemonics are not supported in Mac OS X.

Availability

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

See Also

• – setTitle:

Declared In

NSFormCell.h

title

Returns the receiver’s title.

- (NSString *)title

Return Value

The title of the cell. The default value is "Field:".

Availability

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

Declared In

NSFormCell.h

titleAlignment

Returns the alignment of the title.

- (NSTextAlignment)titleAlignment

Return Value

The alignment can be one of the following values: NSLeftTextAlignment, NSCenterTextAlignment, or NSRightTextAlignment. The default alignment is NSRightTextAlignment.

Availability

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

Declared In

NSFormCell.h

titleBaseWritingDirection

Returns the default writing direction used to render the form cell’s title.

- (NSWritingDirection)titleBaseWritingDirection

Return Value

One of the following constants: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft.

Availability

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

See Also

• – setTitleBaseWritingDirection:

Declared In

NSFormCell.h

titleFont

Returns the font used to draw the receiver’s title.

- (NSFont *)titleFont

Return Value

The font object used for the title.

Availability

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

Declared In

NSFormCell.h

titleWidth

Returns the width of the title field.

- (CGFloat)titleWidth

Return Value

The width of the title field, measured in points in the user coordinate space.

Discussion

If you set the width using setTitleWidth:, this method returns the value you set; otherwise, it returns the width calculated automatically by the Application Kit.

Availability

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

See Also

• – titleWidth:

Declared In

NSFormCell.h

titleWidth:

Returns the width of the title field constrained to the specified size.

- (CGFloat)titleWidth:(NSSize)aSize

Parameters

aSize

The maximum size of the field when calculated by the Application Kit.

Return Value

The width of the title field, measured in points in the user coordinate space.

Discussion

If you set the width using setTitleWidth:, this method returns the value you set; otherwise, the Application Kit calculates the width, constraining the field size to the specified value.

Availability

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

See Also

• – titleWidth

Declared In

NSFormCell.h

---