xref: /xsrc/external/mit/libXaw/dist/specs/TextFuncs.xml

<sect1 id="Text_Functions">
<title>Text Functions</title>
<!-- .XS -->
<!-- 	Text Functions -->
<!-- .XE -->
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
These data structures are defined in the Text widget's public header file,
&lt;X11/Xaw/Text.h&gt;.
</para>
<para>
<!-- .LP -->
<!-- .IN "XawTextPosition" "" "@DEF@" -->
typedef long XawTextPosition;
<!-- .sp -->
</para>
<para>
<!-- .LP -->
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.
</para>
<para>
<!-- .LP -->
<!-- .IN "XawTextBlock" "" "@DEF@" -->
<literallayout class="monospaced">
<!-- .TA .5i 1.5i 2.25i -->
<!-- .ta .5i 1.5i 2.25i -->
typedef struct {
	int <emphasis remap='I'>firstPos</emphasis>;
	int <emphasis remap='I'>length</emphasis>;
	char *<emphasis remap='I'>ptr</emphasis>;
	unsigned long <emphasis remap='I'>format</emphasis>;
} XawTextBlock, *XawTextBlockPtr;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .IN "XawTextBlockPtr" "" -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>firstPos</emphasis>
    </term>
    <listitem>
      <para>
The first position, or index, to use within the <emphasis remap='I'>ptr</emphasis> field.
The value is commonly zero.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>length</emphasis>
    </term>
    <listitem>
      <para>
The number of characters to be used from the <emphasis remap='I'>ptr</emphasis> field.
The number of characters used is commonly the number of characters
in <emphasis remap='I'>ptr</emphasis>, and must not be greater than the length of the string
in <emphasis remap='I'>ptr</emphasis>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>ptr</emphasis>
    </term>
    <listitem>
      <para>
Contains the string to be referenced by the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>format</emphasis>
    </term>
    <listitem>
      <para>
This flag indicates whether the data pointed to by <function>ptr</function> is char
or wchar_t.  When the associated widget has <function>international</function> set
to <function>false</function> this field must be XawFmt8Bit.  When the associated
widget has <function>international</function> set to <function>true</function> this field must be
either XawFmt8Bit or XawFmtWide.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<note>
<para>
<!-- .LP -->
Note: Previous versions of Xaw used
<function>FMT8BIT ,</function>
which has been retained for backwards compatibility. <function>FMT8BIT</function> is
deprecated and will eventually be removed from the implementation.
</para>
</note>
<sect2 id="Selecting_Text">
<title>Selecting Text</title>
<para>
<!-- .LP -->
To select a piece of text, use
<function>XawTextSetSelection : </function>
<!-- .IN "XawTextSetSelection" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextSetSelection</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextPositionleft,<parameter> right</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>left</emphasis>
    </term>
    <listitem>
      <para>
Specifies the character position at which the selection begins.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>right</emphasis>
    </term>
    <listitem>
      <para>
Specifies the character position at which the selection ends.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function>.  <!-- xref --> 
If redisplay is enabled, this function highlights the text and
makes it the <function>PRIMARY</function> selection.  This function does not have any
effect on <function>CUT_BUFFER0</function>.
</para>
<para>
<!-- .LP -->
</para>
</sect2>
<sect2 id="Unhighlighting_Text">
<title>Unhighlighting Text</title>
<para>
<!-- .LP -->
To unhighlight previously highlighted text in a widget, use
<function>XawTextUnsetSelection</function>:
<!-- .IN "XawTextUnsetSelection" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextUnsetSelection</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="Getting_Current_Text_Selection">
<title>Getting Current Text Selection</title>
<para>
<!-- .LP -->
To retrieve the text that has been selected by this
text widget use <function>XawTextGetSelectionPos</function>:
<!-- .IN "XawTextGetSelectionPos" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextGetSelectionPos</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextPosition*begin_return,<parameter> *end_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>begin_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the beginning of the text selection.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>end_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the end of the text selection.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> 
If the returned values are equal, no text is currently selected.
</para>
</sect2>
<sect2 id="Replacing_Text">
<title>Replacing Text</title>
<para>
<!-- .LP -->
To modify the text in an editable Text widget use <function>XawTextReplace</function>:
<!-- .IN "XawTextReplace" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>int<function> XawTextReplace</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
  <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>start</emphasis>
    </term>
    <listitem>
      <para>
Specifies the starting character position of the text replacement.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>end</emphasis>
    </term>
    <listitem>
      <para>
Specifies the ending character position of the text replacement.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>text</emphasis>
    </term>
    <listitem>
      <para>
Specifies the text to be inserted into the file.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
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.
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function> and <!-- xref -->
<function>XawTextBlock</function>.
</para>
<para>
<!-- .LP -->
This function may return the following values:
<variablelist>
  <varlistentry>
    <term>
      <function>XawEditDone</function>
    </term>
    <listitem>
      <para>
<!-- .IN "XawEditDone" "" -->
The text replacement was successful.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <function>XawPositionError</function>
    </term>
    <listitem>
      <para>
<!-- .IN "XawPositionError" "" -->
The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the position of
the last character of the source.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <function>XawEditError</function>
    </term>
    <listitem>
      <para>
<!-- .IN "XawEditError" "" -->
Either the Source was read-only or the range to be deleted is larger
than the length of the Source.

    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
