---

NSTextField Class Reference

Overview

An NSTextField object is a kind of NSControl that displays text that the user can select or edit and that sends its action message to its target when the user presses the Return key while editing.

The NSTextField class uses the NSTextFieldCell class to implement its user interface.

Tasks

Controlling Editability and Selectability

• – setEditable:
• – isEditable
• – setSelectable:
• – isSelectable

Controlling Rich Text Behavior

• – setAllowsEditingTextAttributes:
• – allowsEditingTextAttributes
• – setImportsGraphics:
• – importsGraphics

Setting the Text Color

• – setTextColor:
• – textColor

Controlling the Background

• – setBackgroundColor:
• – backgroundColor
• – setDrawsBackground:
• – drawsBackground

Setting a Border

• – setBezeled:
• – isBezeled
• – setBezelStyle:
• – bezelStyle
• – setBordered:
• – isBordered

Selecting the Text

• – selectText:

Working with the Responder Chain

• – acceptsFirstResponder

Using Keyboard Interface Control

• – setTitleWithMnemonic:

Setting the Delegate

• – setDelegate:
• – delegate

NSText Delegate Method Implementations

• – textShouldBeginEditing:
• – textDidBeginEditing:
• – textDidChange:
• – textShouldEndEditing:
• – textDidEndEditing:

Instance Methods

acceptsFirstResponder

Returns a Boolean value indicating whether the receiver is editable.

- (BOOL)acceptsFirstResponder

Return Value

YES if the receiver is editable, NO otherwise.

Availability

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

Declared In

NSTextField.h

allowsEditingTextAttributes

Returns a Boolean value indicating whether the user is allowed to change font attributes of the receiver's text.

- (BOOL)allowsEditingTextAttributes

Return Value

YES if the receiver allows the user to change font attributes of the receiver’s text, otherwise NO. You can change text attributes programmatically regardless of this setting.

Availability

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

See Also

• – importsGraphics
• – setAllowsEditingTextAttributes:

Declared In

NSTextField.h

backgroundColor

Returns the color of the background that the receiver’s cell draws behind the text.

- (NSColor *)backgroundColor

Return Value

The color used to draw the background.

Availability

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

See Also

• – drawsBackground
• – setBackgroundColor:

Declared In

NSTextField.h

bezelStyle

Returns the receiver’s bezel style.

- (NSTextFieldBezelStyle)bezelStyle

Return Value

A constant indicating the bezel style. Possible values are described in the “Constants” section of NSTextFieldCell.

Availability

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

See Also

• – setBezelStyle:

Declared In

NSTextField.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The object that acts as the receiver's delegate.

Availability

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

See Also

• – textShouldBeginEditing:
• – textShouldEndEditing:
• – textDidBeginEditing:
• – textDidEndEditing:
• – textDidChange:
• – setDelegate:

Declared In

NSTextField.h

drawsBackground

Returns a Boolean value indicating whether the receiver's cell draws its background color.

- (BOOL)drawsBackground

Return Value

YES if the receiver’s cell 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 Mac OS X v10.0 and later.

See Also

• – backgroundColor
• – drawsBackground (NSTextFieldCell)
• – setDrawsBackground:

Declared In

NSTextField.h

importsGraphics

Returns a Boolean value indicating whether the receiver allows the user to drag image files into it.

- (BOOL)importsGraphics

Return Value

YES if the receiver allows the user to drag image files into it, otherwise NO. You can add images programmatically regardless of this setting.

Availability

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

See Also

• – allowsEditingTextAttributes
• – importsGraphics (NSTextView)
• – setImportsGraphics:

Declared In

NSTextField.h

isBezeled

Returns a Boolean value indicating whether the receiver draws a bezeled frame.

- (BOOL)isBezeled

Return Value

YES if the receiver draws a bezeled frame around its contents; otherwise, NO.

Availability

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

See Also

• – isBordered
• – setBezeled:

Declared In

NSTextField.h

isBordered

Returns a Boolean value indicating whether the receiver draws a black border around its contents.

- (BOOL)isBordered

Return Value

YES if the receiver draws a solid black border around its contents; otherwise NO.

Availability

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

See Also

• – isBezeled
• – setBordered:

Declared In

NSTextField.h

isEditable

Returns a Boolean value indicating whether the user is allowed to select and edit the receiver's text.

- (BOOL)isEditable

Return Value

YES if the user is allowed to select and edit the receiver’s text, NO if the user isn’t allowed to edit it (though the user may be able to select it).

Availability

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

See Also

• – isSelectable
• – setEditable:

Declared In

NSTextField.h

isSelectable

Returns a Boolean value indicating whether the user is allowed to select the receiver’s text.

- (BOOL)isSelectable

