TEXTFIELD WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
TE
SXTFIELD WIDGET(3W)
WIDGET CLASS NAME
TextField
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <TextField.h>
widget = XtCreateWidget(name, textFieldWidgetClass, ...);
DESCRIPTION
TextField Components The TextField widget is a one-line
input field for text data that contains the following ele-
ments:
- Input Caret
- Input Field
- Left Arrow (conditional)
- Right Arrow (conditional)
Figure 1. One-Line Text Field
Amiga Unix Last change: 1
TEXTFIELD WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
TE
SXTFIELD WIDGET(3W)
Keyboard Input Once the input focus has been moved to the
Input Field, keyboard entry is allowed. The TextField
widget does not validate the input, leaving that up to the
application.
Keyboard Traversal Users can traverse among Text and Text-
Field widgets within any ancestor ControlArea, Bulletin-
Board, or Form widget using the NEXTFIELD and PREVFIELD
keys:
- NEXTFIELD moves the caret to the next traversable Text
or TextField widget in the managing ancestor widget.
When the caret is in the last traversable field, NEXT-
FIELD moves the caret to the first traversable field.
- PREVFIELD moves the caret to the previous traversable
field in the managing ancestor widget. When the caret
is in the first traversable field, PREVFIELD moves the
caret to the last traversable field. The default key
mappings for NEXTFIELD and PREVFIELD are TAB and
SHIFT-TAB , respectively. A user may change these
defaults through the appropriate Workspace Properties
window.
Editing Capabilities The TextField provides the editing
capabilities listed in the following table. (This is a
subset of the editing capabilities of the Text widget;
this does not imply that the TextField widget is neces-
sarily implemented as a subclass of the Text widget.)
_________________________________________________________________________________
|_Name_______|_Editing_Action____________________________________________________|
| CHARFWD | Move the caret forward one character |
| CHARBAK | Move the caret back one character |
| WORDFWD | Move the caret forward one word |
| WORDBAK | Move the caret back one word |
| LINESTART | Move the caret to the beginning of the current display line |
| LINEEND | Move the caret to the end of the current display line |
| DOCSTART | Move the caret to the beginning of the source |
| DOCEND | Move the caret to the end of the source |
| DELCHARFWD | Delete the character to the right of the caret |
| DELCHARBAK | Delete the character to the left of the caret |
| DELWORDFWD | Delete the word to the right of the caret |
| DELWORDBAK | Delete the word to the left of the caret |
| DELLINEFWD | Delete to the end of the current display line from the caret |
| DELLINEBAK | Delete to the beginning of the current display line from the caret|
|____________|___________________________________________________________________|
This second table displays the virtual expressions and
keyboard equivalents for the editing functions. See
VIRTUAL KEY/BUTTON(3W) earlier in this guide for more
information on virtual expressions.
Amiga Unix Last change: 2
TEXTFIELD WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
TE
SXTFIELD WIDGET(3W)
________________________________________________________
|_Name______|__Virtual_Expression|__Keyboard_Equivalents|
| CHARFWD | charFwdKey | CTRL-F, -> |
| CHARBAK | charBakKey | CTRL-B, <- |
| WORDFWD | wordFwdKey | ALT-F, ALT- -> |
| WORDBAK | wordBakKey | ALT-B, ALT- <- |
| LINESTART | lineStartKey | CTRL-A, CTRL- <- |
| LINEEND | lineEndKey | CTRL-E, CTRL- -> |
| DOCSTART | docStartKey | ALT-↑, ALT- < |
| DOCEND | docEndKey | ALT-↓, ALT- > |
| DELCHARFWD| delCharFwdKey | CTRL-D, DELETE |
| DELCHARBAK| delCharBakKey | CTRL-H, BACKSPACE |
| DELWRDFWD | delWordFwdKey | ALT-D |
| DELWORDBAK| delWordBakKey | ALT-H |
| DELLINEFWD| delLineFwdKey | CTRL-K |
| DELLINEBAK| delLineBakKey | ALT-K |
|___________|____________________|______________________|
Scrolling Long Text Input If an input value exceeds the
length of the Input Field, the Left Arrow and/or Right
Arrow appear and the input value is visually truncated
on the left and/or the right to show only as many char-
acters as can fit in the Input Field. The truncation
is at a character boundary. Since the Arrows take up
space that would otherwise be used for the input, the
truncation is more severe than would be necessary if
they were not visible. An Arrow is present only if
characters are hidden in the direction expressed by the
arrow. The user can scroll to show the hidden parts of
the input by clicking or pressing SELECT on the Left or
Right Arrow. Clicking SELECT on the Left Arrow scrolls
the input one character to the right to show the next
character that was hidden to the left. Clicking SELECT
on the Right Arrow scrolls the input one character to
the left to show the next character that was hidden to
the right. Pressing SELECT scrolls continuously, with
a user-adjustable wait between changes. The text does
not scroll beyond its limits, so that the left-most
character never moves beyond the right edge of the
TextField widget and the right-most character never
moves beyond the left edge. If the user attempts to
scroll beyond the limits by clicking SELECT, the system
beeps. If the user is pressing SELECT when the limit
is reached, the text stops scrolling but the system
does not beep. If the user releases SELECT and then
presses SELECT again to exceed the scrolling limit, the
system beeps once regardless of how long SELECT is
pressed.
Input Validation When the input focus changes from the
TextField widget, or when the user presses RETURN, the
application is given the input value for validation.
The application action is not specified, except that it
cannot force the user to correct the input before
Amiga Unix Last change: 3
TEXTFIELD WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
TE
SXTFIELD WIDGET(3W)
changing the input focus.
Amiga Unix Last change: 4
TEXTFIELD WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
TE
SXTFIELD WIDGET(3W)
Position of the Input Caret As characters are entered
from the keyboard, the Input Caret moves to the right
until it reaches the right end of the Input Field. As
additional characters are typed the text scrolls to the
left (the Left Arrow appears as discussed above) and
the Input Caret moves relative to the text but remains
stationary on the screen.
Selecting and Operating on the Input Field The Text-
Field widget allows text to be copied or moved to and
from the Input Field. See TEXT SELECTION(3W) earlier
in this manual for the description of these operations.
TextField Coloration Figure 2 illustrates the resources
that affect the coloration of the TextField widget.
Figure 2. Text Field Coloration
Amiga Unix Last change: 5
TEXTFIELD WIDGET(3W)
MISC. REFERENCE MANUAL PAGE
TE
SXTFIELD WIDGET(3W)
RESOURCES
__________________________________________________________________________________________
_______________________________TextField_Resource_Set\*(cO________________________________
Name Class Type Default Access
__________________________________________________________________________________________
Amiga Unix Last change: 6
() MISC. REFERENCE MANUAL PAGES ()
__________________________________________________________________________________________
_XtNancestorSensitive___XtCSenstitive__________Boolean__________TRUE_______________G*_____
| XtNbackground XtCBackground Pixel White SGI† |
|_____________________|______________________|________________|__________________|________|
|_XtNbackgroundPixmap_|__XtCPixmap___________|__Pixmap________|__(none)__________|__SGI†__|
| XtNdepth | XtCDepth | int | (parent's) | GI |
|_____________________|______________________|________________|__________________|________|
|_XtNdestroyCallback__|__XtCCallback_________|__XtCallbackList|__NULL____________|__SI____|
| XtNfont | XtCFont | XFontStruct * | (OPEN LOOK font)| SI |
|_____________________|______________________|________________|__________________|________|
|_XtNfontColor________|__XtCFontColor________|__Pixel_________|__Black*__________|__SGI___|
| XtNforeground | XtCForeground | Pixel | Black | SGI† |
|_____________________|______________________|________________|__________________|________|
|_XtNheight___________|__XtCHeight___________|__Dimension_____|__(calculated)____|__SGI___|
| XtNmappedWhenManaged| XtCMappedWhenManaged| Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
|_XtNmaximumSize______|__XtCLength___________|__int___________|__(none)__________|__SGI___|
| XtNreferenceWidget | XtCReferenceWidget | Widget | (Widget)0 | GI |
|_____________________|______________________|________________|__________________|________|
|_XtNsensitive________|__XtCSensitive________|__Boolean_______|__TRUE____________|__GI*___|
| XtNstring | XtCString | String | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
|_XtNtraversalOn______|__XtCTraversalOn______|__Boolean_______|__TRUE____________|__SGI___|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
|_XtNverification_____|__XtCCallback_________|__XtCallbackList|__NULL____________|__SI____|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|______________________|________________|__________________|________|
|_XtNx________________|__XtCPosition_________|__Position______|__0_______________|__SGI___|
| XtNy | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|________________|__________________|________|
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
This resource identifies the font to be used to display the
Input Field. The default value points to a cached font
structure; an application should not expect to get this
value with a call to XtGetValues() and use it reliably
thereafter.
XtNfontColor
Range of Values:
(any Pixel value valid for the current display)/(any
name from the rgb.txt file)
This resource specifies the color for the font. If not set,
the color from the XtNforeground resource, if available, is
used for the font.
Amiga Unix Last change: 1
() MISC. REFERENCE MANUAL PAGES ()
See the note about the interaction of this resource with
other color resources under the description of the XtNback-
ground resource in CORE RESOURCES(3W).
Amiga Unix Last change: 2
() MISC. REFERENCE MANUAL PAGES ()
XtNforeground This resource defines the foreground color for
the widget. See the note about the interaction of this
resource with other color resources under the description of
the XtNbackground resource in CORE RESOURCES(3W).
XtNmaximumSize
Range of Values:
0 < XtNmaximumSize
This resource is the maximum number of characters that can
be entered into the internal buffer. If this value is not
set or is zero, the internal buffer will increase its size
as needed limited only by the space limitations of the pro-
cess.
XtNreferenceWidget
This resource specifies a position for inserting the current
widget in its managing ancestor's traversal list. If the
reference widget is non-null and exists in the managing
ancestor's traversal list, the current widget will be
inserted in front of it. Otherwise, the current widget will
be inserted at the end of the list.
XtNstring This is the content of the Input Field. On being
set a copy of the value is made in an internal buffer.
Using XtGetValues() on this resource gets a new copy that
the application is responsible for freeing when no longer
needed.
XtNtraversalOn Range of Values:
TRUE
FALSE
This resource specifies whether this widget is selectable
during traversal.
XtNverification This callback list is issued when the user
presses the RETURN or TAB key or moves the input focus out
of the TextField widget. The call_data parameter is a
pointer to a structure, OlTextFieldVerify, that looks like
this:
typedef struct _OlTextFieldVerify {
String string;
Boolean ok;
} OlTextFieldVerify;
string gives a pointer to the content of the text field.
It is not a copy but a pointer to an internal
buffer. The application should copy the buffer if
it needs to keep the data intact longer than the
duration of the callback.
ok is currently unused.
Amiga Unix Last change: 3
() MISC. REFERENCE MANUAL PAGES ()
WARNINGS
The XtNverification callback is issued whenever the user
presses RETURN or TAB and whenever the TextField widget
loses input focus. Unfortunately, the loss of input focus
can occur for many different reasons, such as the mapping of
a pop-up window. An application may not want to have to
validate a field each time a user brings up a pop-up window.
(The user may be doing this to look up some information to
fill in the field correctly.) But the callbacks are issued
usually because of loss of input focus. Thus, an applica-
tion programmer should recognize this in designing the
application. One alternative is not to do per-field valida-
tion but to do per-form validation instead.
Amiga Unix Last change: 4