'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olTextField @(#)olTextField	40.3 of 1/8/90
.ig
Revised:  gjh 2/15/89
Revised:  gjh 2/8/89
Revised:  Joy Asay 2/14/89
Revised:  lmh 10/16,17,18/89
format -dshemp -rs1 -man6 gloTextF
THIS IS THE SECOND VERSION
..
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ds cW TEXTFIELD
.ds rW TextField
.ds nW TextField
.ds wW textField
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""TEXTFIELD WIDGET" 3W "\&"
.if \nX=1 .ds x} ""TEXTFIELD WIDGET" 3W
.if \nX=2 .ds x} ""TEXTFIELD WIDGET" "" "\&"
.if \nX=3 .ds x} ""TEXTFIELD "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f(CW#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.P
.nf
\s-1\f(CWwidget = XtCreateWidget(\fIname\fP, \*(wWWidgetClass, ...);\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3\*(rW Components\f1
.P
The \*(bW widget is a one-line input field for text data that
contains the following elements:
.IP \(em 1.5P
Input Caret
.IP \(em 1.5P
Input Field
.IP \(em 1.5P
Left Arrow (conditional)
.IP \(em 1.5P
Right Arrow (conditional)
.br
.ne3.5i
.BP PSART/ps.txtfield1
.P
.ce
\f3Figure 1.\f1  One-Line Text Field
.sp
.bp
\f3Keyboard Input\f1
.P
Once the input focus has been moved to the Input Field,
keyboard entry is allowed.
The \*(bW widget does not validate the input,
leaving that up to the application.
.sp
\f3Keyboard Traversal\f1
.P
Users can traverse among \f3Text\f1 and \f3TextField\f1
widgets within any ancestor \f3ControlArea, BulletinBoard\f1, or
\f3Form\f1 widget using the NEXTFIELD and PREVFIELD keys:  
.IP "\(em" 5
NEXTFIELD
moves the caret to the next traversable \f3Text\f1 or \f3TextField\f1
widget in the managing ancestor widget.
When the caret is in the last traversable
field, NEXTFIELD moves the caret to the first traversable field.
.IP "\(em" 
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.
.P
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.
.sp
\f3Editing Capabilities\f1
.P
The \*(bW provides the editing capabilities listed in the
following table.
(This is a subset of the editing capabilities of the
\f3Text\f1 widget;
this does not imply that the \*(bW widget is necessarily
implemented as a subclass of the \f3Text\f1 widget.)
.TS
box;
lbp-1w(1.2i)1|lbp-1w(2.8i)1
lp-1w(1.2i)1|lp-1w(2.8i)1.
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
.TE
.sp
This second table displays the virtual expressions and keyboard 
equivalents for the editing functions.  See \fBVIRTUAL KEY/BUTTON(3W)\fP 
earlier in this guide for more information on virtual expressions.
.TS
box;
lbp-1|lbp-1|lbp-1
lp-1|lp-1|lp-1.
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-\(ua, ALT- <
DOCEND	docEndKey	ALT-\(da, 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
.TE
.P
\f3Scrolling Long Text Input\f1
.P
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.
.P
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.
.P
The text does not scroll beyond its limits,
so that the left-most character never moves beyond the right
edge of the \*(bW 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.
.XX AUTOSCROLL .P
.XX AUTOSCROLL If the user begins typing again after scrolling the text,
.XX AUTOSCROLL the text automatically scrolls back to where it was before the
.XX AUTOSCROLL user scrolled it.
.sp
\f3Input Validation\f1
.P
When the input focus changes from the \*(bW 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.
.bp
\f3Position of the Input Caret\f1
.P
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.
.P
.XX AUTOSCROLL If the end user scrolls the text,
.XX AUTOSCROLL the Input Caret scrolls with it,
.XX AUTOSCROLL to remain fixed next to the same character(s).
.sp
\f3Selecting and Operating on the Input Field\f1
.P
The \fBTextField\fP widget allows text to be copied or moved to and from 
the Input Field.  See \fBTEXT SELECTION(3W)\fP earlier in 
this manual for the description of these operations.
.P
.XX DRAG .so SOURCEFILES/Widgets/common/RWSelect/DraggingOut
.XX DRAG .so SOURCEFILES/Widgets/common/RWSelect/MovingOut
.XX DRAG .so SOURCEFILES/Widgets/common/RWSelect/DraggingIn
.XX QUICK .so SOURCEFILES/Widgets/common/RWSelect/QuickPasteOut
.XX QUICK .so SOURCEFILES/Widgets/common/RWSelect/QuickPasteIn
.sp
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.txtfield2
.P
.ce
\f3Figure 2.\f1  Text Field Coloration
.bp
.SH "RESOURCES"
.ds cO
.TS 
allbox;
cB s s s s.
\*(bW Resource Set\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
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\(dg
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
.TE
\f3XtNfont\f1
.PP
Range of Values:
.br
.in +5
(any valid return from \f(CWXLoadQueryFont()\f1)
.in 0
.P
Default:
.P
.in +5
\f1(chosen to match the scale and screen resolution)
.in -5
.PP
This resource identifies the font to be used to display the
Input Field.
.P
The default value points to a cached font structure;
an application should not expect to get this value with a call to
\f(CWXtGetValues()\f1
and use it reliably thereafter.
.sp
\f3XtNfontColor\f1
.PP
Range of Values:
.br
.in +5
(any \f(CWPixel \f1value valid for the current display)/(any name from the \f(CWrgb.txt \f1file)
.in -5
.PP
This resource specifies the color for the font.
If not set,
the color from the
\f(CWXtNforeground\f1
resource,
if available,
is used for the font.
.sp .25
See the note about the interaction of this resource with other
color resources under the description of the
\f(CWXtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.bp
\f3XtNforeground\f1
.P
This resource defines the foreground color for the widget.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f(CWXtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.ig
.sp 0.75
\f3XtNinitialDelay\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 < XtNinitialDelay\f1
.in -5
.fi
.PP
This resource gives the time,
in milliseconds,
before the first action occurs when SELECT is pressed on an
Arrow.
Note that millisecond timing precision may not be possible
for all implementations,
so the value may be rounded up to the nearest available unit by
the toolkit.
..
.sp 0.75
\f3XtNmaximumSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNmaximumSize\f1
.in -5
.fi
.PP
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.
.sp 0.75
\f3XtNreferenceWidget\f1
.PP
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.
.ig
.sp 0.75
\f3XtNrepeatRate\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 < XtNrepeatRate\f1
.in -5
.fi
.PP
This resource gives the time,
in milliseconds,
between repeated actions when SELECT is pressed on an Arrow.
Note that millisecond timing precision may not be possible
for all implementations,
so the value may be rounded up to the nearest available unit by
the toolkit.
..
.sp 0.75
\f3XtNstring\f1
.P
This is the content of the Input Field.
On being set a copy of the value is made in an internal buffer.
Using
\f(CWXtGetValues()\f1
on this resource gets a new copy that the application is
responsible for freeing when no longer needed.
.sp 0.75
\f3XtNtraversalOn\f1
.P
Range of Values:
.br
.nf
.in +5
\f(CWTRUE
FALSE\fP
.in -5
.fi
.P
This resource specifies whether this widget is selectable during
traversal.
.sp 0.75
\f3XtNverification\f1
.P
This callback list is issued when the user presses the RETURN
or TAB key or moves the input focus out of the \*(bW widget.
The
\f(CWcall_data\f1
parameter is a pointer to a structure,
\f(CWOlTextFieldVerify\f1,
that looks like this:
.P
.in +4P
.nf
\f(CWtypedef struct _OlTextFieldVerify {
        String string;
        Boolean ok;
} OlTextFieldVerify;\f1
.in -4P
.fi
.IP \f(CWstring\f1 8
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.
.IP \f(CWok\f1 8
is currently unused.
.sp 0.75
.XX TRAVERSAL .SH "TRAVERSAL"
.XX TRAVERSAL \f3Receiving Input Focus\f1
.XX TRAVERSAL .P
.XX TRAVERSAL The \*(bW widget receives input focus through a mnemonic,
.XX TRAVERSAL through a transferal from its parent,
.XX TRAVERSAL or when SELECT is pressed over it.
.XX TRAVERSAL .P
.XX TRAVERSAL \f3Keyboard Actions\f1
.XX TRAVERSAL .P
.XX TRAVERSAL The \*(bW widget responds to these keys with the action listed:
.XX TRAVERSAL .IP "Alphanumeric Keys" 8
.XX TRAVERSAL The \*(bW inserts the corresponding character or space and
.XX TRAVERSAL moves the input cursor.
.XX TRAVERSAL .IP TAB 8
.XX TRAVERSAL The \*(bW widget informs its parent widget to move the input
.XX TRAVERSAL focus to the next category.
.XX TRAVERSAL .IP SHIFT/TAB 8
.XX TRAVERSAL The \*(bW widget informs its parent widget to move the input
.XX TRAVERSAL focus to the previous category.
.XX TRAVERSAL .IP UP 8
.XX TRAVERSAL .sp -.5
.XX TRAVERSAL .IP DOWN 8
.XX TRAVERSAL The \*(bW widget moves the pointer one line in the direction
.XX TRAVERSAL implied by the key.
.XX TRAVERSAL .IP LEFT 8
.XX TRAVERSAL .sp -.5
.XX TRAVERSAL .IP RIGHT 8
.XX TRAVERSAL The \*(bW widget moves the pointer one character in the
.XX TRAVERSAL direction implied by the key.
.XX TRAVERSAL If the pointer would move past the end of the visible
.XX TRAVERSAL characters in the Input Field,
.XX TRAVERSAL it moves to the Left or Right Arrow,
.XX TRAVERSAL if present.
.XX TRAVERSAL .IP SHIFT/UP 8
.XX TRAVERSAL The \*(bW widget moves the pointer to the top of the View,
.XX TRAVERSAL keeping the same relative horizontally position.
.XX TRAVERSAL .IP SHIFT/DOWN 8
.XX TRAVERSAL The \*(bW widget moves the pointer to the bottom of the View,
.XX TRAVERSAL keeping the same relative horizontally position.
.XX TRAVERSAL .IP SHIFT/LEFT8
.XX TRAVERSAL .sp -.5
.XX TRAVERSAL .IP SHIFT/RIGHT 8
.XX TRAVERSAL The \*(bW widget moves the pointer one word in the direction
.XX TRAVERSAL implied by the key.
.XX TRAVERSAL .IP CTRL/UP 8
.XX TRAVERSAL The \*(bW widget moves the pointer to the beginning of the
.XX TRAVERSAL Content.
.XX TRAVERSAL .IP CTRL/DOWN 8
.XX TRAVERSAL The \*(bW widget moves the pointer to the end of the Content.
.XX TRAVERSAL .IP CTRL/LEFT 8
.XX TRAVERSAL .sp -.5
.XX TRAVERSAL .IP CTRL/RIGHT 8
.XX TRAVERSAL The \*(bW widget moves the pointer to the beginning or end of
.XX TRAVERSAL the Input Field,
.XX TRAVERSAL according to the direction implied by the key.
.XX TRAVERSAL .IP CONTROLAREA 8
.XX TRAVERSAL The \*(bW widget informs its parent widget to shift
.XX TRAVERSAL the input focus to the control area/window border.
.bp
.SH "WARNINGS"
The \f4XtNverification\f1 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.
.P
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.
