NSTextField Class Reference

Inherits from
NSControl : NSView : NSResponder : NSObject
Conforms to
NSUserInterfaceValidations
NSAnimatablePropertyContainer (NSView)
NSUserInterfaceItemIdentification (NSView)
NSDraggingDestination (NSView)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Cocoa Text Architecture Guide
Declared in
NSTextField.h
Related sample code

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.

The parent class, NSControl, provides the methods for setting the values of the text field, for example: setStringValue:, setDoubleValue:, etc.. There are corresponding methods to retrieve values.

Tasks

Controlling Selection and Editing

Controlling Rich Text Behavior

Setting the Text Color

Autolayout Sizing

Controlling the Background

Setting a Border

Selecting the Text

Working with the Responder Chain

Using Keyboard Interface Control

Setting the Delegate

NSText Delegate Method Implementations

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 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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
Declared In
NSTextField.h

bezelStyle

Returns the receiver’s bezel style.

- (NSTextFieldBezelStyle)bezelStyle
Return Value

A constant indicating the bezel style. Possible values described in NSTextFieldBezelStyle.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
NSTextField.h

delegate

Returns the receiver’s delegate.

- (id < NSTextFieldDelegate >)delegate
Return Value

The object that acts as the receiver's delegate.

Availability
  • Available in OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 determine if the text is editable.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTextField.h

preferredMaxLayoutWidth

Returns the preferred maximum layout width.

- (CGFloat)preferredMaxLayoutWidth
Return Value

The preferred maximum layout width.

Availability
  • Available in OS X v10.8 and later.
See Also
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 OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSTextField.h

setAllowsEditingTextAttributes:

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

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

If YES, and the text value is an attributed string, it is displayed using the attributed string’s visual settings, which can be modified in the font panel.; if flag is NO and the text is an attributed string. the string attributes (font, color, etc.) are ignored and the string is displayed based on the text field’s settings. Setting the attributed string’s attributes are ignored when displaying the string and when the text field is editing.

Availability
  • Available in OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
Related Sample Code
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 NSTextFieldBezelStyle. You must have already sent the receiver setBezeled: with an argument of YES

Availability
  • Available in OS X v10.2 and later.
See Also
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 OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSTextField.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id < NSTextFieldDelegate >)anObject
Parameters
anObject

The object that acts as the receiver's delegate.

Availability
  • Available in OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 ability to select the receiver’s content is dependent on the value of isSelectable.

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 or selectable, use setSelectable: to disable text selection.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
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 OS X v10.0 and later.
See Also
Declared In
NSTextField.h

setPreferredMaxLayoutWidth:

Sets the preferred maximum width of the text field.

- (void)setPreferredMaxLayoutWidth:(CGFloat)width
Parameters
width

The preferred maximum width.

Discussion

The value determines the maximum width of the intrinsicContentSize. If the text field wraps, the intrinsic height will be large enough to show the entire text contents at that width.

The default is 0, which implies no maximum preferred width.

Availability
  • Available in OS X v10.8 and later.
See Also
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 OS X v10.0 and later.
See Also
Related Sample Code
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 OS X v10.0 and later.
See Also
Related Sample Code
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
Declared In
NSTextField.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...