Manual pages › OPEN LOOK widgets (3W)
olTextField(3W)
TextField
From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.
WIDGET CLASS NAME · SYNOPSIS · DESCRIPTION · RESOURCES · WARNINGS
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 elements:
- Input Caret
- Input Field
- Left Arrow (conditional)
- Right Arrow (conditional)
Figure 1. One-Line Text Field
Amiga Unix Last change: 1
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, NEXTFIELD 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
________________________________________________________
|_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-v, 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
changing the input focus.
Amiga Unix Last change: 4
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
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 XtNbackground 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 application programmer should recognize this in designing the application. One alternative is not to do per-field validation but to do per-form validation instead.
Amiga Unix Last change: 4