TextFuncs.xml revision 994689c1 
1<sect1 id="Text_Functions">
2<title>Text Functions</title>
3<!-- .XS -->
4<!-- 	Text Functions -->
5<!-- .XE -->
6<para>
7<!-- .LP -->
8The following functions are provided as convenience routines for use with
9the Text widget.  Although many of these actions can be performed by
10modifying resources, these interfaces are frequently more efficient.
11</para>
12<para>
13<!-- .LP -->
14These data structures are defined in the Text widget's public header file,
15&lt;X11/Xaw/Text.h&gt;.
16</para>
17<para>
18<!-- .LP -->
19<!-- .IN "XawTextPosition" "" "@DEF@" -->
20typedef long XawTextPosition;
21<!-- .sp -->
22</para>
23<para>
24<!-- .LP -->
25Character positions in the Text widget begin at 0 and end at n, where
26n is the number of characters in the Text source widget.
27</para>
28<para>
29<!-- .LP -->
30<!-- .IN "XawTextBlock" "" "@DEF@" -->
31<literallayout class="monospaced">
32<!-- .TA .5i 1.5i 2.25i -->
33<!-- .ta .5i 1.5i 2.25i -->
34typedef struct {
35	int <emphasis remap='I'>firstPos</emphasis>;
36	int <emphasis remap='I'>length</emphasis>;
37	char *<emphasis remap='I'>ptr</emphasis>;
38	unsigned long <emphasis remap='I'>format</emphasis>;
39} XawTextBlock, *XawTextBlockPtr;
40</literallayout>
41</para>
42<para>
43<!-- .LP -->
44<!-- .IN "XawTextBlockPtr" "" -->
45<variablelist>
46  <varlistentry>
47    <term>
48      <emphasis remap='I'>firstPos</emphasis>
49    </term>
50    <listitem>
51      <para>
52The first position, or index, to use within the <emphasis remap='I'>ptr</emphasis> field.
53The value is commonly zero.
54      </para>
55    </listitem>
56  </varlistentry>
57  <varlistentry>
58    <term>
59      <emphasis remap='I'>length</emphasis>
60    </term>
61    <listitem>
62      <para>
63The number of characters to be used from the <emphasis remap='I'>ptr</emphasis> field.
64The number of characters used is commonly the number of characters
65in <emphasis remap='I'>ptr</emphasis>, and must not be greater than the length of the string
66in <emphasis remap='I'>ptr</emphasis>.
67      </para>
68    </listitem>
69  </varlistentry>
70  <varlistentry>
71    <term>
72      <emphasis remap='I'>ptr</emphasis>
73    </term>
74    <listitem>
75      <para>
76Contains the string to be referenced by the Text widget.
77      </para>
78    </listitem>
79  </varlistentry>
80  <varlistentry>
81    <term>
82      <emphasis remap='I'>format</emphasis>
83    </term>
84    <listitem>
85      <para>
86This flag indicates whether the data pointed to by <function>ptr</function> is char
87or wchar_t.  When the associated widget has <function>international</function> set
88to <function>false</function> this field must be XawFmt8Bit.  When the associated
89widget has <function>international</function> set to <function>true</function> this field must be
90either XawFmt8Bit or XawFmtWide.
91    </para>
92  </listitem>
93  </varlistentry>
94</variablelist>
95</para>
96<note>
97<para>
98<!-- .LP -->
99Note: Previous versions of Xaw used
100<function>FMT8BIT ,</function>
101which has been retained for backwards compatibility. <function>FMT8BIT</function> is
102deprecated and will eventually be removed from the implementation.
103</para>
104</note>
105<sect2 id="Selecting_Text">
106<title>Selecting Text</title>
107<para>
108<!-- .LP -->
109To select a piece of text, use
110<function>XawTextSetSelection : </function>
111<!-- .IN "XawTextSetSelection" "" "@DEF@" -->
112<funcsynopsis>
113<funcprototype>
114  <funcdef>void<function> XawTextSetSelection</function></funcdef>
115  <paramdef>Widget<parameter> w</parameter></paramdef>
116  <paramdef>XawTextPositionleft,<parameter> right</parameter></paramdef>
117</funcprototype>
118</funcsynopsis>
119<!-- .FN -->
120<variablelist>
121  <varlistentry>
122    <term>
123      <emphasis remap='I'>w</emphasis>
124    </term>
125    <listitem>
126      <para>
127Specifies the Text widget.
128      </para>
129    </listitem>
130  </varlistentry>
131  <varlistentry>
132    <term>
133      <emphasis remap='I'>left</emphasis>
134    </term>
135    <listitem>
136      <para>
137Specifies the character position at which the selection begins.
138      </para>
139    </listitem>
140  </varlistentry>
141  <varlistentry>
142    <term>
143      <emphasis remap='I'>right</emphasis>
144    </term>
145    <listitem>
146      <para>
147Specifies the character position at which the selection ends.
148    </para>
149  </listitem>
150  </varlistentry>
151</variablelist>
152</para>
153<para>
154<!-- .LP -->
155See section 5.4 for a description of <function>XawTextPosition</function>.  <!-- xref --> 
156If redisplay is enabled, this function highlights the text and
157makes it the <function>PRIMARY</function> selection.  This function does not have any
158effect on <function>CUT_BUFFER0</function>.
159</para>
160<para>
161<!-- .LP -->
162</para>
163</sect2>
164<sect2 id="Unhighlighting_Text">
165<title>Unhighlighting Text</title>
166<para>
167<!-- .LP -->
168To unhighlight previously highlighted text in a widget, use
169<function>XawTextUnsetSelection</function>:
170<!-- .IN "XawTextUnsetSelection" "" "@DEF@" -->
171<funcsynopsis>
172<funcprototype>
173  <funcdef>void<function> XawTextUnsetSelection</function></funcdef>
174  <paramdef>Widget<parameter> w</parameter></paramdef>
175</funcprototype>
176</funcsynopsis>
177<!-- .FN -->
178<variablelist>
179  <varlistentry>
180    <term>
181      <emphasis remap='I'>w</emphasis>
182    </term>
183    <listitem>
184      <para>
185Specifies the Text widget.
186    </para>
187  </listitem>
188  </varlistentry>
189</variablelist>
190</para>
191</sect2>
192<sect2 id="Getting_Current_Text_Selection">
193<title>Getting Current Text Selection</title>
194<para>
195<!-- .LP -->
196To retrieve the text that has been selected by this
197text widget use <function>XawTextGetSelectionPos</function>:
198<!-- .IN "XawTextGetSelectionPos" "" "@DEF@" -->
199<funcsynopsis>
200<funcprototype>
201  <funcdef>void<function> XawTextGetSelectionPos</function></funcdef>
202  <paramdef>Widget<parameter> w</parameter></paramdef>
203  <paramdef>XawTextPosition*begin_return,<parameter> *end_return</parameter></paramdef>
204</funcprototype>
205</funcsynopsis>
206<!-- .FN -->
207<variablelist>
208  <varlistentry>
209    <term>
210      <emphasis remap='I'>w</emphasis>
211    </term>
212    <listitem>
213      <para>
214Specifies the Text widget.
215      </para>
216    </listitem>
217  </varlistentry>
218  <varlistentry>
219    <term>
220      <emphasis remap='I'>begin_return</emphasis>
221    </term>
222    <listitem>
223      <para>
224Returns the beginning of the text selection.
225      </para>
226    </listitem>
227  </varlistentry>
228  <varlistentry>
229    <term>
230      <emphasis remap='I'>end_return</emphasis>
231    </term>
232    <listitem>
233      <para>
234Returns the end of the text selection.
235    </para>
236  </listitem>
237  </varlistentry>
238</variablelist>
239</para>
240<para>
241<!-- .LP -->
242See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> 
243If the returned values are equal, no text is currently selected.
244</para>
245</sect2>
246<sect2 id="Replacing_Text">
247<title>Replacing Text</title>
248<para>
249<!-- .LP -->
250To modify the text in an editable Text widget use <function>XawTextReplace</function>:
251<!-- .IN "XawTextReplace" "" "@DEF@" -->
252<funcsynopsis>
253<funcprototype>
254  <funcdef>int<function> XawTextReplace</function></funcdef>
255  <paramdef>Widget<parameter> w</parameter></paramdef>
256  <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
257  <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
258</funcprototype>
259</funcsynopsis>
260<!-- .FN -->
261<variablelist>
262  <varlistentry>
263    <term>
264      <emphasis remap='I'>w</emphasis>
265    </term>
266    <listitem>
267      <para>
268Specifies the Text widget.
269      </para>
270    </listitem>
271  </varlistentry>
272  <varlistentry>
273    <term>
274      <emphasis remap='I'>start</emphasis>
275    </term>
276    <listitem>
277      <para>
278Specifies the starting character position of the text replacement.
279      </para>
280    </listitem>
281  </varlistentry>
282  <varlistentry>
283    <term>
284      <emphasis remap='I'>end</emphasis>
285    </term>
286    <listitem>
287      <para>
288Specifies the ending character position of the text replacement.
289      </para>
290    </listitem>
291  </varlistentry>
292  <varlistentry>
293    <term>
294      <emphasis remap='I'>text</emphasis>
295    </term>
296    <listitem>
297      <para>
298Specifies the text to be inserted into the file.
299    </para>
300  </listitem>
301  </varlistentry>
302</variablelist>
303</para>
304<para>
305<!-- .LP -->
306This function will not
307be able to replace text in read-only text widgets.  It will also only
308be able to append text to an append-only text widget.
309</para>
310<para>
311<!-- .LP -->
312See section 5.4 for a description of <function>XawTextPosition</function> and <!-- xref -->
313<function>XawTextBlock</function>.
314</para>
315<para>
316<!-- .LP -->
317This function may return the following values:
318<variablelist>
319  <varlistentry>
320    <term>
321      <function>XawEditDone</function>
322    </term>
323    <listitem>
324      <para>
325<!-- .IN "XawEditDone" "" -->
326The text replacement was successful.
327      </para>
328    </listitem>
329  </varlistentry>
330  <varlistentry>
331    <term>
332      <function>XawPositionError</function>
333    </term>
334    <listitem>
335      <para>
336<!-- .IN "XawPositionError" "" -->
337The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the position of
338the last character of the source.
339      </para>
340    </listitem>
341  </varlistentry>
342  <varlistentry>
343    <term>
344      <function>XawEditError</function>
345    </term>
346    <listitem>
347      <para>
348<!-- .IN "XawEditError" "" -->
349Either the Source was read-only or the range to be deleted is larger
350than the length of the Source.
351
352    </para>
353  </listitem>
354  </varlistentry>
355</variablelist>
356</para>
357<para>
358<!-- .LP -->
359The <function>XawTextReplace</function> arguments <function>start</function> and
360<emphasis remap='I'>end</emphasis> represent the text source character positions for the
361existing text that is to be replaced by the text in the text block.
362The characters from <emphasis remap='I'>start</emphasis> up to
363but not including <emphasis remap='I'>end</emphasis> are deleted, and the characters
364specified on the text block are inserted in their place.  If
365<emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and the new
366text is inserted after <emphasis remap='I'>start</emphasis>.
367</para>
368</sect2>
369<sect2 id="Searching_for_Text">
370<title>Searching for Text</title>
371<para>
372<!-- .LP -->
373To search for a string in the Text widget, use
374<function>XawTextSearch</function>:
375<!-- .IN "XawTextSearch" "" "@DEF@" -->
376<funcsynopsis>
377<funcprototype>
378  <funcdef>XawTextPosition<function> XawTextSearch</function></funcdef>
379  <paramdef>Widget<parameter> w</parameter></paramdef>
380  <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
381  <paramdef>XawTextBlock*<parameter> text</parameter></paramdef>
382</funcprototype>
383</funcsynopsis>
384<!-- .FN -->
385<variablelist>
386  <varlistentry>
387    <term>
388      <emphasis remap='I'>w</emphasis>
389    </term>
390    <listitem>
391      <para>
392Specifies the Text widget.
393      </para>
394    </listitem>
395  </varlistentry>
396  <varlistentry>
397    <term>
398      <emphasis remap='I'>dir</emphasis>
399    </term>
400    <listitem>
401      <para>
402Specifies the direction to search in.  Legal values are
403<function>XawsdLeft</function> and <function>XawsdRight</function>.
404      </para>
405    </listitem>
406  </varlistentry>
407  <varlistentry>
408    <term>
409      <emphasis remap='I'>text</emphasis>
410    </term>
411    <listitem>
412      <para>
413Specifies a text block structure that contains the text to search for.
414    </para>
415  </listitem>
416  </varlistentry>
417</variablelist>
418</para>
419<para>
420<!-- .LP -->
421See section 5.4 for a description of <function>XawTextPosition</function> and <function>XawTextBlock</function>. <!-- xref -->
422The <function>XawTextSearch</function> function will begin at the insertion point
423and search in the
424direction specified for a string that matches the one passed in
425<emphasis remap='I'>text</emphasis>.  If the string is found the location of the first
426character in the string is returned.  If the string could not be
427found then the value <function>XawTextSearchError</function> is returned.
428</para>
429</sect2>
430<sect2 id="Redisplaying_Text">
431<title>Redisplaying Text</title>
432<para>
433<!-- .LP -->
434To redisplay a range of characters, use <function>XawTextInvalidate</function>:
435<!-- .IN "XawTextInvalidate" "" "@DEF@" -->
436<funcsynopsis>
437<funcprototype>
438  <funcdef>void<function> XawTextInvalidate</function></funcdef>
439  <paramdef>Widget<parameter> w</parameter></paramdef>
440  <paramdef>XawTextPositionfrom,<parameter> to</parameter></paramdef>
441</funcprototype>
442</funcsynopsis>
443<!-- .FN -->
444<variablelist>
445  <varlistentry>
446    <term>
447      <emphasis remap='I'>w</emphasis>
448    </term>
449    <listitem>
450      <para>
451Specifies the Text widget.
452      </para>
453    </listitem>
454  </varlistentry>
455  <varlistentry>
456    <term>
457      <emphasis remap='I'>from</emphasis>
458    </term>
459    <listitem>
460      <para>
461Specifies the start of the text to redisplay.
462      </para>
463    </listitem>
464  </varlistentry>
465  <varlistentry>
466    <term>
467      <emphasis remap='I'>to</emphasis>
468    </term>
469    <listitem>
470      <para>
471Specifies the end of the text to redisplay.
472    </para>
473  </listitem>
474  </varlistentry>
475</variablelist>
476</para>
477<para>
478<!-- .LP -->
479See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
480The <function>XawTextInvalidate</function>
481function causes the specified range of characters to be redisplayed
482immediately if redisplay is enabled or the next time that redisplay is
483enabled.
484</para>
485<para>
486<!-- .LP -->
487<!-- .sp 1 -->
488To enable redisplay, use <function>XawTextEnableRedisplay</function>:
489<!-- .IN "XawTextEnableRedisplay" "" "@DEF@" -->
490<funcsynopsis>
491<funcprototype>
492  <funcdef>void<function> XawTextEnableRedisplay</function></funcdef>
493  <paramdef>Widget<parameter> w</parameter></paramdef>
494</funcprototype>
495</funcsynopsis>
496<!-- .FN -->
497<variablelist>
498  <varlistentry>
499    <term>
500      <emphasis remap='I'>w</emphasis>
501    </term>
502    <listitem>
503      <para>
504Specifies the Text widget.
505    </para>
506  </listitem>
507  </varlistentry>
508</variablelist>
509</para>
510<para>
511<!-- .LP -->
512The <function>XawTextEnableRedisplay</function> function flushes any changes due to
513batched updates when <function>XawTextDisableRedisplay</function>
514was called and allows future changes to be reflected immediately.
515</para>
516<para>
517<!-- .LP -->
518<!-- .sp 1 -->
519To disable redisplay while making several changes, use
520<function>XawTextDisableRedisplay</function>.
521<!-- .IN "XawTextDisableRedisplay" "" "@DEF@" -->
522<funcsynopsis>
523<funcprototype>
524  <funcdef>void<function> XawTextDisableRedisplay</function></funcdef>
525  <paramdef>Widget<parameter> w</parameter></paramdef>
526</funcprototype>
527</funcsynopsis>
528<!-- .FN -->
529<variablelist>
530  <varlistentry>
531    <term>
532      <emphasis remap='I'>w</emphasis>
533    </term>
534    <listitem>
535      <para>
536Specifies the Text widget.
537    </para>
538  </listitem>
539  </varlistentry>
540</variablelist>
541</para>
542<para>
543<!-- .LP -->
544The <function>XawTextDisableRedisplay</function> function causes all changes to be
545batched until either <function>XawTextDisplay</function> or <function>XawTextEnableRedisplay</function>
546is called.
547</para>
548<para>
549<!-- .LP -->
550<!-- .sp 1 -->
551To display batched updates, use <function>XawTextDisplay</function>:
552<!-- .IN "XawTextDisplay" "" "@DEF@" -->
553<funcsynopsis>
554<funcprototype>
555  <funcdef>void<function> XawTextDisplay</function></funcdef>
556  <paramdef>Widget<parameter> w</parameter></paramdef>
557</funcprototype>
558</funcsynopsis>
559<!-- .FN -->
560<variablelist>
561  <varlistentry>
562    <term>
563      <emphasis remap='I'>w</emphasis>
564    </term>
565    <listitem>
566      <para>
567Specifies the Text widget.
568    </para>
569  </listitem>
570  </varlistentry>
571</variablelist>
572</para>
573<para>
574<!-- .LP -->
575The <function>XawTextDisplay</function> function forces any accumulated updates to be
576displayed.
577</para>
578</sect2>
579<sect2 id="Resources_Convenience_Routines">
580<title>Resources Convenience Routines</title>
581<para>
582<!-- .LP -->
583To obtain the character position of the left-most character on the
584first line displayed in the widget (the value of the
585<function>displayPosition</function> resource), use <function>XawTextTopPosition</function>.
586<!-- .IN "XawTextTopPosition" "" @DEF@" -->
587<funcsynopsis>
588<funcprototype>
589  <funcdef>XawTextPosition<function> XawTextTopPosition</function></funcdef>
590  <paramdef>Widget<parameter> w</parameter></paramdef>
591</funcprototype>
592</funcsynopsis>
593<!-- .FN -->
594<variablelist>
595  <varlistentry>
596    <term>
597      <emphasis remap='I'>w</emphasis>
598    </term>
599    <listitem>
600      <para>
601Specifies the Text widget.
602    </para>
603  </listitem>
604  </varlistentry>
605</variablelist>
606</para>
607<para>
608<!-- .LP -->
609<!-- .sp 1 -->
610To assign a new selection array to a text widget use
611<function>XawTextSetSelectionArray</function>:
612<!-- .IN "XawTextSetSelectionArray" "" "@DEF@" -->
613<funcsynopsis>
614<funcprototype>
615  <funcdef>void<function> XawTextSetSelectionArray</function></funcdef>
616  <paramdef>Widget<parameter> w</parameter></paramdef>
617  <paramdef>XawTextSelectType*<parameter> sarray</parameter></paramdef>
618</funcprototype>
619</funcsynopsis>
620<!-- .FN -->
621<variablelist>
622  <varlistentry>
623    <term>
624      <emphasis remap='I'>w</emphasis>
625    </term>
626    <listitem>
627      <para>
628Specifies the Text widget.
629      </para>
630    </listitem>
631  </varlistentry>
632  <varlistentry>
633    <term>
634      <emphasis remap='I'>sarray</emphasis>
635    </term>
636    <listitem>
637      <para>
638Specifies a selection array as defined in the section called \fBText
639Selections for Application Programmers\fP.
640    </para>
641  </listitem>
642  </varlistentry>
643</variablelist>
644</para>
645<para>
646<!-- .LP -->
647Calling this function is equivalent to setting the value of the
648<function>selectionTypes</function> resource.
649</para>
650<para>
651<!-- .LP -->
652<!-- .sp 1 -->
653To move the insertion point to the specified source position, use
654<function>XawTextSetInsertionPoint</function>:
655<!-- .IN "XawTextSetInsertionPoint" "" "@DEF@" -->
656<funcsynopsis>
657<funcprototype>
658  <funcdef>void<function> XawTextSetInsertionPoint</function></funcdef>
659  <paramdef>Widget<parameter> w</parameter></paramdef>
660  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
661</funcprototype>
662</funcsynopsis>
663<!-- .FN -->
664<variablelist>
665  <varlistentry>
666    <term>
667      <emphasis remap='I'>w</emphasis>
668    </term>
669    <listitem>
670      <para>
671Specifies the Text widget.
672      </para>
673    </listitem>
674  </varlistentry>
675  <varlistentry>
676    <term>
677      <emphasis remap='I'>position</emphasis>
678    </term>
679    <listitem>
680      <para>
681Specifies the new position for the insertion point.
682    </para>
683  </listitem>
684  </varlistentry>
685</variablelist>
686</para>
687<para>
688<!-- .LP -->
689See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
690The text will be scrolled vertically if necessary to make the line
691containing the insertion point visible.  Calling this function is
692equivalent to setting the <function>insertPosition</function> resource.
693</para>
694<para>
695<!-- .LP -->
696<!-- .sp 1 -->
697To obtain the current position of the insertion point, use
698<function>XawTextGetInsertionPoint</function>:
699<!-- .IN "XawTextGetInsertionPoint" "" "@DEF@" -->
700<funcsynopsis>
701<funcprototype>
702  <funcdef>XawTextPosition<function> XawTextGetInsertionPoint</function></funcdef>
703  <paramdef>Widget<parameter> w</parameter></paramdef>
704</funcprototype>
705</funcsynopsis>
706<!-- .FN -->
707<variablelist>
708  <varlistentry>
709    <term>
710      <emphasis remap='I'>w</emphasis>
711    </term>
712    <listitem>
713      <para>
714Specifies the Text widget.
715    </para>
716  </listitem>
717  </varlistentry>
718</variablelist>
719</para>
720<para>
721<!-- .LP -->
722See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
723The result is equivalent to retrieving the value of the
724<function>insertPosition</function> resource.
725</para>
726<para>
727<!-- .LP -->
728<!-- .sp 1 -->
729To replace the text source in the specified widget, use
730<function>XawTextSetSource</function>:
731<!-- .IN "XawTextSetSource" "" "@DEF@" -->
732<funcsynopsis>
733<funcprototype>
734  <funcdef>void<function> XawTextSetSource</function></funcdef>
735  <paramdef>Widget<parameter> w</parameter></paramdef>
736  <paramdef>Widget<parameter> source</parameter></paramdef>
737  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
738</funcprototype>
739</funcsynopsis>
740<!-- .FN -->
741<variablelist>
742  <varlistentry>
743    <term>
744      <emphasis remap='I'>w</emphasis>
745    </term>
746    <listitem>
747      <para>
748Specifies the Text widget.
749      </para>
750    </listitem>
751  </varlistentry>
752  <varlistentry>
753    <term>
754      <emphasis remap='I'>source</emphasis>
755    </term>
756    <listitem>
757      <para>
758Specifies the text source object.
759      </para>
760    </listitem>
761  </varlistentry>
762  <varlistentry>
763    <term>
764      <emphasis remap='I'>position</emphasis>
765    </term>
766    <listitem>
767      <para>
768Specifies character position that will become the upper left hand corner
769of the displayed text.  This is usually set to zero.
770    </para>
771  </listitem>
772  </varlistentry>
773</variablelist>
774</para>
775<para>
776<!-- .LP -->
777See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
778A display update will be performed if redisplay is enabled.
779</para>
780<para>
781<!-- .LP -->
782<!-- .sp 1 -->
783To obtain the current text source for the specified widget, use
784<function>XawTextGetSource</function>:
785<!-- .IN "XawTextGetSource" "" "@DEF@" -->
786<funcsynopsis>
787<funcprototype>
788  <funcdef>Widget<function> XawTextGetSource</function></funcdef>
789  <paramdef>Widget<parameter> w</parameter></paramdef>
790</funcprototype>
791</funcsynopsis>
792<!-- .FN -->
793<variablelist>
794  <varlistentry>
795    <term>
796      <emphasis remap='I'>w</emphasis>
797    </term>
798    <listitem>
799      <para>
800Specifies the Text widget.
801    </para>
802  </listitem>
803  </varlistentry>
804</variablelist>
805</para>
806<para>
807<!-- .LP -->
808This function returns the text source that this Text widget is currently
809using.
810</para>
811<para>
812<!-- .LP -->
813<!-- .sp -->
814To enable and disable the insertion point, use
815<function>XawTextDisplayCaret</function>:
816<!-- .IN "XawTextDisplayCaret" "" "@DEF@" -->
817<funcsynopsis>
818<funcprototype>
819  <funcdef>void<function> XawTextDisplayCaret</function></funcdef>
820  <paramdef>Widget<parameter> w</parameter></paramdef>
821  <paramdef>Boolean<parameter> visible</parameter></paramdef>
822</funcprototype>
823</funcsynopsis>
824<!-- .FN -->
825<variablelist>
826  <varlistentry>
827    <term>
828      <emphasis remap='I'>w</emphasis>
829    </term>
830    <listitem>
831      <para>
832Specifies the Text widget.
833      </para>
834    </listitem>
835  </varlistentry>
836  <varlistentry>
837    <term>
838      <emphasis remap='I'>visible</emphasis>
839    </term>
840    <listitem>
841      <para>
842Specifies whether or not the caret should be displayed.
843    </para>
844  </listitem>
845  </varlistentry>
846</variablelist>
847</para>
848<para>
849<!-- .LP -->
850If <function>visible</function> is <function>False</function> the insertion point will be disabled.
851The marker is re-enabled either by setting <function>visible</function> to <function>True</function>, by
852calling <function>XtSetValues</function>, or by executing the <function>display-caret</function>
853action routine.
854</para>
855</sect2>
856</sect1>
857