.NH 2
Text Functions
.XS
	Text Functions
.XE
.LP
The following functions are provided as convenience routines for use with
the Text widget.  Although many of these actions can be performed by
modifying resources, these interfaces are frequently more efficient.
.NH 3
Selecting Text
.LP
To select a piece of text, use 
.PN XawTextSetSelection :
.IN "XawTextSetSelection" "" "@DEF@"
.FD 0
void XawTextSetSelection(\fIw\fP, \fIleft\fP, \fIright\fP)
.br
     Widget \fIw\fP;
.br
     XawTextPosition \fIleft\fP, \fIright\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIleft\fP 1i
Specifies the character position at which the selection begins.
.IP \fIright\fP 1i
Specifies the character position at which the selection ends.
.LP
If redisplay is enabled, this function highlights the text and
makes it the \fBPRIMARY\fP selection.  This function does not have any
effect on \fBCUT_BUFFER0\fP.
.LP
.NH 3
Unhighlighting Text
.LP
To unhighlight previously highlighted text in a widget, use
\fBXawTextUnsetSelection\fP:
.IN "XawTextUnsetSelection" "" "@DEF@"
.FD 0
void XawTextUnsetSelection(\fIw\fP)
.br
     Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.NH 3
Getting Current Text Selection
.LP
To retrieve the text that has been selected by this
text widget use \fBXawTextGetSelectionPos\fP:
.IN "XawTextGetSelectionPos" "" "@DEF@"
.FD 0
void XawTextGetSelectionPos(\fIw\fP, \fIbegin_return\fP, \fIend_return\fP)
.br
     Widget \fIw\fP;
.br
     XawTextPosition *\fIbegin_return\fP, *\fIend_return\fP; 
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIbegin_return\fP 1i
Returns the beginning of the text selection.
.IP \fIend_return\fP 1i
Returns the end of the text selection.
.LP
If the returned values are equal, no text is currently selected.
.NH 3
Replacing Text
.LP
To modify the text in an editable Text widget use \fBXawTextReplace\fP:
.IN "XawTextReplace" "" "@DEF@"
.FD 0
int XawTextReplace(\fIw\fP, \fIstart\fP, \fIend\fP, \fItext\fP)
.br
     Widget \fIw\fP;
.br
     XawTextPosition \fIstart\fP, \fIend\fP;
.br
     XawTextBlock *\fItext\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIstart\fP 1i
Specifies the starting character position of the text replacement.
.IP \fIend\fP 1i
Specifies the ending character position of the text replacement.
.IP \fItext\fP 1i
Specifies the text to be inserted into the file.  This function will not
be able to replace text in read-only text widgets.  It will also only
be able to append text to an append-only text widget.
.LP
This function may return the following values:
.IP \fBXawEditDone\fP 1.25i
.IN "XawEditDone" ""
The text replacement was successful.
.IP \fBXawPositionError\fP 1.25i
.IN "XawPositionError" ""
The edit mode is \fBXawtextAppend\fP and \fIstart\fP is not the last
character of the source.
.IP \fBXawEditError\fP 1.25i
.IN "XawEditError" ""
Either the Source was read-only or the range to be deleted is larger
than the length of the Source. 
.LP
.sp 1
The \fBXawTextBlock\fP structure is defined in the Text widget's
public header file as follows: 
.LP
.IN "XawTextBlock" "" "@DEF@"
.Ds 0
.TA .5i 1.5i 2.25i 
.ta .5i 1.5i 2.25i
typedef struct {
	int \fIfirstPos\fP;
	int \fIlength\fP;
	char \fI*ptr\fP;
	Atom \fIformat\fP;
} XawTextBlock, *TextBlockPtr;
.De
.LP
.IN "XawTextBlock" ""
.IN "TextBlockPtr" ""
.IN "TextBlock" ""
.IP \fIfirstPos\fP 1.0i
The starting point to use within the ptr field.
The value is usually zero.  
.IP \fIlength\fP 1.0i
The number of characters that to be transferred from the
ptr field.  The number of characters transferred is usually the number
of characters in ptr.
.IP \fIptr\fP 1.0i
Contains the string to insert into the text widget.
.IP \fIformat\fP 1.0i
This field is not currently used, but should be specified as
\fBFMT8BIT\fP.  
.LP
The \fBXawTextReplace\fP arguments \fIstart\fP and
\fIend\fP represent the text source character positions for the
existing text that is to be replaced by the text in the text block.
The characters from \fIstart\fP up to
but not including \fIend\fP are deleted, and the characters
specified on the text block are inserted in their place.  If
\fIstart\fP and \fIend\fP are equal, no text is deleted and the new
text is inserted after \fIstart\fP. 
.NH 3
Searching for Text
.LP
To search for a string in the Text widget, use
\fBXawTextSearch\fP:
.IN "XawTextSearch" "" "@DEF@"
.FD 0
XawTextPosition XawTextSearch(\fIw\fP, \fIdir\fP, \fItext\fP)
.br
      Widget \fIw\fP;
.br
      XawTextScanDirection \fIdir\fP;
.br
      XawTextBlock * \fItext\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIdir\fP 1i
Specifies the direction to search in.  Legal values are
\fBXawsdLeft\fP and \fBXawsdRight\fP.
.IP \fItext\fP 1i
Specifies a text block structure (see \fBXawTextReplace\fP for the
definition) that contains the text to search for.
.LP
The \fBXawTextSearch\fP function will begin at the insert point
location and search in the 
direction specified for a string that matches the one passed in 
\fItext\fP.  If the string is found the location of the first
character in the string is returned.  If the string could not be
found then the value \fBXawTextSearchError\fP is returned.
.NH 3
Redisplaying Text
.LP
To redisplay a range of characters, use \fBXawTextInvalidate\fP:
.IN "XawTextInvalidate" "" "@DEF@"
.FD 0
void XawTextInvalidate(\fIw\fP, \fIfrom\fP, \fIto\fP)
.br
      Widget \fIw\fP;
