TextField(3W)

NAME

TextField − one line text field widget

SYNOPSIS

#include <Xol/OpenLook.h>
#include <Xol/TextField.h>
. . .

ANCESTRY

Core-Composite-Constraint-Manager-TextField

DESCRIPTION

Components

A TextField widget is a one-line input field for text data that is shown in

Figure 1 One Line Text Field

The TextField contains the following graphical elements:

• input caret

• input field

• left arrow (conditional)

• right arrow (conditional)

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

—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:

—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.

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.

Caret Position

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 textselection(3W) for the description of these operations.

Coloration

of the TextField widget.

Figure 2 TextField Coloration

RESOURCES

Table 1 TextField Resource Summary

Name                    Type             Default             Access
XtNancestorSensitive-   Boolean          TRUE                   GO
XtNbackground-          Pixel            XtDefaultBackground    SGI
XtNbackgroundPixmap-    Pixmap           (none)                 SGI
XtNcharsVisible         int              0                      GI
XtNconsumeEvent-        XtCallbackList   NULL                   SG
XtNdepth-               int              (parent’s)             GI
XtNdestroyCallback-     XtCallbackList   NULL                   SI
XtNfont                 XFontStruct∗     (OPEN LOOK font)       SI
XtNfontColor            Pixel            XtDefaultForeground∗   SGI
XtNforeground-          Pixel            XtDefaultForeground    SGI
XtNheight-              Dimension        (calculated)           SGI
XtNinputFocusColor-     Pixel            Red                    SGI
XtNinitialDelay         int              500                    SGI
XtNinsertTab            Boolean          FALSE                  SGI
XtNmappedWhenManaged-   Boolean          TRUE                   SGI
XtNmaximumSize          int              0                      SGI
XtNreferenceName-       String           NULL                   GI
XtNreferenceWidget-     Widget           NULL                   GI
XtNrepeatRate           int              100                    SGI
XtNscale                int              12                     SGI
XtNsensitive-           Boolean          TRUE                   GIO
XtNstring               String           NULL                   SGI
XtNtextEditWidget       Widget           NULL                   G
XtNtraversalOn-         Boolean          TRUE                   SGI
XtNuserData-            XtPointer        NULL                   SGI
XtNverification         XtCallbackList   NULL                   SGI
XtNwidth-               Dimension        (calculated)           SGI
XtNx-                   Position         0                      SGI
XtNy-                   Position         0                      SGI

Access: S = XtSetValues G = XtGetValues
I = init time O = other access
† see resources(3W)

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.

XtNfont

class:XtCfont type:XFontStruct∗ default:(OPEN LOOK font)access:SI

Action: specifies the font to be used to display the Input Field.

Values: any valid return from XLoadQueryFont().

The default value is chosen to match the scale and screen resolution. 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

class:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI Action: specifies the font color.

Values: any pixel value valid for the current display, or
any name from the rgb.txt file

If not set, the color from the XtNforeground resource, if available, is used for the font.

XtNforeground

class:XtCForeground type:Pixel default:XtDefaultForegroundaccess:SGI

Action: defines the foreground color for the widget.

XtNinitialDelay

class:XtCInitialDelay type:int default:500access:SGI

Action: specifies the time in milliseconds of the initial repeat delay to be used when the scrolling arrows are pressed.

XtNinsertTab

class:XtCInsertTab type:Boolean default:FALSEaccess:SGI

Action: specifies whether or not a TAB character is insertable.

Values: TRUE – a TAB character is insertable. 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 .

XtNmaximumSize

class:XtCLength type:int default:(none)access:SGI

Action: specifies the maximum number of characters that can be entered into the internal buffer.

Values: 0 ≤ XtNmaximumSize

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.

XtNreferenceWidget

class:XtCReferenceWidget type:Widget default:(Widget)NULLaccess:GI

Action: 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

class:XtCRepeatRate type:int default:100access:SGI

Action: specifies the time in milliseconds of the repeat delay to be used when the scrolling arrows are pressed.

XtNscale

class:XtCScale type:Int default:12access:SGI

Action: determines size of graphical elements, in points (1/72 inch), not pixels

Values: 0 < XtNscale

This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources. Only sizes 10, 12, 14, and 19 are presently supported. If this resource is set to any other value, one of these is substituted instead.

XtNstring

class:XtCString type:String default:NULLaccess:SGI

Action: specifies 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

class:XtCTextEditWidget type:Widget default:NULLaccess:G

Action: retrieves 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

class:XtCTraversalOn type:Boolean default:TRUEaccess:SGI

Action: specifies whether this widget is selectable during traversal.

Values: TRUE, FALSE

XtNverification

class:XtCCallback type:XtCallbackList default:NULLaccess:SI

Action: 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:

typedef struct _OlTextFieldVerify {
        String             string;
        Boolean            ok;
        OlTextVerifyReason reason;
} 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.

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           OL_WRAP_OFF

At SetValues time, XtNstring is passed to the Text~dit widget as XtNsource and the following resources are set:

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       OL_STRING_SOURCE
XtNsource           (current string)

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.

Museum

Related Articles