TextField

TextField

Inherits From: Control : View : Responder : Object

Declared In: appkit/TextField.h

Class Description

A TextField is a Control object that can display a piece of text that a user can select or edit, and which sends an action message to its target if the user hits the Return key while editing. A TextField can also be linked to other TextFields, so that when the user presses Tab or Shift-Tab, the object assigned as the "next" or "previous" field gets a message to select its text.
A TextField is a good alternative to a Text object for small regions of editable text, since the display of the TextField is achieved by using a global Text object shared by objects all over your application, which saves on memory usage. Each Window also has a Text object used for editing of TextFields (and TextFieldCells in Matrices). A Window's global Text object is called a field editor, since it's attached as needed to a TextField to perform its editing. TextField allows you to specify an object to act as an indirect delegate to the field editor; the TextField itself acts as the Text delegate if it needs to, then passes the delegate method on to its own Text delegate.

Instance Variables

id nextText;
id previousText;
id textDelegate;
SEL errorAction;

nextText The object whose text is selected when Tab is pressed.

previousText The object whose text is selected when Shift-Tab is pressed.

textDelegate Delegate for Text object delegate methods.

errorAction Message sent to the target when a bad value is entered in the field.

Method Types

Initializing the TextField class + setCellClass:

Initializing a new TextField initFrame:

Enabling the TextField setEnabled:

Setting user access to text setSelectable:

isSelectable
setEditable:
isEditable

Editing Text selectText:

Setting Tab key behavior setNextText:

nextText
setPreviousText:
previousText

Assigning a Text delegate setTextDelegate:

textDelegate

Text object delegate methods textWillChange:

textDidChange:
textDidGetKeys:isEmpty:
textWillEnd:
textDidEnd:endChar:

Setting the TextField's value setFloatValue: (Control)

floatValue (Control)
setDoubleValue: (Control)
doubleValue (Control)
setIntValue: (Control)
intValue (Control)
setStringValue: (Control)
setStringValueNoCopy: (Control)
setStringValueNoCopy:shouldFree: (Control)
stringValue (Control)

Modifying graphic attributes setTextColor:

textColor
setTextGray:
textGray
setBackgroundColor:
backgroundColor
setBackgroundGray:
backgroundGray
setBackgroundTransparent:
isBackgroundTransparent
setBezeled:
isBezeled
setBordered:
isBordered

Target and action setErrorAction:

errorAction

Resizing a TextField sizeTo::

Handling events acceptsFirstResponder

mouseDown:

Archiving read:

write:

Class Methods

setCellClass:

+ setCellClass:classId

Configures the TextField class to use instances of classId for its Cells. classId should be the id of a subclass of TextFieldCell, obtained by sending the class message to either the Cell subclass object or to an instance of that subclass. The default Cell class is TextFieldCell. Returns self.
For more on how to safely set a Cell class for your subclass of TextField, see "Creating New Controls" in the Control class specification.

Instance Methods

acceptsFirstResponder

(BOOL)acceptsFirstResponder

Returns YES if the TextField is editable or selectable, NO otherwise.
See also: setEditable:, setSelectable:

backgroundColor

(NXColor)backgroundColor

Returns the color used to draw the background on color displays.
See also: setBackgroundColor:, backgroundGray

backgroundGray

(float)backgroundGray

Returns the gray level used to draw the background on monochrome displays. If the gray level is less than 0, then the background is transparent.
See also: setBackgroundGray:, backgroundColor

errorAction

(SEL)errorAction

Returns the action sent to the target of the TextField when the user enters an illegal value for the Cell type (as set by Cell's setEntryType: method and checked by Cell's isEntryAcceptable: method).
See also: setErrorAction:, setEntryType: (Cell), isEntryAcceptable: (Cell)

initFrame:

initFrame:(const NXRect *)frameRect

Initializes and returns the receiver, a new instance of TextField, with default parameters in the given frame. The string value is set to be empty (not NULL), and the TextField has no target, action, error action, or Text delegate. The TextField is editable, drawn with a bezel, a white background, and black text; the alignment is NX_LEFTALIGNED. The font is set to the user's system font, and the font size is 12.0 point. This is the designated initializer for the TextField class.

isBackgroundTransparent

(BOOL)isBackgroundTransparent

Returns YES if the background of the TextField is transparent (that is, if the background gray is less than 0).
See also: setBackgroundTransparent:

isBezeled

(BOOL)isBezeled

Returns YES if the text is drawn in a bezeled frame.
See also: setBezeled:, isBordered

isBordered

(BOOL)isBordered

Returns YES if the text has a solid black border around it.
See also: setBordered:, isBezeled

isEditable

(BOOL)isEditable

Returns YES if the text is editable and selectable, NO if the text is not editable (though it may be selectable).
See also: setEditable:, isSelectable

isSelectable

