XmTextField(3X) UNIX System V XmTextField(3X)
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).
10/89 Page 1
XmTextField(3X) UNIX System V XmTextField(3X)
_________________________________________________________________________________________________
XmTextFieldResource Set
_________________________________________________________________________________________________
Name Class Type Default Access
_________________________________________________________________________________________________
_________________________________________________________________________________________________
XmNactivateCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNblinkRate XmCBlinkRate int 500 CSG
_________________________________________________________________________________________________
XmNcolumns XmCColumns short dynamic CSG
_________________________________________________________________________________________________
XmNcursorPosition XmCCursorPosition XmTextPosition 0 CSG
_________________________________________________________________________________________________
XmNcursorPositionVisible XmCCursorPositionVisible Boolean True CSG
_________________________________________________________________________________________________
XmNeditable XmCEditable Boolean True CSG
_________________________________________________________________________________________________
XmNfontList XmCFontList XmFontList dynamic CSG
_________________________________________________________________________________________________
XmNgainPrimaryCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNlosePrimaryCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNlosingFocusCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNmarginHeight XmCMarginHeight Dimension 5 CSG
_________________________________________________________________________________________________
XmNmarginWidth XmCMarginWidth Dimension 5 CSG
_________________________________________________________________________________________________
XmNmaxLength XmCMaxLength int largest integer CSG
_________________________________________________________________________________________________
XmNmodifyVerifyCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNmotionVerifyCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNpendingDelete XmCPendingDelete Boolean True CSG
_________________________________________________________________________________________________
XmNresizeWidth XmCResizeWidth Boolean False CSG
_________________________________________________________________________________________________
XmNselectionArray XmCSelectionArray Pointer default array CSG
_________________________________________________________________________________________________
XmNselectionArrayCount XmCSelectionArrayCount int 3 CSG
_________________________________________________________________________________________________
XmNselectThreshold XmCSelectThreshold int 5 CSG
_________________________________________________________________________________________________
XmNvalue XmCValue String "" CSG
_________________________________________________________________________________________________
XmNvalueChangedCallback XmCCallback XtCallbackList NULL C
_________________________________________________________________________________________________
XmNverifyBell XmCVerifyBell Boolean True CSG
_________________________________________________________________________________________________
Page 2 10/89
XmTextField(3X) UNIX System V XmTextField(3X)
| | | |
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
10/89 Page 3
XmTextField(3X) UNIX System V XmTextField(3X)
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.
Page 4 10/89
XmTextField(3X) UNIX System V XmTextField(3X)
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.
10/89 Page 5
XmTextField(3X) UNIX System V XmTextField(3X)
__________________________________________________________________________________________________
| XmPrimitive Resource Set |
|_____________________|_______________________|__________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________|_______________________|__________________|______________________|________|
|_____________________|_______________________|__________________|______________________|________|
|XmNbottomShadowColor | XmCBottomShadowColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNbottomShadowPixmap| XmCBottomShadowPixmap| Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNforeground | XmCForeground | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightColor | XmCHighlightColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightOnEnter | XmCHighlightOnEnter | Boolean | False | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightThickness| XmCHighlightThickness| Dimension | 2 | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType| XmTAB_GROUP | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | 2 | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtopShadowColor | XmCTopShadowColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_______________________|__________________|______________________|________|
Page 6 10/89
XmTextField(3X) UNIX System V XmTextField(3X)
________________________________________________________________________________________________________________
| Core Resource Set |
|_____________________________|_______________________________|________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________________|_______________________________|________________|______________________|________|
|_____________________________|_______________________________|________________|______________________|________|
|XmNaccelerators | XmCAccelerators | XtAccelerators| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackground | XmCBackground | Pixel | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNcolormap | XmCColormap | Colormap | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdepth | XmCDepth | int | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdestroyCallback | XmCCallback | XtCallbackList| NULL | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNheight | XmCHeight | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNinitialResourcesPersistent| XmCInitialResourcesPersistent| Boolean | True | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNscreen | XmCScreen | Screen * | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNsensitive | XmCSensitive | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNtranslations | XmCTranslations | XtTranslations| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNwidth | XmCWidth | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNx | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNy | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
int reason;
10/89 Page 7
XmTextField(3X) UNIX System V XmTextField(3X)
XEvent * event;
} XmAnyCallbackStruct;
reason Indicates why the callback was invoked.
event Points 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
{
int reason;
XEvent * event;
Boolean doit;
Position currInsert, newInsert;
Position startPos, endPos;
XmTextBlock text;
} XmTextVerifyCallbackStruct, *XmTextVerifyPtr;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
doit Indicates whether that action that invoked the callback will
be performed. Setting doit to False negates the action.
currInsert
Indicates the current position of the insert cursor.
newInsert
Indicates the position at which the user attempts to position
the insert cursor.
startPos
Indicates the starting position of the text to modify. If
the callback is not a modify verification callback, this
value is the same as currInsert.
endPos Indicates 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.
Page 8 10/89
XmTextField(3X) UNIX System V XmTextField(3X)
text Points to a structure of type XmTextBlockRec. This structure
holds the textual information to be inserted.
typedef struct
{
char * ptr;
int length;
XmTextFormat format
} XmTextBlockRec, *XmTextBlock;
ptr Is 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.
length Specifies the length of the text to be inserted.
format Specifies the format of the text (e.g., FMT8BIT).
The following table describes the reasons for which the individual
verification callback structure fields are valid:
________________________________________________________
| Reason | Valid Fields |
|__________________________|____________________________|
| XmCR_LOSING_FOCUS | reason, event, doit |
| | |
| XmCR_MODIFYING_TEXT_VALUE| reason, event, doit,|
| | currInsert, newInsert,|
| | startPos, endPos, text |
| | |
| XmCR_MOVING_TEXT_CURSOR | reason, event, doit,|
| | currInsert, newInsert |
|__________________________|____________________________|
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.
10/89 Page 9
XmTextField(3X) UNIX System V XmTextField(3X)
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).
Page 10 10/89