Return Value

YES if the user is allowed to select the receiver’s text; otherwise NO.

Discussion

Selectable text isn’t necessarily editable; use isEditable to check for editability.

Availability

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

See Also

• – setSelectable:

Declared In

NSTextField.h

selectText:

Ends editing and selects the entire contents of the receiver if it’s selectable.

- (void)selectText:(id)sender

Parameters

sender

The sender of the message.

Discussion

If the receiver isn’t in some window’s view hierarchy, this method has no effect.

Availability

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

See Also

• – isSelectable

Related Sample Code

• QTMetadataEditor

Declared In

NSTextField.h

setAllowsEditingTextAttributes:

Controls whether the receiver allows the user to change font attributes of the receiver’s text.

- (void)setAllowsEditingTextAttributes:(BOOL)flag

Parameters

flag

If YES, the user is permitted to change font attributes of the receiver’s text; if flag is NO, the user isn’t so permitted. You can change text attributes programmatically regardless of this setting.

Availability

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

See Also

• – setImportsGraphics:
• – allowsEditingTextAttributes

Declared In

NSTextField.h

setBackgroundColor:

Sets the color of the background that the receiver’s cell draws behind the text.

- (void)setBackgroundColor:(NSColor *)aColor

Parameters

aColor

The color used to draw the background.

Availability

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

See Also

• – setDrawsBackground:
• – backgroundColor

Declared In

NSTextField.h

setBezeled:

Controls whether the receiver draws a bezeled border around its contents.

- (void)setBezeled:(BOOL)flag

Parameters

flag

If YES, it draws a bezeled border and invokes setDrawsBackground: with an argument of NO; if NO, the receiver does not draw a border.

Availability

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

See Also

• – isBezeled
• – setBordered:

Related Sample Code

• Quartz Composer QCTV
• Vertex Optimization

Declared In

NSTextField.h

setBezelStyle:

Sets the receiver’s bezel style.

- (void)setBezelStyle:(NSTextFieldBezelStyle)style

Parameters

style

A constant indicating the bezel style. Possible values for style are described in the “Constants” section of NSTextFieldCell. You must have already sent the receiver setBezeled: with an argument of YES

Availability

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

See Also

• – bezelStyle

Declared In

NSTextField.h

setBordered:

Controls whether the receiver draws a solid black border around its contents.

- (void)setBordered:(BOOL)flag

Parameters

flag

If YES, the receiver draws a border; if NO, it draws no border.

Availability

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

See Also

• – isBordered
• – setBezeled:

Declared In

NSTextField.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Parameters

anObject

The object that acts as the receiver's delegate.

Availability

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

See Also

• – textShouldBeginEditing:
• – textShouldEndEditing:
• – textDidBeginEditing:
• – textDidEndEditing:
• – textDidChange:
• – delegate

Declared In

NSTextField.h

setDrawsBackground:

Controls whether the receiver’s cell draws its background color behind its text.

- (void)setDrawsBackground:(BOOL)flag

Parameters

flag

If YES, the receiver’s cell 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 Mac OS X v10.0 and later.

See Also

• – setBackgroundColor:
• – setDrawsBackground: (NSTextFieldCell)
• – drawsBackground

Related Sample Code

• Quartz Composer QCTV

Declared In

NSTextField.h

setEditable:

Controls whether the user can edit the receiver’s text.

- (void)setEditable:(BOOL)flag

Parameters

flag

If YES, then the user is allowed to both select and edit text. If flag is NO, then the user isn’t permitted to edit text, and the receiver’s selectability is restored to its previous value.

Discussion

For example, if an NSTextField object is selectable but not editable, then made editable for a time, then made not editable, it remains selectable. To guarantee that text is neither editable nor selectable, simply use setSelectable: to turn off selectability.

Availability

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

See Also

• – isEditable

Related Sample Code

• Quartz Composer QCTV

Declared In

NSTextField.h

setImportsGraphics:

Controls whether the receiver allows the user to drag image files into it.

- (void)setImportsGraphics:(BOOL)flag

Parameters

flag

If YES, the receiver accepts dragged images; if NO, it doesn’t. You can add images programmatically regardless of this setting.

Availability

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

See Also

• – setAllowsEditingTextAttributes:
• – setImportsGraphics: (NSTextView)
• – importsGraphics

Declared In

NSTextField.h

setSelectable:

Sets whether the receiver is selectable (but not editable).

- (void)setSelectable:(BOOL)flag

Parameters

flag

If YES, the receiver is made selectable but not editable (use setEditable: to make text both selectable and editable). If NO, the text is neither editable nor selectable.

Availability

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

See Also

• – setEditable:

Related Sample Code

• Quartz Composer QCTV

Declared In

