WIDGET CLASS NAME

TextField

SYNOPSIS

#include <Intrinsic.h>
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <TextField.h>

widget = XtCreateWidget(name, textFieldWidgetClass, ...);
widget = XtCreateWidget(name, textFieldWidgetClass, ...);

DESCRIPTION

TextField Components

A simple, one line, text field widget is shown in the diagram One Line Text Field. 

  Figure 1 One Line Text Field

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) 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 TextField widgets within any ancestor ControlArea, BulletinBoard, 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 necessarily implemented as a subclass of the Text widget.) 

  Table 1 TextField Editing Capabilities 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. 

  Table 2 TextField Virtual Expressions and Keyboard Equivalents
      Name  Keyboard Equivalents
   CHARFWD  CTRL-F, →
   CHARBAK  CTRL-B, ←
   WORDFWD  META-F, META- →
   WORDBAK  META-B, META- ←
 LINESTART  CTRL-A, CTRL- ←
   LINEEND  CTRL-E, CTRL- →
  DOCSTART  META-↑, META- <
    DOCEND  META-↓, META- > DELCHARFWD  CTRL-D, DELETE DELCHARBAK  CTRL-H, BACKSPACE
 DELWRDFWD      META-D DELWORDBAK      META-H DELLINEFWD      CTRL-K DELLINEBAK      META-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 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

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 changing the input focus.  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. 

TextField Coloration

The diagram TextField Coloration illustrates the resources that affect the coloration of the TextField widget. 

  Figure 2 TextField Coloration

RESOURCES

  Table 3 TextField Resource Set TextField Resource Set
                Name            Type       Default    Access XtNancestorSensitive         Boolean          TRUE        G∗
       XtNbackground           Pixel         White   SGI†
 XtNbackgroundPixmap          Pixmap        (none)   SGI†
            XtNdepth             int    (parent’s)        GI
  XtNdestroyCallback  XtCallbackList          NULL        SI
             XtNfont   XFontStruct ∗  (OPEN LOOK font)        SI
        XtNfontColor           Pixel        Black∗       SGI
       XtNforeground           Pixel         Black   SGI†
           XtNheight       Dimension  (calculated)       SGI XtNmappedWhenManaged         Boolean          TRUE       SGI
      XtNmaximumSize             int        (none)       SGI
  XtNreferenceWidget          Widget     (Widget)0        GI
        XtNsensitive         Boolean          TRUE       GI∗
           XtNstring          String          NULL       SGI
      XtNtraversalOn         Boolean          TRUE       SGI
         XtNuserData       XtPointer          NULL       SGI
     XtNverification  XtCallbackList          NULL        SI
            XtNwidth       Dimension  (calculated)       SGI
                XtNx        Position             0       SGI
                XtNy        Position             0       SGI XtNfont

Range of Values:

(any valid return from XLoadQueryFont()) (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() 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) (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 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 XtNbackground resource in CORE RESOURCES(3W).  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 XtNbackground resource in CORE RESOURCES(3W).  XtNmaximumSize

Range of Values:

0 ≤ XtNmaximumSize
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.  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() XtGetValues() on this resource gets a new copy that the application is responsible for freeing when no longer needed.  XtNtraversalOn

Range of Values:

TRUE
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 call_data parameter is a pointer to a structure, OlTextFieldVerify, OlTextFieldVerify, that looks like this:

typedef struct _OlTextFieldVerify {
typedef struct _OlTextFieldVerify {
        String string;
        Boolean ok;
} OlTextFieldVerify;

string

stringgives 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

okis currently unused. 

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. 

Sun Release 4.1  —  Last change: 1/8/90