NAME

XmTextField — the TextField class.

SYNOPSIS

#include <Xm/TextF.h>

DESCRIPTION

TextField widget provides a single line text editor for customizing both user and programmatic interfaces.  It is used for single-line string entry, and forms entry with verification procedures.  It provides an application with a consistent editing system for textual data. 

TextField widget provides separate callback lists to verify movement of the insert cursor, modification of the text, and changes in input focus.  Each of these callbacks provides the verification function with the widget instance, the event that caused the callback, and a data structure specific to the verification type.  From this information the function can verify if the application considers this to be a legitimate state change and can signal the widget whether to continue with the action. 

The user interface tailors a new set of actions.  The key bindings have been added for insert cursor movement, deletion, insertion, and selection of text. 

TextField allows the user to select regions of text.  Selection is based on the model specified in the Inter-Client Communication Conventions Manual (ICCCM).  TextField supports primary and secondary selection. 

Classes
TextField widget inherits behavior and resources from Core and Primitive classes. 

The class pointer is xmTextFieldWidgetClass. 

The class name is XmTextField. 

New Resources
The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNactivateCallback
Specifies the list of callbacks that is called when the user invokes an event that calls the Activate() function.  The type of the structure whose address is passed to this callback is XmAnyCallbackStruct.  The reason sent by the callback is XmCR_ACTIVATE. 

XmNblinkRate
Specifies the blink rate of the text cursor in milliseconds. The time indicated in the blink rate relates to the length of time the cursor is visible and the time the cursor is invisible (i.e., the time it will take to blink the insertion cursor on and off will be 2 times the blink rate).  The cursor will not blink when the blink rate is set to zero. The value must not be negative.

XmNcolumns
Specifies the initial width of the text window measured in character spaces. The value must be greater than 0. The default value depends on the value of the XmNwidth resource.  If no width is specified the default is 20. 

XmNcursorPosition
Indicates the position in the text where the current insert cursor is to be located.  Position is determined by the number of characters from the beginning of the text.

XmNcursorPositionVisible
Indicates that the insert cursor position is marked by a blinking text cursor when the Boolean is True.

XmNeditable
Indicates that the user can edit the text string when set to True. A false value will prohibit the user from editing the text.

XmNfontList
Specifies the font list to be used for TextField. If this value is NULL at initialization, it is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the appropriate default font list of the ancestor widget (XmNdefaultFontList for VendorShell and XmMenuShell, XmNtextFontList for XmBulletinBoard). See XmFontListCreate(3X) to create a font list. 

XmNgainPrimaryCallback
Specifies the list of callbacks that are called when the user invokes an event that cause the text widget to gain ownership of the primary selection. The callback reason for this callback is XmCR_GAIN_PRIMARY.

XmNlosePrimaryCallback
Specifies the list of callbacks that are called when the user invokes an event that cause the text widget to lose ownership of the primary selection. The callback reason for this callback is XmCR_LOSE_PRIMARY.

XmNlosingFocusCallback
Specifies the list of callbacks that is called before TextField widget loses input focus. The type of the structure whose address is passed to this callback is XmTextVerifyCallbackStruct.  The reason sent by the callback is XmCR_LOSING_FOCUS. 

XmNmarginHeight
Specifies the distance between the top edge of the widget window and the text, and the bottom edge of the widget window and the text.

XmNmarginWidth
Specifies the distance between the left edge of the widget window and the text, and the right edge of the widget window and the text.

XmNmaxLength
Specifies the maximum length of the text string that can be entered into text from the keyboard. Strings that are entered using the XmNvalue resource or the XmTextFieldSetString function are truncated by this resource. 

XmNmodifyVerifyCallback
Specifies the list of callbacks that is called before text is deleted from or inserted into TextField. The type of the structure whose address is passed to this callback is XmTextVerifyCallbackStruct.  The reason sent by the callback is XmCR_MODIFYING_TEXT_VALUE. 

XmNmotionVerifyCallback
Specifies the list of callbacks that is called before the insert cursor is moved to a new position. The type of the structure whose address is passed to this callback is XmTextVerifyCallbackStruct.  The reason sent  by the callback is XmCR_MOVING_INSERT_CURSOR. 

XmNpendingDelete
Indicates that pending delete mode is on when the Boolean is True. Pending deletion is defined as deletion of the selected text when an insertion is made.

XmNresizeWidth
Indicates that TextField widget will attempt to resize its width to accommodate all the text contained in the widget when Boolean is True.

XmNselectionArray
Defines the actions for multiple-mouse clicks.  Each mouse click performed within a half of a second of the previous mouse click will increment the index into this array and perform the defined action for that index. The possible actions are:

•XmSELECT_POSITIONS — resets the insert cursor position. 

•XmSELECT_WORD — selects a word. 

•XmSELECT_LINE — selects a line of text. 

XmNselectionArrayCount
Specifies the number of actions that are defined in the XmNselectionArray resource.  The value must not be negative. 

XmNselectThreshold
Specifies the number of pixels of motion that is required to select the next character when selection is performed using the click-drag mode of selection. The value must not be negative.

XmNvalue
Displays the string value.  XtGetValues returns the value of the internal buffer and XtSetValues copies the string values into the internal buffer. 

XmNvalueChangedCallback
Specifies the list of callbacks that is called after text is deleted from or inserted into TextField. The type of the structure whose address is passed to this callback is XmAnyCallbackStruct.  The reason sent by the callback is XmCR_VALUE_CHANGED. 

XmNverifyBell
Specifies whether a bell will sound when an action is reversed during a verification callback.

Inherited Resources
TextField widget inherits behavior and resources from the following superclasses.  For a complete description of these resources, refer to the man page for that superclass.

Callback Information
A pointer to the following structure is passed to each callback:

typedef struct
{
intreason;
XEvent∗ event;
} XmAnyCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

The TextField widget defines a new callback structure for use with verification callbacks.  Note that not all of the fields are relevant for every callback reason.  The application must first look at the reason field and use only the structure members that are valid for the particular reason.  A pointer to the following structure is passed to the

callbacks for XmNlosingFocusCallback, XmNmodifyVerifyCallback, and XmNmotionVerifyCallback. 

typedef struct
{
intreason;
XEvent∗ event;
Booleandoit;
Position currInsert, newInsert;
Position startPos, endPos;
XmTextBlock text;
} XmTextVerifyCallbackStruct, ∗XmTextVerifyPtr;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

doitIndicates whether that action that invoked the callback will be performed.  Setting doit to False negates the action. 

currInsertIndicates the current position of the insert cursor. 

newInsertIndicates the position at which the user attempts to position the insert cursor. 

startPosIndicates the starting position of the text to modify.  If the callback is not a modify verification callback, this value is the same as currInsert. 

endPosIndicates the ending position of the text to modify.  If no text is replaced or deleted, then the value is the same as startPos.  If the callback is not a modify verification callback, this value is the same as currInsert. 

textPoints to a structure of type XmTextBlockRec.  This structure holds the textual information to be inserted. 

typedef struct
{
char∗ ptr;
intlength;
XmTextFormat format
} XmTextBlockRec, ∗XmTextBlock;

ptrIs the text to be inserted.  ptr points to a temporary storage space that is reused after the callback is finished. Therefore, is an application needs to save the text to be inserted, it should copy the text into its own data space. 

lengthSpecifies the length of the text to be inserted. 

formatSpecifies the format of the text (e.g., FMT8BIT). 

The following table describes the reasons for which the individual verification callback structure fields are valid:

Translations

The XmTextField translations are the same as those of XmText when XmNeditMode is set to XmSINGLE_LINE_EDIT. 

Action Routines

The XmTextField action routines are the same as those of XmText when XmNeditMode is set to XmSINGLE_LINE_EDIT. 

Virtual Bindings

The bindings for virtual keys are vendor specific.  For information about bindings for virtual buttons and keys, see VirtualBindings(3X). 

RELATED INFORMATION

Core(3X), XmCreateTextField(3X), XmFontListCreate(3X), XmPrimitive(3X), XmTextFieldClearSelection(3X), XmTextFieldCopy(3X), XmTextFieldCut(3X), XmTextFieldGetBaseline(3X), XmTextFieldGetEditable(3X), XmTextFieldGetInsertionPosition(3X), XmTextFieldGetLastPosition(3X), XmTextFieldGetMaxLength(3X), XmTextFieldGetSelection(3X), XmTextFieldGetSelectionPosition(3X), XmTextFieldGetString(3X), XmTextFieldInsert(3X), XmTextFieldPaste(3X), XmTextFieldPosToXY(3X), XmTextFieldRemove(3X), XmTextFieldReplace(3X), XmTextFieldSetAddMode(3X), XmTextFieldSetEditable(3X), XmTextFieldSetHighlight(3X), XmTextFieldSetInsertionPosition(3X), XmTextFieldSetMaxLength(3X), XmTextFieldSetSelection(3X), XmTextFieldSetString(3X), XmTextFieldShowPosition(3X), and XmTextFieldXYToPos(3X). 

Sun Release 4.0  —  Last change: