# 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>.

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.

    typedef struct {
    	int firstPos;
    	int length;
    	char *ptr;
    	unsigned long format;
    } XawTextBlock, *XawTextBlockPtr;

firstPos

  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 :`

      void XawTextSetSelection
      Widget w
      XawTextPositionleft, right

w

  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 :

      void XawTextUnsetSelection
      Widget w

w

  Specifies the Text widget.

## Getting Current Text Selection

To retrieve the text that has been selected by this text widget use :

      void XawTextGetSelectionPos
      Widget w
      XawTextPosition*begin_return, *end_return

w

  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 :

      int XawTextReplace
      Widget w
      XawTextPositionstart, end
      XawTextBlock *text

w

  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:

`XawEditDone`

  The text replacement was successful.

`XawPositionError`

  The edit mode is `XawtextAppend` and `start` is not the position of the last character of the source.

`XawEditError`

  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 :

      XawTextPosition XawTextSearch
      Widget w
      XawTextScanDirection dir
      XawTextBlock* text

w

  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 :

      void XawTextInvalidate
      Widget w
      XawTextPositionfrom, to

w

  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 :

      void XawTextEnableRedisplay
      Widget w

w

  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 .

      void XawTextDisableRedisplay
      Widget w

w

  Specifies the Text widget.

The function causes all changes to be batched until either or is called.

To display batched updates, use :

      void XawTextDisplay
      Widget w

w

  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 .

      XawTextPosition XawTextTopPosition
      Widget w

w

  Specifies the Text widget.

To assign a new selection array to a text widget use :

      void XawTextSetSelectionArray
      Widget w
      XawTextSelectType* sarray

w

  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 :

      void XawTextSetInsertionPoint
      Widget w
      XawTextPosition position

w

  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 :

      XawTextPosition XawTextGetInsertionPoint
      Widget w

w

  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 :

      void XawTextSetSource
      Widget w
      Widget source
      XawTextPosition position

w

  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 :

      Widget XawTextGetSource
      Widget w

w

  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 :

      void XawTextDisplayCaret
      Widget w
      Boolean visible

w

  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.