diff options
Diffstat (limited to 'libXaw/specs/TextFuncs.xml')
| -rw-r--r-- | libXaw/specs/TextFuncs.xml | 856 |
1 files changed, 856 insertions, 0 deletions
diff --git a/libXaw/specs/TextFuncs.xml b/libXaw/specs/TextFuncs.xml new file mode 100644 index 000000000..0d2ae8192 --- /dev/null +++ b/libXaw/specs/TextFuncs.xml @@ -0,0 +1,856 @@ +<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, +<X11/Xaw/Text.h>. +</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> |