Text Functions
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.
These data structures are defined in the Text widget's public header file,
<X11/Xaw/Text.h>.
XawTextPosition
typedef long XawTextPosition;
Character positions in the Text widget begin at 0 and end at n, where
n is the number of characters in the Text source widget.
XawTextBlock
typedef struct {
int firstPos;
int length;
char *ptr;
unsigned long format;
} XawTextBlock, *XawTextBlockPtr;
XawTextBlockPtrfirstPos
The first position, or index, to use within the ptr field.
The value is commonly zero.
length
The number of characters to be used from the ptr field.
The number of characters used is commonly the number of characters
in ptr, and must not be greater than the length of the string
in ptr.
ptr
Contains the string to be referenced by the Text widget.
format
This flag indicates whether the data pointed to by ptr is char
or wchar_t. When the associated widget has international set
to false this field must be XawFmt8Bit. When the associated
widget has international set to true this field must be
either XawFmt8Bit or XawFmtWide.
Note: Previous versions of Xaw used
FMT8BIT,
which has been retained for backwards compatibility. FMT8BIT is
deprecated and will eventually be removed from the implementation.
Selecting Text
To select a piece of text, use
XawTextSetSelection : XawTextSetSelectionvoid XawTextSetSelectionWidget wXawTextPositionleft, rightw
Specifies the Text widget.
left
Specifies the character position at which the selection begins.
right
Specifies the character position at which the selection ends.
See section 5.4
for a description of XawTextPosition.
If redisplay is enabled, this function highlights the text and
makes it the PRIMARY selection. This function does not have any
effect on CUT_BUFFER0.
Unhighlighting Text
To unhighlight previously highlighted text in a widget, use
:
XawTextUnsetSelectionvoid XawTextUnsetSelectionWidget ww
Specifies the Text widget.
Getting Current Text Selection
To retrieve the text that has been selected by this
text widget use :
XawTextGetSelectionPosvoid XawTextGetSelectionPosWidget wXawTextPosition*begin_return, *end_returnw
Specifies the Text widget.
begin_return
Returns the beginning of the text selection.
end_return
Returns the end of the text selection.
See section 5.4
for a description of XawTextPosition.
If the returned values are equal, no text is currently selected.
Replacing Text
To modify the text in an editable Text widget use :
XawTextReplaceint XawTextReplaceWidget wXawTextPositionstart, endXawTextBlock *textw
Specifies the Text widget.
start
Specifies the starting character position of the text replacement.
end
Specifies the ending character position of the text replacement.
text
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.
See section 5.4
for a description of XawTextPosition and
XawTextBlock.
This function may return the following values:
XawEditDoneXawEditDone
The text replacement was successful.
XawPositionErrorXawPositionError
The edit mode is XawtextAppend and start is not the position of
the last character of the source.
XawEditErrorXawEditError
Either the Source was read-only or the range to be deleted is larger
than the length of the Source.
The arguments start and
end 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 start up to
but not including end are deleted, and the characters
specified on the text block are inserted in their place. If
start and end are equal, no text is deleted and the new
text is inserted after start.
Searching for Text
To search for a string in the Text widget, use
:
XawTextSearchXawTextPosition XawTextSearchWidget wXawTextScanDirection dirXawTextBlock* textw
Specifies the Text widget.
dir
Specifies the direction to search in. Legal values are
XawsdLeft and XawsdRight.
text
Specifies a text block structure that contains the text to search for.
See section 5.4 for a description of
XawTextPosition and XawTextBlock.
The function will begin at the insertion point
and search in the
direction specified for a string that matches the one passed in
text. 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 XawTextSearchError is returned.
Redisplaying Text
To redisplay a range of characters, use :
XawTextInvalidatevoid XawTextInvalidateWidget wXawTextPositionfrom, tow
Specifies the Text widget.
from
Specifies the start of the text to redisplay.
to
Specifies the end of the text to redisplay.
See section 5.4
for a description of XawTextPosition.
The
function causes the specified range of characters to be redisplayed
immediately if redisplay is enabled or the next time that redisplay is
enabled.
To enable redisplay, use :
XawTextEnableRedisplayvoid XawTextEnableRedisplayWidget ww
Specifies the Text widget.
The function flushes any changes due to
batched updates when
was called and allows future changes to be reflected immediately.
To disable redisplay while making several changes, use
.
XawTextDisableRedisplayvoid XawTextDisableRedisplayWidget ww
Specifies the Text widget.
The function causes all changes to be
batched until either or
is called.
To display batched updates, use :
XawTextDisplayvoid XawTextDisplayWidget ww
Specifies the Text widget.
The function forces any accumulated updates to be
displayed.
Resources Convenience Routines
To obtain the character position of the left-most character on the
first line displayed in the widget (the value of the
displayPosition resource), use .
XawTextTopPositionXawTextPosition XawTextTopPositionWidget ww
Specifies the Text widget.
To assign a new selection array to a text widget use
:
XawTextSetSelectionArrayvoid XawTextSetSelectionArrayWidget wXawTextSelectType* sarrayw
Specifies the Text widget.
sarray
Specifies a selection array as defined in
.
Calling this function is equivalent to setting the value of the
selectionTypes resource.
To move the insertion point to the specified source position, use
:
XawTextSetInsertionPointvoid XawTextSetInsertionPointWidget wXawTextPosition positionw
Specifies the Text widget.
position
Specifies the new position for the insertion point.
See section 5.4
for a description of XawTextPosition.
The text will be scrolled vertically if necessary to make the line
containing the insertion point visible. Calling this function is
equivalent to setting the insertPosition resource.
To obtain the current position of the insertion point, use
:
XawTextGetInsertionPointXawTextPosition XawTextGetInsertionPointWidget ww
Specifies the Text widget.
See section 5.4
for a description of XawTextPosition.
The result is equivalent to retrieving the value of the
insertPosition resource.
To replace the text source in the specified widget, use
:
XawTextSetSourcevoid XawTextSetSourceWidget wWidget sourceXawTextPosition positionw
Specifies the Text widget.
source
Specifies the text source object.
position
Specifies character position that will become the upper left hand corner
of the displayed text. This is usually set to zero.
See section 5.4
for a description of XawTextPosition.
A display update will be performed if redisplay is enabled.
To obtain the current text source for the specified widget, use
:
XawTextGetSourceWidget XawTextGetSourceWidget ww
Specifies the Text widget.
This function returns the text source that this Text widget is currently
using.
To enable and disable the insertion point, use
:
XawTextDisplayCaretvoid XawTextDisplayCaretWidget wBoolean visiblew
Specifies the Text widget.
visible
Specifies whether or not the caret should be displayed.
If visible is False the insertion point will be disabled.
The marker is re-enabled either by setting visible to True, by
calling , or by executing the display-caret
action routine.