NSTextFieldCell Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Text Fields
Declared in
NSTextFieldCell.h
Related sample code

Overview

The NSTextFieldCell class adds to the text display capabilities of the NSCell class by allowing you to set the color of both the text and its background. You can also specify whether the cell draws its background at all.

All of the methods declared by this class are also declared by the NSTextField class, which uses NSTextFieldCell objects to draw and edit text. These NSTextField cover methods call the corresponding NSTextFieldCell methods.

Placeholder strings, set using setPlaceholderString: or setPlaceholderAttributedString:, now appear in the text field cell if the actual string is nil or @"". They are drawn in grey on the cell and are not archived in the “pre-10.2” nib format.

Designated Initializers

When subclassing NSTextFieldCell you must implement all of the designated initializers. Those methods are: initWithCoder:, initTextCell:, and initImageCell:.

Tasks

Setting the Text Color

Setting the Bezel Style

Controlling the Background

Managing the Field Editor

Managing Placeholder Strings

Accessing Input Source Locales

Instance Methods

allowedInputSourceLocales

Returns an array of locale identifiers representing input sources that are allowed to be enabled when the receiver has the keyboard focus.

- (NSArray *)allowedInputSourceLocales
Return Value

The locale identifiers of allowed input sources.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTextFieldCell.h

backgroundColor

Returns the color of the background the receiver draws behind the text.

- (NSColor *)backgroundColor
Return Value

The background color of the text field cell.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTextFieldCell.h

bezelStyle

Returns the receiver’s bezel style.

- (NSTextFieldBezelStyle)bezelStyle
Return Value

A constant indicating the bezel style of the text field cell. See NSTextFieldBezelStyle.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSTextFieldCell.h

drawsBackground

Returns a Boolean value that indicates whether the receiver draws its background color.

- (BOOL)drawsBackground
Return Value

YES if the receiver draws its background color behind its text, NO if it draws no background.

Discussion

In order to prevent inconsistent rendering, background color rendering is disabled for rounded-bezel text fields.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTextFieldCell.h

placeholderAttributedString

Returns the cell’s attributed placeholder string.

- (NSAttributedString *)placeholderAttributedString
Return Value

The attributed string used as the cell's placeholder.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSTextFieldCell.h

placeholderString

Returns the cell’s plain text placeholder string.

- (NSString *)placeholderString
Return Value

The cell''s placeholder string.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSTextFieldCell.h

setAllowedInputSourceLocales:

Sets an array of locale identifiers representing input sources that are allowed to be enabled when the receiver has the keyboard focus.

- (void)setAllowedInputSourceLocales:(NSArray *)localeIdentifiers
Parameters
localeIdentifiers

The new locale identifiers of allowed input sources.

Discussion

You can use the meta-locale identifier, NSAllRomanInputSourcesLocaleIdentifier, to specify input sources that are limited for Roman script editing.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTextFieldCell.h

setBackgroundColor:

Sets the color of the background that the receiver draws behind the text.

- (void)setBackgroundColor:(NSColor *)aColor
Parameters
aColor

The background color of the text field cell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextFieldCell.h

setBezelStyle:

Sets the receiver’s bezel style.

- (void)setBezelStyle:(NSTextFieldBezelStyle)style
Parameters
style

A constant specifying the bezel style of the text field cell. See NSTextFieldBezelStyle.

Discussion

To set the bezel style, you must have already sent setBezeled: with an argument of YES.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSTextFieldCell.h

setDrawsBackground:

Controls whether the receiver draws its background color behind its text.

- (void)setDrawsBackground:(BOOL)flag
Parameters
flag

If YES, the receiver draws its background; if NO it draws nothing behind its text.

Discussion

In order to prevent inconsistent rendering, background color rendering is disabled for rounded-bezel text fields.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextFieldCell.h

setPlaceholderAttributedString:

Sets the placeholder of the cell as an attributed string.

- (void)setPlaceholderAttributedString:(NSAttributedString *)string
Return Value

The attributed string to use as a placeholder.

Discussion

Note that invoking this successfully will clear out any plain text string set by setPlaceholderString:.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSTextFieldCell.h

setPlaceholderString:

Sets the placeholder of the cell as a plain text string.

- (void)setPlaceholderString:(NSString *)string
Parameters
string

The placeholder string.

Discussion

Note that invoking this successfully will clear out any attributed string set by setPlaceholderAttributedString:.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSTextFieldCell.h

setTextColor:

Sets the color used to draw the receiver’s text.

- (void)setTextColor:(NSColor *)aColor
Parameters
aColor

The color used to draw the text.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextFieldCell.h

setUpFieldEditorAttributes:

Sets up the field editor. You never invoke this method directly; by overriding it, however, you can customize the field editor.

- (NSText *)setUpFieldEditorAttributes:(NSText *)textObj
Discussion

When you override this method, you should generally invoke the implementation of super and return the textObj argument. For information on field editors, see “Using the Window’s Field Editor”.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSTextFieldCell.h

setWantsNotificationForMarkedText:

Directs the cell’s associated field editor to post text change notifications.

- (void)setWantsNotificationForMarkedText:(BOOL)flag
Parameters
flag

If YES, the field editor posts text change notifications (NSTextDidChangeNotification) while editing marked text; if NO, notifications are delayed until the marked text confirmation.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTextFieldCell.h

textColor

Returns the color used to draw the receiver’s text.

- (NSColor *)textColor
Return Value

The color used to draw the text.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTextFieldCell.h

Constants

NSTextFieldBezelStyle

Specify the bezel style of the text field cell.

enum {
   NSTextFieldSquareBezel  = 0,
   NSTextFieldRoundedBezel = 1
};
typedef NSUInteger NSTextFieldBezelStyle;
Constants
NSTextFieldSquareBezel

Corners are square.

Available in OS X v10.2 and later.

Declared in NSTextFieldCell.h.

NSTextFieldRoundedBezel

Corners are rounded.

Available in OS X v10.2 and later.

Declared in NSTextFieldCell.h.

Discussion

The bezel style of a text field is set using the bezelStyle and setBezelStyle: methods.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSTextFieldCell.h