---

NSTextField

Overview

An NSTextField 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.

NSTextField uses NSTextFieldCell to implement its user interface.

Tasks

Constructors

• NSTextField

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

Text Delegate Methods

• textShouldBeginEditing
• textDidBeginEditing
• textDidChange
• textShouldEndEditing
• textDidEndEditing

Instance Methods

acceptsFirstResponder

Returns true if the receiver is editable, false otherwise.

public boolean acceptsFirstResponder()

allowsEditingTextAttributes

Returns true if the receiver allows the user to change font attributes of the receiver’s text, false if the user isn’t permitted to do so.

public boolean allowsEditingTextAttributes()

Discussion

You can change text attributes programmatically regardless of this setting.

See Also

• importsGraphics
• setAllowsEditingTextAttributes

backgroundColor

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

public NSColor backgroundColor()

See Also

• drawsBackground
• setBackgroundColor

bezelStyle

Returns the receiver’s bezel style.

public int bezelStyle()

Discussion

Possible return values are described in NSTextFieldCell’s “Constants.”

Availability

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

See Also

• setBezelStyle

delegate

Returns the receiver’s delegate.

public Object delegate()

See Also

• textShouldBeginEditing
• textShouldEndEditing
• textDidBeginEditing
• textDidEndEditing
• textDidChange
• setDelegate

drawsBackground

Returns true if the receiver’s cell draws its background color behind its text, false if it draws no background.

public boolean drawsBackground()

See Also

• backgroundColor
• drawsBackground (NSTextFieldCell)
• setDrawsBackground

importsGraphics

Returns true if the receiver allows the user to drag image files into it, false if it doesn’t accept dragged images.

public boolean importsGraphics()

Discussion

You can add images programmatically regardless of this setting.

See Also

• allowsEditingTextAttributes
• importsGraphics (NSTextView)
• setImportsGraphics

isBezeled

Returns true if the receiver draws a bezeled frame around its contents, false if it doesn’t.

public boolean isBezeled()

See Also

• isBordered
• setBezeled

isBordered

Returns true if the receiver draws a solid black border around its contents, false if it doesn’t.

public boolean isBordered()

See Also

• isBezeled
• setBordered

isEditable

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

public boolean isEditable()

See Also

• isSelectable
• setEditable

isSelectable

Returns true if the user is allowed to select the receiver’s text, false if the user isn’t allowed to select it.

public boolean isSelectable()

Discussion

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

See Also

• setSelectable

selectText

This action method ends editing and selects the entire contents of the receiver if it’s selectable.

public void selectText(Object sender)

Discussion

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

See Also

• isSelectable

setAllowsEditingTextAttributes

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

public void setAllowsEditingTextAttributes(boolean flag)

Discussion

If flag is true, the user is permitted to make such changes; if flag is false, the user isn’t so permitted. You can change text attributes programmatically regardless of this setting.

See Also

• setImportsGraphics
• allowsEditingTextAttributes

setBackgroundColor

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

public void setBackgroundColor(NSColor aColor)

See Also

• setDrawsBackground
• backgroundColor

setBezeled

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

public void setBezeled(boolean flag)

Discussion

If flag is false, it draws no border; if flag is true, it draws a bezeled border and invokes setDrawsBackground with an argument of false.

See Also

• isBezeled
• setBordered

setBezelStyle

Sets the receiver’s bezel style to be style.

public void setBezelStyle(int style)

Discussion

Possible values for style are described in NSTextFieldCell’s “Constants.” You must have already sent the receiver setBezeled with an argument of true.

Availability

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

See Also

• bezelStyle

setBordered

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

public void setBordered(boolean flag)

Discussion

If flag is true, then it draws a border; if flag is false, it draws no border.

See Also

• isBordered
• setBezeled

setDelegate

Sets the receiver’s delegate to anObject.

public void setDelegate(Object anObject)

See Also

• textShouldBeginEditing
• textShouldEndEditing
• textDidBeginEditing
• textDidEndEditing
• textDidChange
• delegate

setDrawsBackground

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

public void setDrawsBackground(boolean flag)

Discussion

If flag is true, then it does; if flag is false, then it draws nothing behind its text.

See Also

• setBackgroundColor
• setDrawsBackground (NSTextFieldCell)
• drawsBackground

setEditable

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

public void setEditable(boolean flag)

Discussion

If flag is true, then the user is allowed to both select and edit text. If flag is false, then the user isn’t permitted to edit text, and the receiver’s selectability is restored to its previous value. For example, if an NSTextField 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.

See Also

• isEditable

setImportsGraphics

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

public void setImportsGraphics(boolean flag)

Discussion

If flag is true, the receiver accepts dragged images; if flag is false, it doesn’t. You can add images programmatically regardless of this setting.

See Also

• setAllowsEditingTextAttributes
• setImportsGraphics (NSTextView)
• importsGraphics

setSelectable

public void setSelectable(boolean flag)

Discussion

If flag is true, the receiver is made selectable but not editable (use setEditable to make text both selectable and editable). If false, then the text is made neither editable nor selectable.

See Also

• setEditable

setTextColor

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

public void setTextColor(NSColor aColor)

See Also

• setBackgroundColor
• setTextColor (NSTextFieldCell)
• textColor

setTitleWithMnemonic

Sets the receiver’s string value to aString, using the first character preceded by an ampersand (‘&’) as the mnemonic and stripping out that first ampersand character.

public void setTitleWithMnemonic(String aString)

Discussion

Mnemonics are not supported in Mac OS X.

textColor

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

public NSColor textColor()

See Also

• backgroundColor
• textColor (NSTextFieldCell)
• setTextColor

textDidBeginEditing

Posts a ControlTextDidBeginEditingNotification to the default notification center.

public void textDidBeginEditing(NSNotification aNotification)

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.

See Also

• textDidBeginEditing
• textDidChange
• textShouldEndEditing
• textDidEndEditing

textDidChange

Forwards this message to the receiver’s cell if it responds and posts a ControlTextDidChangeNotification to the default notification center.

public void textDidChange(NSNotification aNotification)

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.

See Also

• textShouldBeginEditing
• textDidBeginEditing
• textShouldEndEditing
• textDidEndEditing

textDidEndEditing

Handles an end of editing NSNotification aNotification.

public void textDidEndEditing(NSNotification aNotification)

Discussion

After validating the new value, posts a ControlTextDidEndEditingNotification 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 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.

See Also

• textShouldBeginEditing
• textDidBeginEditing
• textDidChange
• textShouldEndEditing

textShouldBeginEditing

public boolean textShouldBeginEditing(NSText textObject)

Discussion

If the receiver isn’t editable, returns false immediately. If it is editable and its delegate responds to controlTextShouldBeginEditing, invokes that method and returns the result. Otherwise simply returns true to allow editing to occur. The textObject argument is the NSText object that invoked this method. See the NSControl class specification for more information on the text delegate method.

See Also

• textDidBeginEditing
• textDidChange
• textShouldEndEditing
• textDidEndEditing

textShouldEndEditing

Performs validation on the receiver’s new value using NSCell’s isEntryAcceptable, sending the receiver’s error action to its target if validation fails.

public boolean textShouldEndEditing(NSText textObject)

Discussion

If the new value is valid and the delegate responds to controlTextShouldEndEditing, invokes that method and returns the result, in addition beeping if the delegate returns false. The textObject argument is the NSText object that invoked this method. See the NSControl class specification for more information on the text delegate method.

See Also

• textShouldBeginEditing
• textDidBeginEditing
• textDidChange
• textDidEndEditing

---