NSTextField.h

setTextColor:

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

- (void)setTextColor:(NSColor *)aColor

Parameters

aColor

The color used to draw text.

Availability

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

See Also

• – setBackgroundColor:
• – setTextColor: (NSTextFieldCell)
• – textColor

Related Sample Code

• Vertex Optimization

Declared In

NSTextField.h

setTitleWithMnemonic:

Sets the receiver’s string value, using the embedded character as the keyboard mnemonic.

- (void)setTitleWithMnemonic:(NSString *)aString

Parameters

aString

The string to set as the title. The first character preceded by an ampersand (‘&’) is used as the mnemonic (the first ampersand character is stripped out).

Discussion

Mnemonics are not supported in Mac OS X.

Availability

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

Declared In

NSTextField.h

textColor

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

- (NSColor *)textColor

Return Value

The color used to draw text.

Availability

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

See Also

• – backgroundColor
• – textColor (NSTextFieldCell)
• – setTextColor:

Declared In

NSTextField.h

textDidBeginEditing:

Posts a notification that the text is about to begin editing to the default notification center.

- (void)textDidBeginEditing:(NSNotification *)aNotification

Parameters

aNotification

The NSControlTextDidBeginEditingNotification notification to post.

Discussion

This action causes the receiver’s delegate to receive a controlTextDidBeginEditing: message. See the NSControl class specification for more information on the text delegate method.

Availability

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

See Also

• – textDidBeginEditing:
• – textDidChange:
• – textShouldEndEditing:
• – textDidEndEditing:

Declared In

NSTextField.h

textDidChange:

Posts a notification that the text has changed and forwards this message to the receiver’s cell if it responds.

- (void)textDidChange:(NSNotification *)aNotification

Parameters

aNotification

The NSControlTextDidChangeNotification notification that is posted to the default notification center.

Discussion

This method causes the receiver’s delegate to receive a controlTextDidChange: message. See the NSControl class specification for more information on the text delegate method.

Availability

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

See Also

• – textShouldBeginEditing:
• – textDidBeginEditing:
• – textShouldEndEditing:
• – textDidEndEditing:

Declared In

NSTextField.h

textDidEndEditing:

Handles an end of editing.

- (void)textDidEndEditing:(NSNotification *)aNotification

Parameters

aNotification

The notification that editing has ended.

Discussion

After validating the new value, posts an NSControlTextDidEndEditingNotification to the default notification center. This posting causes the receiver’s delegate to receive a controlTextDidEndEditing: message. After this message, sends endEditing: to the receiver’ cell and handles the key that caused editing to end:

• If the user ended editing by pressing Return, this method tries to send the receiver’s action to its target; if unsuccessful, it sends performKeyEquivalent: to its NSView (for example, to handle the default button on a panel); if that also fails, the receiver simply selects its text.

• If the user ended editing by pressing Tab or Shift-Tab, the receiver tries to have its NSWindow object select its next or previous key view, using the NSWindow method selectKeyViewFollowingView: or selectKeyViewPrecedingView:. If unsuccessful in doing this, the receiver simply selects its text.

See the NSControl class specification for more information on the text delegate method.

Availability

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

See Also

• – textShouldBeginEditing:
• – textDidBeginEditing:
• – textDidChange:
• – textShouldEndEditing:

Declared In

NSTextField.h

textShouldBeginEditing:

Requests permission to begin editing a text object.

- (BOOL)textShouldBeginEditing:(NSText *)textObject

Parameters

textObject

The object to begin editing.

Return Value

YES if editing should be allowed to occur, NO otherwise.

Discussion

If the receiver isn’t editable, returns NO immediately. If it is editable and its delegate responds to control:textShouldBeginEditing:, this invokes that method and returns the result. Otherwise it simply returns YES to allow editing to occur. See the NSControl class specification for more information on the text delegate method.

Availability

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

See Also

• – textDidBeginEditing:
• – textDidChange:
• – textShouldEndEditing:
• – textDidEndEditing:

Declared In

NSTextField.h

textShouldEndEditing:

Performs validation on the receiver’s new value.

- (BOOL)textShouldEndEditing:(NSText *)textObject

Parameters

textObject

The text object requesting permission to end editing.

Return Value

YES if the new value is valid; otherwise NO.

Discussion

This method validates the receiver's new value using the NSCell method isEntryAcceptable:. If the new value is valid and the delegate responds to control:textShouldEndEditing:, invokes that method and returns the result, in addition beeping if the delegate returns NO. See the NSControl class specification for more information on the text delegate method.

Availability

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

See Also

• – textShouldBeginEditing:
• – textDidBeginEditing:
• – textDidChange:
• – textDidEndEditing:

Declared In

NSTextField.h

---