(BOOL)isSelectable

Returns YES if the text is selectable, NO otherwise. Selectable text isn't necessarily editable.
See also: setSelectable:, isEditable

mouseDown:

mouseDown:(NXEvent *)theEvent

Overrides the Control method to begin editing or select text if the TextField allows it. You never invoke this method directly, but may override it to implement subclasses of the TextField class. Returns self.
See also: isEditable, isSelectable

nextText

nextText

Returns the object whose text is selected when the user presses Tab while editing the TextField. If that object responds to the selectText: message, the current TextField is deactivated and selectText: is send to the next text.
See also: setNextText:, previousText

previousText

previousText

Returns the object that is selected when the user presses Shift-Tab while editing the TextField. If that object responds to the selectText: message, the current TextField is deactivated and selectText: is sent to the previous text.
See also: setPreviousText:, nextText

read:

read:(NXTypedStream *)stream

Reads the TextField from the typed stream stream. Returns self.
See also: write:

selectText:

selectText:sender

Selects the entire contents of the receiving TextField if it is editable or selectable. If the TextField isn't in a View hierarchy, it has no effect. Returns self.
See also: isEditable, isSelectable

setBackgroundColor:

setBackgroundColor:(NXColor)aColor

Sets the background color for the TextField to aColor. The background color is used only on color displays; on monochrome displays, the background gray is used. Returns self.
See also: backgroundColor, setBackgroundGray:

setBackgroundGray:

setBackgroundGray:(float)value

Sets the gray level that will be used to draw the background on monochrome displays. If value is less than 0.0, no background will be drawn. If the TextField is editable, it should have a background gray greater than or equal to 0.0. Returns self.
See also: backgroundGray, setBackgroundColor:

setBackgroundTransparent:

setBackgroundTransparent:(BOOL)flag

If flag is YES, sets the background gray of the TextField to transparent (a negative value); if NO, sets the background gray to NX_WHITE. Returns self.
See also: setBackgroundGray:

setBezeled:

setBezeled:(BOOL)flag

If flag is YES, the TextFieldCell is drawn with a bezel around the edge; if NO, nothing is drawn around the text. Bezels and borders are mutually exclusive. If the current background gray is transparent, it's changed to NX_WHITE. Bezeled transparent TextFields look rather strange, but if you want to have one, invoke setBackgroundGray: with 1.0 after invoking setBezeled:.
See also: isBezeled, setBordered:, setBackgroundGray:

setBordered:

setBordered:(BOOL)flag

If flag is YES, a 1-pixel black border will be drawn around the text; if NO, nothing is drawn around the text. Borders and bezels are mutually exclusive. Does not affect the background gray level or color. Returns self.
See also: isBordered, setBezeled:

setEditable:

setEditable:(BOOL)flag

If flag is YES, then the text in the TextField is made both editable and selectable. If NO, the text can't be edited, and is restored to its previous selectable state. For example, if a TextField is set selectable but not editable, then made editable for a time, then made not editable again, it will still be selectable. To guarantee that text will be neither editable nor selectable, simply turn off selectability explicitly. Returns self.
See also: isEditable, setSelectable:

setEnabled:

setEnabled:(BOOL)flag

Makes the TextField enabled (able to accept mouse clicks and keystrokes) according to flag. Redraws the text of the cell if autodisplay is on and the enabled state changes. Returns self.
See also: isEnabled (Control)

setErrorAction:

setErrorAction:(SEL)aSelector

Sets the action sent to the target of the TextField when the user enters an illegal value for the Cell's entry type (as set by Cell's setEntryType: method and checked by Cell's isEntryAcceptable: method). Returns self.
See also: errorAction, setEntryType: (Cell), isEntryAccectable: (Cell)

setNextText:

setNextText:anObject

Sets up anObject as the object whose text will be selected when the user presses Tab while editing the TextField's text. anObject should respond to the selectText: message. If anObject also responds to both selectText: and setPrevious:, it's sent setPreviousText: with the receiving TextField as the argument; this builds a two-way connection, so that pressing Tab in the TextField selects anObject's text, and pressing Shift-Tab in anObject selects the TextField's text. Returns self.
See also: nextText, setPreviousText:, selectText:

setPreviousText:

setPreviousText:anObject

Sets up anObject as the object whose text will be selected when the user presses Shift-Tab while editing the TextField's text. anObject should respond to the selectText: message. Your code shouldn't need to use this method directly, since it's invoked automatically by setNextText:. In deference to setNextText:, this method doesn't build a two-way connection. Returns self.
See also: previousText, setNextText:, selectText:

setSelectable:

setSelectable:(BOOL)flag

If flag is YES, then the TextField is made selectable but not editable (use setEditable: to make text both selectable and editable). If NO, then the text is made neither editable nor selectable. Returns self.
See also: isSelectable, setEditable:

setTextColor:

setTextColor:(NXColor)aColor

Sets the color used to draw the text. On monochrome displays this can result in unsightly dithering of text, so this method should only be used if the TextField responds YES to a shouldDrawColor message. setTextColor: doesn't cause the text to be redrawn. Returns self.
See also: textColor, setTextGray:

setTextDelegate:

setTextDelegate:anObject

Sets the object to which the TextField will pass along any messages from the field editor. These messages include text:isEmpty:, textWillEnd:, textDidEnd:endChar:, textWillChange:, and textDidChange:. Returns self.
See also: textDelegate, Text delegate methods

setTextGray:

setTextGray:(float)value

Sets the gray level used to draw the text, regardless of the color capability of the display. value should lie in the range 0.0 (indicating black) to 1.0 (indicating white). To specify one of the four pure shades of gray, use one of these constants:

Constant Shade

NX_WHITE White

NX_LTGRAY Light gray

NX_DKGRAY Dark gray

NX_BLACK Black

A setTextGray: message doesn't cause the text to be redrawn. Returns self.
See also: textGray, setTextColor:

sizeTo::

sizeTo:(float)width :(float)height

Resizes the TextField to width and height, aborting any editing in the TextField. After the TextField is resized, this method reselects all the text. Returns self.

textColor

(NXColor)textColor

Returns the color used to draw the text. Returns self.
See also: setTextColor:, textGray

textDelegate

textDelegate

Returns the object that receives messages passed on by the TextField from the field editor.
See also: setTextDelegate:

textDidChange:

textDidChange:textObject

Passes this message on, with the same argument, to the TextField's Text delegate. Override this method if you want your subclass of TextField to act as the field editor's delegate. Returns self.
See also: textDidChange: (Text delegate)

textDidEnd:endChar:

textDidEnd:textObject endChar:(unsigned short)whyEnd

Invoked by textObject (the field editor) when text editing ends. Passes this message on, with the same argument, to the TextField's Text delegate, then ends editing for the field editor and checks whyEnd to see if an action key (Return or Tab) was pressed. If Return was pressed, the action message is sent to the target. If Tab was pressed, selectText: is sent to the next text if there is one and it responds, or to self if not. If Shift-Tab was pressed, selectText: is sent to the previous text if there is one and it responds, or to self if not. Returns the object sent the selectText: message.
You may want to override this method to interpret more characters (such as the Enter or Escape keys) in ending editing.
See also: sendAction:to: (Control), setNextText:, setPreviousText:, textDidEnd:endChar: (Text delegate)

textDidGetKeys:isEmpty:

textDidGetKeys:textObject isEmpty:(BOOL)flag

textGray

(float)textGray

Returns the gray level used to draw the text. Returns self.
See also: setTextGray:, textColor

textWillChange:

(BOOL)textWillChange:textObject

Invoked automatically during editing to determine if it is okay to edit the TextField. This method checks whether the TextField is editable and sends textWillChange: to the TextField's Text delegate to allow it to respond. Returns YES if the text isn't editable, NO if the text is editable but the TextField's Text delegate doesn't respond to textWillChange:, and the text delegate's return value for textWillChange: if the TextField's Text delegate responds to it.
See also: setEditable:, setTextDelegate:, textWillChange: (Text delegate)

textWillEnd:

(BOOL)textWillEnd:textObject

Invoked automatically before text editing ends. Checks the text by sending isEntryAcceptable: to the TextField's Cell. If the entry isn't acceptable, sends the error action to the target. This method is then passed on to the TextField's Text delegate with the same argument. The return value is based on whether the entry is acceptable and on the return value from the TextField's Text delegate. If the delegate responds to textWillEnd:, this method returns NO if the entry is acceptable and the delegate returns NO. Otherwise this method returns YES to indicate that editing shouldn't end, and generates a beep to indicate an error in the entry.
See also: isEntryAcceptable: (Cell), setTextDelegate:, textWillEnd: (Text delegate)

write:

write:(NXTypedStream *)stream

Writes the receiving TextField to the typed stream stream. Returns self.
See also: read:

	Inherits From:	Control : View : Responder : Object

	Declared In:	appkit/TextField.h

	nextText	The object whose text is selected when Tab is pressed.

	previousText	The object whose text is selected when Shift-Tab is pressed.

	textDelegate	Delegate for Text object delegate methods.

	errorAction	Message sent to the target when a bad value is entered in the field.

	Initializing the TextField class	+ setCellClass:

	Initializing a new TextField	initFrame:

	Enabling the TextField	setEnabled:

	Setting user access to text	setSelectable:

	Resizing a TextField	sizeTo::

	Handling events	acceptsFirstResponder

	Constant	Shade

	NX_WHITE	White
	NX_LTGRAY	Light gray
	NX_DKGRAY	Dark gray
	NX_BLACK	Black