TextField(3w) — OLIT Widget Set

NAME

TextField − one line text field widget

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/TextField.h>
. . .
Widget my_textfield, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_textfield = XtCreate( my_name, textFieldWidgetClass,

my_parent, args, num_args);

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

TextField            Resource       Set
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
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 timeO = 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:XtCfonttype:XFontStruct∗default:(OPEN LOOK font)(OPEN LOOK font)’u’access:SISI’u’

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:XtCFontColortype:Pixeldefault:BlackBlack’u’access:SGISGI’u’

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:XtCForegroundtype:Pixeldefault:BlackBlack’u’access:SGISGI’u’

Action: defines the foreground color for the widget.

XtNinitialDelay

class:XtCInitialDelaytype:intdefault:500500’u’access:SGISGI’u’

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

XtNinsertTab

class:XtCInsertTabtype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’

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:XtCLengthtype:intdefault:(none)(none)’u’access:SGISGI’u’

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:XtCReferenceWidgettype:Widgetdefault:(Widget)NULL(Widget)NULL’u’access:GIGI’u’

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:XtCRepeatRatetype:intdefault:100100’u’access:SGISGI’u’

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

XtNscale

class:XtCScaletype:Intdefault:1212’u’access:SGISGI’u’

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:XtCStringtype:Stringdefault:NULLNULL’u’access:SGISGI’u’

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:XtCTextEditWidgettype:Widgetdefault:NULLNULL’u’access:GG’u’

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:XtCTraversalOntype:Booleandefault:TRUETRUE’u’access:SGISGI’u’

Action: specifies whether this widget is selectable during traversal.

Values: TRUE, FALSE

XtNverification

class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’

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
XtNfont              (textfield font)
XtNinsertTab         (textfield XtNinsertTab)
XtNleftMargin        1
XtNlinesVisible      1
XtNregisterFocusFunc (textfield private        routine
XtNrightMargin       1
XtNtopMargin         1
XtNwidth             (width      of             textfield)
XtNwrapMode          OL_WRAP_OFF

At SetValues time, XtNstring is passed to the TextEdit 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

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