'\"!  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 | mmdoc
'\"macro stdmacro
.if n .pH g3w.olText @(#)olText	40.3 of 1/8/90
.tr ~
.ig
Revised:  gjh 2/15/89
Revised:  gjh 2/6/89
Revised:  Joy Asay 2/14/89
Revised:  lmh 10/16,17,18/89
Revised:  lmh 10/20/89
format -dshemp -rs1 -man6 Text
THIS IS THE SECOND VERSION
..
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ds cW TEXT
.ds rW Text
.ds nW Text
.ds wW text
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""TEXT WIDGET" 3W "\&"
.if \nX=1 .ds x} ""TEXT WIDGET" 3W
.if \nX=2 .ds x} ""TEXT WIDGET" "" "\&"
.if \nX=3 .ds x} ""TEXT "" "" "\&"
.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(\f2name\f(CW, \*(wWWidgetClass, ...);\f1\s+1
.fi
.SH "DESCRIPTION"
The \*(bW widget provides a single and multi-line text editor that has
both a customizable user interface and a programmatic interface.
It can be used for single-line string entry,
forms entry with verification procedures,
multiple-page document viewing,
and full-window editing.
It provides an application with a consistent editing paradigm
for entry of textual data.
.P
The display of the textual data on the screen can be adjusted
to scroll, wrap, or grow automatically as the user reaches the
edge of the view of the text.
.P
The \*(bW widget provides separate callback lists to verify
insertion cursor movement,
modification of the text,
and leaving the \*(bW widget.
Each of these callbacks provides the verification function with
the widget instance,
the event that caused the callback,
and a data structure specific to the verification type.
From this information, the function can verify if the
application considers this to be a legitimate state change and
signal the widget whether to continue with the action.
The verification function can also manipulate the widget
through the class methods defined by the \*(bW widget class.
The verification callback lists are explained in detail below.
.bp
\f3Editing Capabilities\f1
.P
The \*(bW widget provides the editing capabilities listed in the
following table.
.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
ROWDOWN	Move the caret down one line in the current column
ROWUP	Move the caret up one line in the current column
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, \(<-
ROWDOWN	rowDownKey	CTRL-N, \(da
ROWUP	rowUpKey	CTRL-P, \(ua
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
.bp
\f3Hierarchical Text\f1
.P
Text is considered to be hierarchically composed of white
space, words, lines and paragraphs.
White space is defined as any non-empty sequence of the ASCII
characters space, tab, linefeed or carriage return (decimal
values of 32, 9, 10, 13, respectively);
a word is any non-empty sequence of characters bounded on both
sides by
\f2whitespace\f1.
A source line is any (possibly empty) sequence of characters
bounded by newline characters;
a display line is any (possibly empty) sequence of characters
appearing on a single screen display line.
A source paragraph is any sequence of characters bounded by
sets of two or more adjacent newline characters.
A display paragraph is any (possibly empty) sequence of
characters bounded by newline characters
(\f3Note:\f1  This is identical to the definition of a source line.)
.P
In all cases,
the beginning or end of the edit text is an acceptable bounding
element in the previous definitions.
.sp
\f3Sizing the Display\f1
.P
When making display decisions,
the \*(bW widget first determines whether all the text will fit
in the current display.
If it does not,
and growing is enabled,
the widget will request a resize from its parent.
If the request is denied or only partially satisfied,
no future growth requests will be made unless there is an
intervening resize operation externally imposed.
.sp
If any source line is still too long to fit in the display
after growing is attempted,
wrapping is checked.
If wrapping is disabled,
one display line is drawn for each source line.
If a source line is too long for the display,
it is truncated at the right margin after the last full
character that fits.
If wrapping is enabled,
a new display line will be started with the first word that
does not fit on the current line.
If the wrap break option is
\f(CWOL_WRAP_ANY\f1,
as many characters from that word as will fit before the right
margin are written to the current display line,
then the next character starts at the left margin of the next
display line.
If the wrap break option is
\f(CWOL_WRAP_WHITE_SPACE\f1,
the line break is instead made after the first whitespace
character that follows the last full word that does fit on
the current display line.
If, 
however,
under white space break,
the first full word that does not fit is also the first word
on the line,
the wrap break is made as if
\f(CWOL_WRAP_ANY\f1
were selected.
.sp
\f3Scrolled Window\f1
.P
The application can decide if the \*(bW widget can have
a scrollbar at the side. 
With a scrollbar,
the end user can move through the text easily.
Without a scrollbar,
the \*(bW widget either grows its window,
if possible,
to show the complete content,
or wraps a long line onto another line.
.P
The proportion indicators on the scrollbar show how much of
the text the user can see at once,
compared with the entire text buffer or file.
.P
As the user enters text,
the view will automatically scroll left to keep the insert
point in view,
unless the \*(bW widget is operating in a wrap or grow mode.
.bp
\f3Application Callbacks\f1
.P
Three types of verification callbacks are supported by the
\*(bW widget:
.IP \(em 1.5P
one for motion operations, to verify a new insert position;
.IP \(em 1.5P
one for modifying operations, to verify insertion,
deletion or replacement of text; and
.IP \(em 1.5P
one for widget exit, to verify state consistency on
loss of focus by the widget.
The
\f(CWcall_data\f1
value is a pointer to an
\f(CWOlTextVerifyCD\f1
structure.
The C data types used here are:
.P
.nf
.in +6
\f(CWtypedef enum {
        motionVerify,
        modVerify,
        leaveVerify
} OlVerifyOpType;
.sp
\f(CWtypedef struct {
        int              firstPos;
        int              length;
        unsigned char    *ptr;
} OlTextBlock, *OlTextBlockPtr;
.sp
\f(CWtypedef struct {
        XEvent           *xevent;
        OlVerifyOpType   operation;
        Boolean          doit;
        OlTextPosition   currInsert, newInsert;
        OlTextPosition   startPos, endPos;
        OlTextBlock      *text;
} OlTextVerifyCD, *OlTextVerifyPtr;\f1
.fi
.in -6
.sp
The elements of an \f(CWOlTextBlock\f1 structure are as
follows:
.IP \f(CWfirstPos\f1 8
the offset of the starting character in the text block.
.IP \f(CWlength\f1 8
the size of the text block.
.IP \f(CWptr\f1 8
a pointer to the text block.
.PP
.PP
.PP
Before the verification callbacks are issued for any
given operation,
a structure of type
\f(CWOlTextVerifyCD\f1
is initialized.
The initial values are:
.IP \f(CWxevent\f1 8
for a leave operation, the current event pointer.
.IP \f(CWoperation\f1 8
element of
\f(CWOlVerifyOpType\f1
signifying the type of verification operation.
.IP \f(CWdoit\f1 8
\f(CWTRUE\f1.
.bp
.IP \f(CWcurrInsert\f1 8
current position of the insert point.
.IP \f(CWnewInsert\f1 8
for a motion operation,
the position the user is attempting to move the insert point
to;
otherwise,
the same value as
\f(CWcurrInsert\f1.
.IP \f(CWstartPos\f1 8
for a modify operation,
the beginning position in the current source of the text about
to be deleted or replaced,
or where new text will be inserted.
If not a modify operation,
it will have the same value as
\f(CWcurrInsert\f1
.IP \f(CWendPos\f1 8
for a modify operation,
the ending position in the current source of the text about to
be deleted or replaced.
If no text is being removed,
it will have the same value as
\f(CWstartPos\f1.
If not a modify operation,
the same value as currInsert.
.IP \f(CWtext\f1 8
for a modify operation with new text to be inserted,
a pointer to a structure of type
\f(CWOlTextBlock\f1,
that references the text to be inserted.
Otherwise, NULL.
.P
It is possible for the client to register more than one
callback procedure for any of these callback types.
Since there can be more than one callback,
each verification procedure should first check the
\f(CWdoit\f1
field.
.P
On return from the last callback,
the \*(bW widget will look at the
\f(CWdoit\f1
member of the
\f(CWOlTextVerifyCD\f1
structure.
If it is false,
a callback has already rejected the operation,
so there is no need for further evaluation.
If it is still true,
the \*(bW widget will proceed with the operation;
otherwise, it will not.
Any user feedback for the rejected operation is the
responsibility of the verification procedure.
.P
Verification callbacks are permitted to modify some of the
data in the
\f(CWOlTextVerifyCD\f1
structure.
The \*(bW widget will only look at certain fields on return,
though,
according to the operation type:
.IP \(em 1.5P
For a motion operation,
only the
\f(CWnewInsert\f1
position will be looked at.
.IP \(em 1.5P
For a modify operation,
only
\f(CWstartPos\f1,
\f(CWendPos\f1,
and
\f(CWtext\f1
will be examined for changes.
.IP \(em 1.5P
For a leave operation,
no fields will be examined.
.P
There is no mechanism for preventing a verification callback
from making other changes to the editing state through the
documented interface,
but the results of such behind-the-back actions are undefined.
.sp
\f3Application Access to Text\f1
.P
The \*(bW has several resources that identify entry points that
the application can use to access the internal buffer that the
\*(bW widget manages.
For example,
if the widget is being used to enter a string,
the program can get a copy of the string
(i.e. the internal buffer)
with the function under the resources
\f(CWXtNtextCopyBuffer\f1
or
\f(CWXtNtextReadSubString\f1.
.bp
.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
\f3Selecting and Copying the Text\f1
.P
Text can be moved or copied to and from 
the \f3Text\f1 widget.  See \fBTEXT SELECTION(3W)\fP earlier 
in this manual for the description of these operations.
.sp
.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
\f3\*(rW Coloration\f1
.P
Figure 1 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.text1
.ce
\f3Figure 1.\f1  Text Coloration
.sp
.SH "SUBSTRUCTURE"
.P
\f3Vertical Scrollbar component\f1
.P
.nf
Names: verticalscrollbar
Class: Scrollbar
.fi
.P
See the regular resource list for alternate names used for some
key
\f3Scrollbar\f1
resources.
.sp
.SH "RESOURCES"
.TS
allbox;
cB s s s s.
\*(bW Resource Set
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.T&
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
XtNancestorSensitive	XtCSensitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderColor	XtCBorderColor	Pixel	Black	SGI\(dg
XtNborderPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderWidth	XtCBorderWidth	Dimension	0	SGI
XtNbottomMargin	XtCMargin	Dimension	0	SGI
XtNcursorPosition	XtCTextPosition	OlTextPosition	0	SGI
XtNcurrentPage	XtCCurrentPage	int	1	SGI
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNdisplayPosition	XtCTextPosition	OlTextPosition	0	SGI
XtNeditType	XtCEditType	OlDefine	OL_TEXT_EDIT	SGI
XtNfile	XtCFile	String	NULL	SGI
XtNfont	XtCFont	XFontStruct *	(OPEN LOOK font)	SI
XtNfontColor	XtCFontColor	Pixel	Black*	SGI
XtNforeground	XtCForeground	Pixel	Black	SGI\(dg
XtNgrow	XtCGrow	OlDefine	OL_GROW_OFF	SGI
XtNhorizontalSB	XtCHorizontalSB	Boolean	FALSE	SGI
XtNleaveVerification	XtCCallback	XtCallbackList	NULL	SI
XtNleftMargin	XtCMargin	Dimension	0	SGI
XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	SGI
XtNmaximumSize	XtCLength	int	(none)	SGI
XtNmodifyVerification	XtCCallback	XtCallbackList	NULL	SI
XtNmotionVerification	XtCCallback	XtCallbackList	NULL	SI
XtNrecomputeSize	XtCRecomputeSize	Boolean	TRUE	SGI
XtNreferenceWidget	XtCReferenceWidget	Widget	(Widget)0	GI
XtNrightMargin	XtCMargin	Dimension	0	SGI
.TE
.bp
.TS
allbox;
cB s s s s.
\*(bW Resource Set (cont.)
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.T&
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
XtNsensitive	XtCSensitive	Boolean	TRUE	SGI
XtNshowPage	XtCShowPage	OlDefine	OL_NONE	SGI
XtNsourceType	XtCSourceType	OlDefine	OL_STRING_SRC	SGI
XtNstring	XtCString	String	NULL	SGI
XtNtextClearBuffer	XtCTextClearBuffer	void(*)()	(n/a)	G
XtNtextCopyBuffer	XtCTextCopyBuffer	unsigned char(*)()	(n/a)	G
XtNtextGetInsertPoint	XtCTextGetInsertPoint	OlTextPosition(*)()	(n/a)	G
XtNtextGetLastPos	XtCTextGetLastPos	OlTextPosition(*)()	(n/a)	G
XtNtextInsert	XtCTextInsert	void(*)()	(n/a)	G
XtNtextReadSubStr	XtCTextReadSubStr	int(*)()	(n/a)	G
XtNtextRedraw	XtCTextRedraw	void(*)()	(n/a)	G
XtNtextReplace	XtCTextReplace	OlEditResult(*)()	(n/a)	G
XtNtextSetInsertPoint	XtCTextSetInsertPoint	void(*)()	(n/a)	G
XtNtextUpdate	XtCTextUpdate	void(*)()	(n/a)	G
XtNtopMargin	XtCMargin	Dimension	0	SGI
XtNtraversalOn	XtCTraversalOn	Boolean	TRUE	SGI
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNverticalSB	XtCVerticalSB	Boolean	FALSE	SGI
XtNviewHeight	XtCViewHeight	Dimension	(calculated)	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNwrap	XtCWrap	Boolean	TRUE	SGI
XtNwrapBreak	XtCWrapBreak	OlDefine	OL_WRAP_WHITE_SPACE	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
.in
.P
.XX SCROLLMENU XtNhMenuPane	XtCHMenuPane	Widget	(none)	G
.XX SCROLLMENU XtNvMenuPane	XtCVMenuPane	Widget	(none)	G
.XX SOURCE XtNtextSetSource	XtCTextSetSource	void(*)()	(n/a)	G
.sp
\f3XtNbottomMargin\f1
.PP
Range of Values:
.br
.in +5
.nf
.vA
\f(CW0 \(<= XtNbottomMargin\f1
.in -5
.fi
.P
This resource is the number of pixels used for the bottom margin.
.sp
\f3XtNcursorPosition\f1
.PP
Range of Values:
.br
.in +5
\f(CW0 \(<= XtNcursorPosition < \f1(current size of the text)
.in -5
.PP
This resource is the position in the text source of the insert cursor.
.sp
\f3XtNdisplayPosition\f1
.PP
Range of Values:
.br
.in +5
.vA
\f(CW0 \(<= XtNdisplayPosition\f1
.in -5
.fi
.PP
This resource contains the position in the text source 
that will be displayed at the
top of the screen.
A value of 0 indicates the start of the text source.
.P
\f(HBNote:\fP  
.br
The specified position must correspond to the 
first character position
of a source line (i.e., it must be 0, or it must be a position
immediately following a newline character).  Otherwise, correct behavior
is not guaranteed.
.sp
\f3XtNeditType\f1
.PP
Range of Values:
.br
.nf
.in +5
\f(CWOL_TEXT_READ/"read"
.XX APPEND OL_TEXT_APPEND/"textappend"
\f(CWOL_TEXT_EDIT/"edit"\f1
.in -5
.fi
.PP
This resource controls the edit state of the source:
.IP "\f(CWOL_TEXT_READ\f1" 12
The source is read-only;
the end user cannot edit it.
.XX APPEND .IP "\f(CWOL_TEXT_APPEND\f1" 12
.XX APPEND The source is append-only;
.XX APPEND the end user can add text to the end.
.IP "\f(CWOL_TEXT_EDIT\f1" 12
The source is fully editable.
.P
\f3Note:\f1  
.br
This option is available for text buffers only;
text files cannot be edited.
.P
.sp
\f3XtNfile\f1
.P
This resource is used only if the
\f(CWXtNsourceType\f1
resource has the value
\f(CWOL_DISK_SOURCE\f1.
It is the absolute pathname of a disk file to be viewed.
.XX EDITABLE and/or edited to.
.XX EDITABLE If no file is given, and the
.XX EDITABLE \f(CWXtNeditType\f1
.XX EDITABLE resource is not
.XX EDITABLE \f(CWOL_TEXT_READ\f1,
.XX EDITABLE a temporary file will be created.
.sp
\f3XtNfont\f1
.PP
Range of Values:
.br
.in +5
(any valid return from \f(CWXLoadQueryFont()\f1)
.in 0
.P
Default:
.P
.in +5
(chosen to match the scale and screen resolution)
.in -5
.fi
.PP
This resource identifies the font to be used to display the
text.
.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.
.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(3W)\f1.
.sp
.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(3W)\f1.
.sp
\f3XtNgrow\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWOL_GROW_OFF/"off"
OL_GROW_HORIZONTAL/"horizontal"
OL_GROW_VERTICAL/"vertical"
OL_GROW_BOTH/"both"\f1
.in -5
.fi
.PP
This resource controls if the widget will try to resize its
window when it needs more height or width to display the text:
.IP "\f(CWOL_GROW_OFF\f1" 8
It will not resize itself.
.IP "\f(CWOL_GROW_HORIZONTAL\f1" 8
It will attempt to change its width when lines are too long for
the current screen width.
.IP "\f(CWOL_GROW_VERTICAL\f1" 8
it will attempt to resize its height when the number of
text lines is greater than can be displayed with the
current screen height.
.IP "\f(CWOL_GROW_BOTH\f1" 8
It will attempt resizes in both dimensions.
.P
.XX GROW/WRAP/SCROLL .sp .5
.XX GROW/WRAP/SCROLL Growth attempts have higher priority than either wrapping
.XX GROW/WRAP/SCROLL (\f(CWXtNwrap\f1)
.XX GROW/WRAP/SCROLL or scrolling.
.XX GROW/WRAP/SCROLL If growth is not
.XX GROW/WRAP/SCROLL \f(CWOL_GROW_OFF\f1
.XX GROW/WRAP/SCROLL the \*(bW widget will always try to grow to display text before
.XX GROW/WRAP/SCROLL trying to wrap or scroll.
.XX GROW/WRAP/SCROLL The success of a resize request is determined by the \*(bW
.XX GROW/WRAP/SCROLL widget's parent.
\f3XtNverticalSB\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
These resources determine if the \*(bW widget will have a
scrollbar along the side.
.sp
.XX SCROLLMENU .so SOURCEFILES/Widgets/common/XtN/hMenuPane
.XX SCROLLMENU .so SOURCEFILES/Widgets/common/XtN/vMenuPane
.sp
\f3XtNleaveVerification\f1
.P
This is the callback list used when the input focus leaves the
\*(bW widget.
The
\f(CWcall_data\f1
parameter is a pointer to an
\f(CWOlTextVerifyCD\f1
structure described earlier in \f3TEXT\f1.
.sp
\f3XtNleftMargin\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNleftMargin\f1
.in -5
.fi
.PP
This resource is the number of pixels used for the left margin.
.sp
.bp
\f3XtNmaximumSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNmaximumSize\f1
.in -5
.fi
.PP
This resource is used only if the
\f(CWXtNsourceType\f1
resource has the value
\f(CWOL_STRING_SOURCE\f1.
It is the maximum number of characters that can be entered into
the internal buffer.
If this value is not set, then the internal buffer will increase
its size as needed, limited only by the space limitations of the
process.
.sp
\f3XtNmodifyVerification\f1
.P
This callback list is called before text is deleted from or
inserted into the text source.
The
\f(CWcall_data\f1
parameter is a pointer to an
\f(CWOlTextVerifyCD\f1
structure described earlier.
.sp
\f3XtNmotionVerification\f1
.P
This callback list is called before the insertion cursor is
moved to a new position.
The
\f(CWcall_data\f1
parameter is a pointer to an
\f(CWOlTextVerifyCD\f1
structure described earlier in \f3TEXT\f1.
.sp
\f3XtNrecomputeSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.PP
This resource indicates whether the \*(bW widget should
calculate its size and automatically set the
\f(CWXtNheight\f1
and
\f(CWXtNwidth\f1
resources.
If set to
\f(CWTRUE\f1,
the \*(bW widget will do normal size calculations that may
cause its geometry to change.
If set to
\f(CWFALSE\f1,
the \*(bW widget will leave its size alone.
.P
This resource is ignored for each dimension that has an
associated scrollbar.
.sp
\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.
.sp
\f3XtNrightMargin\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNrightMargin\f1
.in -5
.fi
.PP
This resource is the number of pixels used for the right margin.
.sp
\f3XtNshowPage\f1
.P
This resource is directed to the vertical scrollbar in the
\*(bW widget.
See \f3SCROLLBAR\f1
for more detail.
.bp
\f3XtNsourceType\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWOL_STRING_SOURCE/"stringsrc"
OL_DISK_SOURCE/"disksrc"\f1
.XX PROGDEFSOURCE OL_PROG_DEFINED_SOURCE/"progdefinedsrc"\f1
.in -5
.fi
.PP
This resource defines the type of the text source.
.sp
\f3XtNstring\f1
.P
This resource is used only if the
\f(CWXtNsourceType\f1
resource has the value
\f(CWOL_STRING_SOURCE\f1.
This is the string to be viewed and/or edited.
A copy is made into an internal buffer allocated by the \*(bW
widget.
A call to
\f(CWXtGetValues()\f1
on this resource will return a copy of the internal buffer.
The application program is responsible for freeing the space
allocated by this copy.
.sp
\f3XtNtextClearBuffer\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.P
.in +0.5i
\f(CWvoid (*textClearBuffer)();
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextClearBuffer,(XtArgVal)&textClearBuffer }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CW(*textClearBuffer)(w)
Widget w;\f1
.fi
.in 0
.P
This function clears the internal buffer.
After this call, all characters in the buffer have been removed.
.sp
\f3XtNtextCopyBuffer\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWunsigned char *(*textCopyBuffer)(), *buf;
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextCopyBuffer, (XtArgVal)&textCopyBuffer }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CWbuf = (*textCopyBuffer)(w)
Widget w;\f1
.fi
.in 0
.P
This function uses
\f(CWXtMalloc()\f1
to create space for copying the internal buffer and
returns the pointer to that copy.
The application is responsible for freeing the space.
.sp
\f3XtNtextGetInsertPoint\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWOlTextPosition (*textGetInsertPoint)(), pos;
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextGetInsertPoint,(XtArgVal)&textGetInsertPoint }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CWpos = (*textGetInsertPoint)(w)
Widget w;\f1
.fi
.in 0
.P
This function returns the insertion position.
.sp
\f3XtNtextGetLastPos\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWOlTextPosition  (*textGetLastPos)(), pos;
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextGetLastPos, (XtArgVal)&textGetLastPos }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CWpos = (*textGetLastPos)(w, lastPos)
Widget w;
OltextPosition lastPos;\f1
.fi
.in 0
.PP
This function returns the last character position in the
buffer.
.sp
\f3XtNtextInsert\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWvoid (*textInsert)();
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextInsert, (XtArgVal)&textInsert }
};
XtGetValues(widget, query, XtNumber(query));
.sp0.5
\f(CW(*textInsert)(w, string)
Widget w;
unsigned char *string;\f1
.fi
.in 0
.P
This function inserts the string at the current insertion
position and advances the insertion position to the end of the
string.
.sp 0.75
\f3XtNtextReadSubString\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.25i
.sp 0.5
\f(CWint (*textReadSubString)();
.sp0.5
\f(CWstatic Arg query[] = {
        { XtNtextReadSubString,(XtArgVal)&textReadSubString }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CW(*textReadSubString)(w,startpos,endpos,target,tsize,tused)
Widget w;
OltextPosition startpos, endpos;
unsigned char *target;
int tsize, *tused;\f1
.fi
.in 0
.P
This function will move characters from the buffer into the
caller's space.
The caller must provide the space to copy into and its size in
bytes.
The routine will return the number of positions moved.
The value of
\f(CWtused\f1
returns the number of bytes used in the target string by the move.
.sp
\f3XtNtextRedraw\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWvoid (*textRedraw)();
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextRedraw, (XtArgVal)&textRedraw }
};
XtGetValues(widget, query, XtNumber(query));
.sp0.5
\f(CW(*textRedraw)(w);
Widget w;\f1
.fi
.in 0
.P
This function refreshes the widget's window.
.sp 0.75
\f3XtNtextReplace\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWOlEditResult (*textReplace)(), result;
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextReplace, (XtArgVal)&textReplace }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CWresult = (*textReplace)(w, startPos, endPos, text)
Widget w;
OltextPosition startPos, endPos;
unsigned char *text;\f1
.fi
.in 0
.P
This function removes text in the source from
\f(CWstartPos\f1
to
\f(CWendPos\f1
and inserts the string
\f(CWtext\f1 starting at
\f(CWstartPos\f1.
If
\f(CWstartPos\f1
and
\f(CWendPos\f1
are the same, the action is an insertion.
If \f(CWtext\f1 is the empty string,
the action is a deletion.
.sp
\f3XtNtextSetInsertPoint\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.25i
.sp 0.5
\f(CWvoid (*textSetInsertPoint)();
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextSetInsertPoint, (XtArgVal)&textSetInsertPoint }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CW(*textSetInsertPoint)(w, position)
Widget w;
OltextPosition position;\f1
.fi
.in 0
.P
This function sets the insertion point.
.sp
.XX SOURCE .so SOURCEFILES/Widgets/common/XtN/textSetSource
\f3XtNtextUpdate\f1
.P
.nf
\f1\s+1Synopsis:\s-1\f(CW
.in +0.5i
.sp 0.5
\f(CWvoid (*textUpdate)();
.sp 0.5
\f(CWstatic Arg query[] = {
        { XtNtextUpdate, (XtArgVal)&textUpdate }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f(CW(*textUpdate)(w, status)
Widget w;
Boolean status;\f1
.fi
.in 0
.P
This function turns the widget's screen updating function on
and off.
If the application needs to make a sequence of source change
calls,
a call to
\f(CWOlTextUpdate(FALSE)\f1
will prevent screen flash.
After the sequence of calls the application calls
\f(CWOlTextUpdate(TRUE)\f1
to update the window and resume normal updating.
Note that it is not necessary to turn off updating
for functions that only get values from the widget,
nor is it necessary to turn it off if the application only
makes one call that changes the widget.
.sp
\f3XtNtopMargin\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNtopMargin\f1
.in -5
.fi
.PP
This resource is the number of pixels used for the top margin.
.sp
\f3XtNviewHeight\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CW0 \(<= XtNviewHeight\f1
.in -5
.fi
.PP
This resource gives the preferred height, in lines, of the text pane.
If a nonzero value is given, the corresponding
\f(CWXtNheight\f1
resource is computed by converting this number to pixels and
adding the thickness of any scrollbar and border that appears.
In this case, any value in the
\f(CWXtNheight\f1
resource is overwritten.
.sp
If a zero value is given in the
\f(CWXtNviewHeight\f1
resource,
the
\f(CWXtNheight\f1
resource is used as an estimate.
The text pane is sized to show an integral number of lines,
such that the overall height of the \*(bW widget is less than
or equal to
\f(CWXtNheight\f1,
if possible.
However,
the text pane is always large enough to show at least one line
and is no shorter than the minimum scroll bar size.
.P
If neither the
\f(CWXtNviewHeight\f1
resource nor the
\f(CWXtNheight\f1
resource is set,
or both are set to zero,
the text pane is made as small as possible,
limited as described above.
.bp
\f3XtNtraversalOn\f1
.PP
Range of Values:
.br
.nf
.in +5
\f(CWTRUE
FALSE\fP
.fi
.in -5
.P
This resource specifies whether this widget is selectable
during traversal.
.XX MAXVIEW? .P
.XX MAXVIEW? These resources also represent the maximum size the View can
.XX MAXVIEW? be;
.XX MAXVIEW? while the \*(bW may resize the View smaller than indicated in
.XX MAXVIEW? these resources
.XX MAXVIEW? (cf.
.XX MAXVIEW? \f(CWXtNrecomputeViewHeight\f1
.XX MAXVIEW? and
.XX MAXVIEW? \f(CWXtNrecomputeViewWidth\f1)
.XX MAXVIEW? it will never resize the View larger than indicated.
.sp
\f3XtNwrap\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWTRUE
FALSE\f1
.in -5
.fi
.P
This resource specifies how the widget displays lines longer
than the screen width.
When set to
\f(CWFALSE\f1,
the lines may extend off screen to the right.
When set to
\f(CWTRUE\f1,
the lines will be wrapped at the right margin,
with the position determined by the resource
\f(CWXtNwrapBreak\f1.
.ig
Having a vertical scrollbar
(\f(CWXtNverticalSB\f1)
with this resource set to
\f(CWTRUE\f1
is redundant;
a warning is given and this resource is ignored.
..
.sp
\f3XtNwrapBreak\f1
.PP
Range of Values:
.br
.in +5
.nf
\f(CWOL_WRAP_ANY/"wrapany"
OL_WRAP_WHITE_SPACE/"wrapwhitespace"\f1
.in -5
.fi
.PP
This resource specifies how the wrap position is determined.
When set to
\f(CWOL_WRAP_ANY\f1,
the wrap will happen at the character position closest to the
right margin.
When set to
\f(CWOL_WRAP_WHITE_SPACE\f1,
the wrap will happen at the last white space before the right
margin.
If the line does not have white space, it will be wrapped as
\f(CWOL_WRAP_ANY\f1.
.sp
\f3Growing, Wrapping, Scrolling\f1
.P
The
\f(CWXtNgrow\f1,
\f(CWXtNwrap\f1,
and
\f(CWXtNverticalSB\f1
resources are used to control how the view of the text is
adjusted as new text is inserted.
Assuming the insertion would cause the current view to be too
small to show all the text,
the following table explains what happens.
A "yes" in the first column means that
\f(CWXtNgrow\f1
allows growing in the affected direction;
a "no" means it does not.
A "yes" in the second column means that the 
\f(CWXtNverticalSB\f1 resource is \f(CWTRUE\f1.
.TS
center, box;
cB | c | cB | l.
XtNgrow	Can scroll?	XtNwrap	Affect
=
.T&
c | c | c | l.
yes	yes	TRUE	grow if can, else scroll
\^	\^	_	\^
\^	\^	FALSE	\^
\^	_	_	_
\^	no	TRUE	grow if can, else clip
\^	\^	_	\^
\^	\^	FALSE	\^
_
no	yes	TRUE	wrap
\^	\^	_	_
\^	\^	FALSE	scroll
\^	_	_	_
\^	no	TRUE	wrap
\^	\^	_	_
\^	\^	FALSE	clip
.TE
