TextField(3W) UNIX System V TextField(3W)
NAME
TextField - provides a one-line editable text field
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
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
The default value of the XtNtraversalOn resource is True.
The TextField widget responds to the following keyboard navigation keys:
- NEXT_FIELD and DOWN move to the next traversable widget in the window
- PREV_FIELD and UP move to the previous traversable widget in the window
- NEXTWINDOW moves to the next window in the application
- PREVWINDOW moves to the previous window in the application
- NEXTAPP moves to the first window in the next application
- PREVAPP moves to the first window in the previous application
- CHARBAK moves the caret backward one character
10/89 Page 1
TextField(3W) UNIX System V TextField(3W)
- CHARFWD moves the caret forward one character
- WORDFWD moves the caret forward one word
- WORDBAK moves the caret back one word
- LINESTART moves the caret to the beginning of the display
- LINEEND moves the caret to the end of the display
The MENUKEY posts the menu attached to the TextField.
The TextField widget responds to the following selection keys:
- SELCHARFWD adjusts the selection one character forward
- SELWORDFWD adjusts the selection to the end of the current (or next)
word
- SELLINEFWD adjusts the selection to the end of the current (or next)
line
- SELCHARBAK adjusts the selection one character backward
- SELWORDBAK adjusts the selection to the beginning of the current (or
previous) word
- SELLINEBAK adjusts the selection to the beginning of the current (or
previous) line
- SELLINE adjusts the selection to include the entire current line
- SELFLIPENDS reverses the "anchor" and cursor position of the selection
The TextField widget responds to the following scrolling keys:
- SCROLLLEFT scroll the view one screen to the left
- SCROLLRIGHT scroll the view one screen to the right
- SCROLLLEFTEDGE scroll to the left edge of the textfield
- SCROLLRIGHTEDGE scroll to the right edge of the textfield
The TextField widget responds to the following edit keys:
Page 2 10/89
TextField(3W) UNIX System V TextField(3W)
- DELCHARFWD deletes the character to the right of the caret
- DELCHARBAK deletes the character to the left of the caret
- DELWORDFWD deletes the word to the right of the caret
- DELWORDBAK deletes the word to the left of the caret
- DELLINEFWD deletes to the end of the line from the caret
- DELLINEBAK deletes from the beginning of the line to the caret
- DELLINE deletes the line containing the caret
- UNDO undoes the last edit
Display of Keyboard Mnemonic
The TextField does not display the mnemonic. If the TextField is the
child of a Caption widget, the Caption widget can be used to display the
mnemonic.
Display of Keyboard Accelerators
The TextField does not respond to a keyboard accelerator because clicking
the SELECT button on a TextField activates depending on the pointer
position. So, the TextField does not display a keyboard accelerator.
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 characters 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.
10/89 Page 3
TextField(3W) UNIX System V TextField(3W)
Input Validation
A validation callback list can be used to perform limited per-field
validation. This callback is used when the end-user hits the RETURN,
PREV_FIELD, or NEXT_FIELD. It is not called if the user mouses the focus
to another input area.
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 TextField 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.
Coloration
When this widget receives the input focus, it changes the text caret in
the text field to the active caret.
Figure 2 illustrates the resources that affect the coloration of the
TextField widget.
Figure 2. Text Field Coloration
RESOURCES
____________________________________________________________________________________________
| TextField Resource Set |
|_____________________|______________________|_________________|__________________|_________|
| Name | Class | Type | Default | Access |
|_____________________|______________________|_________________|__________________|_________|
____________________________________________________________________________________________
XtNancestorSensitive XtCSenstitive Boolean TRUE G*
____________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
____________________________________________________________________________________________
XtNbackgroundPixmap XtCPixmap Pixmap (none) SGI†
____________________________________________________________________________________________
XtNcharsVisible XtCCharsVisible int 0 GI
____________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SG
____________________________________________________________________________________________
XtNdepth XtCDepth int (parent's) GI
____________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
____________________________________________________________________________________________
XtNfont XtCFont XFontStruct * (OPEN LOOK font) SI
____________________________________________________________________________________________
XtNfontColor XtCFontColor Pixel Black* SGI
____________________________________________________________________________________________
Page 4 10/89
TextField(3W) UNIX System V TextField(3W)
____________________________________________________________________________________________
| TextField Resource Set (cont'd) |
|_____________________|______________________|_________________|__________________|_________|
| Name | Class | Type | Default | Access |
|_____________________|______________________|_________________|__________________|_________|
| XtNforeground | XtCForeground | Pixel | Black | SGI† |
|_____________________|______________________|_________________|__________________|_________|
| XtNheight | XtCHeight | Dimension | (calculated) | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNinputFocusColor | XtCInputFocusColor | Pixel | Black | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNinitialDelay | XtCInitialDelay | int | 500 | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNinsertTab | XtCInsertTab | Boolean | FALSE | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNmappedWhenManaged| XtCMappedWhenManaged| Boolean | TRUE | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNmaximumSize | XtCMaximumSize | int | 0 | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNreferenceName | XtCReferenceName | String | NULL | GI |
|_____________________|______________________|_________________|__________________|_________|
| XtNreferenceWidget | XtCReferenceWidget | Widget | NULL | GI |
|_____________________|______________________|_________________|__________________|_________|
| XtNrepeatRate | XtCRepeatRate | int | 100 | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|______________________|_________________|__________________|_________|
| XtNstring | XtCString | String | NULL | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNtextEditWidget | XtCTextEditWidget | Widget | NULL | G |
|_____________________|______________________|_________________|__________________|_________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNverification | XtCCallback | XtCallbackList | NULL | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|_________________|__________________|_________|
| XtNy | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|_________________|__________________|_________|
XtNcharsVisible
This resource is used to specify the initial width of the list in terms
of characters. It overrides the XtNwidth resource setting. The XtNwidth
is recalculated to be the value of XtNcharsVisible multiplied by the
width of the 'n' (en) character in the font plus the values for the
internal left and right margins. The value of this resource changes to
reflect the effects of geometry changes imposed by the widget tree and
the user. SetValues for this resource is ignored.
10/89 Page 5
TextField(3W) UNIX System V TextField(3W)
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.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
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, Section 2.
XtNinitialDelay
This resource is used to specify the time in milliseconds of the initial
repeat delay to be used when the scrolling arrows are pressed.
XtNinsertTab
If this resource is set to FALSE, a TAB character is not insertable;
Setting this resource to FALSE makes traversal of controls easier if the
TAB key is bound as OL_NEXT_FIELD. If set to TRUE, a TAB character is
insertable.
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 process.
Page 6 10/89
TextField(3W) UNIX System V TextField(3W)
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.
XtNrepeatRate
This resource is used to specify the time in milliseconds of the repeat
delay to be used when the scrolling arrows are pressed.
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.
XtNtextEditWidget
This resource is used to retrieve the TextEdit widget associated with the
TextField. This value can be used to directly access the underlying
TextEdit widget (and its TextBuffer) used to manage the textual display.
XtNtraversalOn
Range of Values:
TRUE
FALSE
This resource specifies whether this widget is selectable during
traversal.
XtNverification
This is the callback list used when the end-user hits the RETURN,
PREV_FIELD, or NEXT_FIELD. The calldata parameter is a pointer to an
OlTextFieldVerify structure:
typedef enum {
OlTextFieldReturn,
OlTextFieldPrevious,
OlTextFieldNext
} OlTextVerifyReason;
typedef struct {
OlTextVerifyReason reason;
String string;
Boolean ok;
OlTextVerifyReason reason;
} OlTextFieldVerify, *OlTextFieldVerifyPointer;
10/89 Page 7
TextField(3W) UNIX System V TextField(3W)
This callback list can be used to perform per-field validation. Note:
the callback is called only when a key is used to traverse from the
field; it is not called when the user mouses the focus to another input
area, therefore applications will still need to perform per-form
validation.
The following interactions between resources of the textfield and
textedit widgets should be noted.
At creation time, the following resources are passed from the textfield
to the textedit widget:
TextField Initialize Resources Passed from Textfield Widget to Textedit
Widget
_________________________________________________________________________
| Name | Value |
|_____________________|__________________________________________________|
|_____________________|__________________________________________________|
| XtNbackground | (textfield XtNbackground) |
|_____________________|__________________________________________________|
| XtNbottomMargin | 3 |
|_____________________|__________________________________________________|
| XtNcharsVisible | (depends on size of textfield) |
|_____________________|__________________________________________________|
| XtNfont | (textfield font) |
|_____________________|__________________________________________________|
| XtNinsertTab | (textfield XtNinsertTab) |
|_____________________|__________________________________________________|
| XtNleftMargin | 1 |
|_____________________|__________________________________________________|
| XtNlinesVisible | 1 |
|_____________________|__________________________________________________|
| XtNregisterFocusFunc| (textfield private routine EditsRegisterFocus())|
|_____________________|__________________________________________________|
| XtNrightMargin | 1 |
|_____________________|__________________________________________________|
| XtNtopMargin | 1 |
|_____________________|__________________________________________________|
| XtNwidth | (width of textfield) |
|_____________________|__________________________________________________|
| XtNwrapMode | OLWRAPOFF |
|_____________________|__________________________________________________|
At SetValues time, XtNstring is passed to the Text~dit widget as
XtNsource and the following resources are set:
Page 8 10/89
TextField(3W) UNIX System V TextField(3W)
TextField SetValues Resources Passed from Textfield Widget to Textedit
Widget
_________________________________________________________________________
| Name | Value |
|_______________________________|________________________________________|
|_______________________________|________________________________________|
| XtNbackground | (textfield XtNbackground) |
|_______________________________|________________________________________|
| XtNcursorPosition | 0 |
|_______________________________|________________________________________|
| XtNinsertTab | (textfield XtNinsertTab) |
|_______________________________|________________________________________|
| XtNselectStart | 0 |
|_______________________________|________________________________________|
| XtNselectEnd | 0 |
|_______________________________|________________________________________|
| XtNsourceType | OLSTRINGSOURCE |
|_______________________________|________________________________________|
10/89 Page 9