The <function>XawTextReplace</function> arguments <function>start</function> and
<emphasis remap='I'>end</emphasis> 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 <emphasis remap='I'>start</emphasis> up to
but not including <emphasis remap='I'>end</emphasis> are deleted, and the characters
specified on the text block are inserted in their place.  If
<emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and the new
text is inserted after <emphasis remap='I'>start</emphasis>.
</para>
</sect2>
<sect2 id="Searching_for_Text">
<title>Searching for Text</title>
<para>
<!-- .LP -->
To search for a string in the Text widget, use
<function>XawTextSearch</function>:
<!-- .IN "XawTextSearch" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>XawTextPosition<function> XawTextSearch</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
  <paramdef>XawTextBlock*<parameter> text</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>dir</emphasis>
    </term>
    <listitem>
      <para>
Specifies the direction to search in.  Legal values are
<function>XawsdLeft</function> and <function>XawsdRight</function>.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>text</emphasis>
    </term>
    <listitem>
      <para>
Specifies a text block structure that contains the text to search for.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function> and <function>XawTextBlock</function>. <!-- xref -->
The <function>XawTextSearch</function> function will begin at the insertion point
and search in the
direction specified for a string that matches the one passed in
<emphasis remap='I'>text</emphasis>.  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 <function>XawTextSearchError</function> is returned.
</para>
</sect2>
<sect2 id="Redisplaying_Text">
<title>Redisplaying Text</title>
<para>
<!-- .LP -->
To redisplay a range of characters, use <function>XawTextInvalidate</function>:
<!-- .IN "XawTextInvalidate" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextInvalidate</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextPositionfrom,<parameter> to</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>from</emphasis>
    </term>
    <listitem>
      <para>
Specifies the start of the text to redisplay.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>to</emphasis>
    </term>
    <listitem>
      <para>
Specifies the end of the text to redisplay.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
The <function>XawTextInvalidate</function>
function causes the specified range of characters to be redisplayed
immediately if redisplay is enabled or the next time that redisplay is
enabled.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To enable redisplay, use <function>XawTextEnableRedisplay</function>:
<!-- .IN "XawTextEnableRedisplay" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextEnableRedisplay</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
The <function>XawTextEnableRedisplay</function> function flushes any changes due to
batched updates when <function>XawTextDisableRedisplay</function>
was called and allows future changes to be reflected immediately.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To disable redisplay while making several changes, use
<function>XawTextDisableRedisplay</function>.
<!-- .IN "XawTextDisableRedisplay" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextDisableRedisplay</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
The <function>XawTextDisableRedisplay</function> function causes all changes to be
batched until either <function>XawTextDisplay</function> or <function>XawTextEnableRedisplay</function>
is called.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To display batched updates, use <function>XawTextDisplay</function>:
<!-- .IN "XawTextDisplay" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextDisplay</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
The <function>XawTextDisplay</function> function forces any accumulated updates to be
displayed.
</para>
</sect2>
<sect2 id="Resources_Convenience_Routines">
<title>Resources Convenience Routines</title>
<para>
<!-- .LP -->
To obtain the character position of the left-most character on the
first line displayed in the widget (the value of the
<function>displayPosition</function> resource), use <function>XawTextTopPosition</function>.
<!-- .IN "XawTextTopPosition" "" @DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>XawTextPosition<function> XawTextTopPosition</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To assign a new selection array to a text widget use
<function>XawTextSetSelectionArray</function>:
<!-- .IN "XawTextSetSelectionArray" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextSetSelectionArray</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextSelectType*<parameter> sarray</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>sarray</emphasis>
    </term>
    <listitem>
      <para>
Specifies a selection array as defined in the section called \fBText
Selections for Application Programmers\fP.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
Calling this function is equivalent to setting the value of the
<function>selectionTypes</function> resource.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To move the insertion point to the specified source position, use
<function>XawTextSetInsertionPoint</function>:
<!-- .IN "XawTextSetInsertionPoint" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextSetInsertionPoint</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>position</emphasis>
    </term>
    <listitem>
      <para>
Specifies the new position for the insertion point.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
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 <function>insertPosition</function> resource.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To obtain the current position of the insertion point, use
<function>XawTextGetInsertionPoint</function>:
<!-- .IN "XawTextGetInsertionPoint" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>XawTextPosition<function> XawTextGetInsertionPoint</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
The result is equivalent to retrieving the value of the
<function>insertPosition</function> resource.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To replace the text source in the specified widget, use
<function>XawTextSetSource</function>:
<!-- .IN "XawTextSetSource" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextSetSource</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>Widget<parameter> source</parameter></paramdef>
  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>source</emphasis>
    </term>
    <listitem>
      <para>
Specifies the text source object.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>position</emphasis>
    </term>
    <listitem>
      <para>
Specifies character position that will become the upper left hand corner
of the displayed text.  This is usually set to zero.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
A display update will be performed if redisplay is enabled.
</para>
<para>
<!-- .LP -->
<!-- .sp 1 -->
To obtain the current text source for the specified widget, use
<function>XawTextGetSource</function>:
<!-- .IN "XawTextGetSource" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>Widget<function> XawTextGetSource</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
This function returns the text source that this Text widget is currently
using.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To enable and disable the insertion point, use
<function>XawTextDisplayCaret</function>:
<!-- .IN "XawTextDisplayCaret" "" "@DEF@" -->
<funcsynopsis>
<funcprototype>
  <funcdef>void<function> XawTextDisplayCaret</function></funcdef>
  <paramdef>Widget<parameter> w</parameter></paramdef>
  <paramdef>Boolean<parameter> visible</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the Text widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>visible</emphasis>
    </term>
    <listitem>
      <para>
Specifies whether or not the caret should be displayed.
    </para>
  </listitem>
  </varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
If <function>visible</function> is <function>False</function> the insertion point will be disabled.
The marker is re-enabled either by setting <function>visible</function> to <function>True</function>, by
calling <function>XtSetValues</function>, or by executing the <function>display-caret</function>
action routine.
</para>
</sect2>
</sect1>