.br
      XawTextPosition \fIfrom\fP, \fIto\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIfrom\fP 1i
Specifies the start of the text to redisplay.
.IP \fIto\fP 1i
Specifies the end of the text to redisplay.
.LP
The \fBXawTextInvalidate\fP
function causes the specified range of characters to be redisplayed
immediately if redisplay is enabled or the next time that redisplay is
enabled.
.LP
.sp 1
To enable redisplay, use \fBXawTextEnableRedisplay\fP:
.IN "XawTextEnableRedisplay" "" "@DEF@"
.FD 0
void XawTextEnableRedisplay(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.LP
The \fBXawTextEnableRedisplay\fP function flushes any changes due to
batched updates when \fBXawTextDisableRedisplay\fP
was called and allows future changes to be reflected immediately.
.LP
.sp 1
To disable redisplay while making several changes, use
\fBXawTextDisableRedisplay\fP.
.IN "XawTextDisableRedisplay" "" "@DEF@"
.FD 0
void XawTextDisableRedisplay(\fIw\fP)
.br
       Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.LP
The \fBXawTextDisableRedisplay\fP function causes all changes to be
batched until either \fBXawTextDisplay\fP or \fBXawTextEnableRedisplay\fP
is called.
.LP
.sp 1
To display batched updates, use \fBXawTextDisplay\fP:
.IN "XawTextDisplay" "" "@DEF@" 
.FD 0
void XawTextDisplay(\fIw\fP)
.br
     Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.LP
The \fBXawTextDisplay\fP function forces any accumulated updates to be
displayed. 
.NH 3
Resources Convenience Routines
.LP
To obtain the character position of the left-most character on the
first line displayed in the widget (the value of the
\fBdisplayPosition\fP resource), use \fBXawTextTopPosition\fP.
.IN "XawTextTopPosition" "" @DEF@"
.FD 0
XawTextPosition XawTextTopPosition(\fIw\fP)
.br    
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.LP
.sp 1
To assign a new selection array to a text widget use
\fBXawTextSetSelectionArray\fP:
.IN "XawTextSetSelectionArray" "" "@DEF@"
.FD 0
void XawTextSetSelectionArray(\fIw\fP, \fIsarray\fP)
.br
      Widget \fIw\fP;
.br
      XawTextSelectType * \fIsarray\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIsarray\fP 1i
Specifies a selection array as defined in the section called \fBText
Selections for Application Programmers\fP.
.LP
Calling this function is equivalent to setting the value of the
\fBselectionTypes\fP resource. 
.LP
.sp 1
To move the insert point to the specified source position, use
\fBXawTextSetInsertionPoint\fP:
.IN "XawTextSetInsertionPoint" "" "@DEF@"
.FD 0
void XawTextSetInsertionPoint(\fIw\fP, \fIposition\fP)
.br        
      Widget \fIw\fP;
.br
      XawTextPosition \fIposition\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIposition\fP 1i
Specifies the new position for the insert point.
.LP
The text will be scrolled vertically if necessary to make the line
containing the insert point visible.  Calling this function is
equivalent to setting the \fBinsertPosition\fP resource. 
.LP
.sp 1
To obtain the current position of the insert point, use
\fBXawTextGetInsertionPoint\fP:
.IN "XawTextGetInsertionPoint" "" "@DEF@"
.FD 0
XawTextPosition XawTextGetInsertionPoint(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.LP
The result is equivalent to retrieving the value of the
\fBinsertPosition\fP resource. 
.LP
.sp 1
To replace the text source in the specified widget, use
\fBXawTextSetSource\fP:
.IN "XawTextSetSource" "" "@DEF@"
.FD 0
void XawTextSetSource(\fIw\fP, \fIsource\fP, \fIposition\fP)
.br
      Widget \fIw\fP;
.br
      Widget \fIsource\fP;
.br
      XawTextPosition \fIposition\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIsource\fP 1i
Specifies the text source object.
.IP \fIposition\fP 1i
Specifies character position that will become the upper left hand corner
of the displayed text.  This is usually set to zero.
.LP
A display update will be performed if redisplay is enabled.
.LP
.sp 1
To obtain the current text source for the specified widget, use
\fBXawTextGetSource\fP:
.IN "XawTextGetSource" "" "@DEF@"
.FD 0
Widget XawTextGetSource(\fIw\fP)
.br    
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.LP
This function returns the text source that this Text widget is currently
using.
.LP
.sp
To enable and disable the insert point, use
\fBXawTextDisplayCaret\fP:
.IN "XawTextDisplayCaret" "" "@DEF@"
.FD 0
void XawTextDisplayCaret(\fIw\fP, \fIvisible\fP)
.br
      Widget \fIw\fP;
.br
      Boolean \fIvisible\fP;
.FN
.IP \fIw\fP 1i
Specifies the Text widget.
.IP \fIvisible\fP 1i
Specifies whether or not the caret should be displayed.
.LP
If \fIvisible\fP is \fBFalse\fP the insert point will be disabled.
The marker is re-enabled either by setting \fIvisible\fP to \fBTrue\fP, by
calling \fBXtSetValues\fP, or by executing the \fIdisplay-caret\fP
action routine.
