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<indexterm significance="preferred"><primary>XawTextPosition</primary></indexterm>
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<indexterm significance="preferred"><primary>XawTextBlock</primary></indexterm>
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<indexterm><primary>XawTextBlockPtr</primary></indexterm>
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<indexterm significance="preferred"><primary>XawTextSetSelection</primary></indexterm>
112<funcsynopsis id='XawTextSetSelection'>
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 -->
155<link linkend="Text_Functions">See section 5.4</link>
156for a description of <function>XawTextPosition</function>.
157If redisplay is enabled, this function highlights the text and
158makes it the <function>PRIMARY</function> selection.  This function does not have any
159effect on <function>CUT_BUFFER0</function>.
160</para>
161<para>
162<!-- .LP -->
163</para>
164</sect2>
165<sect2 id="Unhighlighting_Text">
166<title>Unhighlighting Text</title>
167<para>
168<!-- .LP -->
169To unhighlight previously highlighted text in a widget, use
170<xref linkend='XawTextUnsetSelection' xrefstyle='select: title'/>:
171<indexterm significance="preferred"><primary>XawTextUnsetSelection</primary></indexterm>
172<funcsynopsis id='XawTextUnsetSelection'>
173<funcprototype>
174  <funcdef>void<function> XawTextUnsetSelection</function></funcdef>
175  <paramdef>Widget<parameter> w</parameter></paramdef>
176</funcprototype>
177</funcsynopsis>
178<!-- .FN -->
179<variablelist>
180  <varlistentry>
181    <term>
182      <emphasis remap='I'>w</emphasis>
183    </term>
184    <listitem>
185      <para>
186Specifies the Text widget.
187    </para>
188  </listitem>
189  </varlistentry>
190</variablelist>
191</para>
192</sect2>
193<sect2 id="Getting_Current_Text_Selection">
194<title>Getting Current Text Selection</title>
195<para>
196<!-- .LP -->
197To retrieve the text that has been selected by this
198text widget use <xref linkend='XawTextGetSelectionPos' xrefstyle='select: title'/>:
199<indexterm significance="preferred"><primary>XawTextGetSelectionPos</primary></indexterm>
200<funcsynopsis id='XawTextGetSelectionPos'>
201<funcprototype>
202  <funcdef>void<function> XawTextGetSelectionPos</function></funcdef>
203  <paramdef>Widget<parameter> w</parameter></paramdef>
204  <paramdef>XawTextPosition*begin_return,<parameter> *end_return</parameter></paramdef>
205</funcprototype>
206</funcsynopsis>
207<!-- .FN -->
208<variablelist>
209  <varlistentry>
210    <term>
211      <emphasis remap='I'>w</emphasis>
212    </term>
213    <listitem>
214      <para>
215Specifies the Text widget.
216      </para>
217    </listitem>
218  </varlistentry>
219  <varlistentry>
220    <term>
221      <emphasis remap='I'>begin_return</emphasis>
222    </term>
223    <listitem>
224      <para>
225Returns the beginning of the text selection.
226      </para>
227    </listitem>
228  </varlistentry>
229  <varlistentry>
230    <term>
231      <emphasis remap='I'>end_return</emphasis>
232    </term>
233    <listitem>
234      <para>
235Returns the end of the text selection.
236    </para>
237  </listitem>
238  </varlistentry>
239</variablelist>
240</para>
241<para>
242<!-- .LP -->
243<link linkend="Text_Functions">See section 5.4</link>
244for a description of <function>XawTextPosition</function>.
245If the returned values are equal, no text is currently selected.
246</para>
247</sect2>
248<sect2 id="Replacing_Text">
249<title>Replacing Text</title>
250<para>
251<!-- .LP -->
252To modify the text in an editable Text widget use <xref linkend='XawTextReplace' xrefstyle='select: title'/>:
253<indexterm significance="preferred"><primary>XawTextReplace</primary></indexterm>
254<funcsynopsis id='XawTextReplace'>
255<funcprototype>
256  <funcdef>int<function> XawTextReplace</function></funcdef>
257  <paramdef>Widget<parameter> w</parameter></paramdef>
258  <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef>
259  <paramdef>XawTextBlock<parameter> *text</parameter></paramdef>
260</funcprototype>
261</funcsynopsis>
262<!-- .FN -->
263<variablelist>
264  <varlistentry>
265    <term>
266      <emphasis remap='I'>w</emphasis>
267    </term>
268    <listitem>
269      <para>
270Specifies the Text widget.
271      </para>
272    </listitem>
273  </varlistentry>
274  <varlistentry>
275    <term>
276      <emphasis remap='I'>start</emphasis>
277    </term>
278    <listitem>
279      <para>
280Specifies the starting character position of the text replacement.
281      </para>
282    </listitem>
283  </varlistentry>
284  <varlistentry>
285    <term>
286      <emphasis remap='I'>end</emphasis>
287    </term>
288    <listitem>
289      <para>
290Specifies the ending character position of the text replacement.
291      </para>
292    </listitem>
293  </varlistentry>
294  <varlistentry>
295    <term>
296      <emphasis remap='I'>text</emphasis>
297    </term>
298    <listitem>
299      <para>
300Specifies the text to be inserted into the file.
301    </para>
302  </listitem>
303  </varlistentry>
304</variablelist>
305</para>
306<para>
307<!-- .LP -->
308This function will not
309be able to replace text in read-only text widgets.  It will also only
310be able to append text to an append-only text widget.
311</para>
312<para>
313<!-- .LP -->
314<link linkend="Text_Functions">See section 5.4</link>
315for a description of <function>XawTextPosition</function> and
316<function>XawTextBlock</function>.
317</para>
318<para>
319<!-- .LP -->
320This function may return the following values:
321<variablelist>
322  <varlistentry>
323    <term>
324      <function>XawEditDone</function>
325    </term>
326    <listitem>
327      <para>
328<indexterm><primary>XawEditDone</primary></indexterm>
329The text replacement was successful.
330      </para>
331    </listitem>
332  </varlistentry>
333  <varlistentry>
334    <term>
335      <function>XawPositionError</function>
336    </term>
337    <listitem>
338      <para>
339<indexterm><primary>XawPositionError</primary></indexterm>
340The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the position of
341the last character of the source.
342      </para>
343    </listitem>
344  </varlistentry>
345  <varlistentry>
346    <term>
347      <function>XawEditError</function>
348    </term>
349    <listitem>
350      <para>
351<indexterm><primary>XawEditError</primary></indexterm>
352Either the Source was read-only or the range to be deleted is larger
353than the length of the Source.
354
355    </para>
356  </listitem>
357  </varlistentry>
358</variablelist>
359</para>
360<para>
361<!-- .LP -->
362The <xref linkend='XawTextReplace' xrefstyle='select: title'/> arguments <function>start</function> and
363<emphasis remap='I'>end</emphasis> represent the text source character positions for the
364existing text that is to be replaced by the text in the text block.
365The characters from <emphasis remap='I'>start</emphasis> up to
366but not including <emphasis remap='I'>end</emphasis> are deleted, and the characters
367specified on the text block are inserted in their place.  If
368<emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and the new
369text is inserted after <emphasis remap='I'>start</emphasis>.
370</para>
371</sect2>
372<sect2 id="Searching_for_Text">
373<title>Searching for Text</title>
374<para>
375<!-- .LP -->
376To search for a string in the Text widget, use
377<xref linkend='XawTextSearch' xrefstyle='select: title'/>:
378<indexterm significance="preferred"><primary>XawTextSearch</primary></indexterm>
379<funcsynopsis id='XawTextSearch'>
380<funcprototype>
381  <funcdef>XawTextPosition<function> XawTextSearch</function></funcdef>
382  <paramdef>Widget<parameter> w</parameter></paramdef>
383  <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef>
384  <paramdef>XawTextBlock*<parameter> text</parameter></paramdef>
385</funcprototype>
386</funcsynopsis>
387<!-- .FN -->
388<variablelist>
389  <varlistentry>
390    <term>
391      <emphasis remap='I'>w</emphasis>
392    </term>
393    <listitem>
394      <para>
395Specifies the Text widget.
396      </para>
397    </listitem>
398  </varlistentry>
399  <varlistentry>
400    <term>
401      <emphasis remap='I'>dir</emphasis>
402    </term>
403    <listitem>
404      <para>
405Specifies the direction to search in.  Legal values are
406<function>XawsdLeft</function> and <function>XawsdRight</function>.
407      </para>
408    </listitem>
409  </varlistentry>
410  <varlistentry>
411    <term>
412      <emphasis remap='I'>text</emphasis>
413    </term>
414    <listitem>
415      <para>
416Specifies a text block structure that contains the text to search for.
417    </para>
418  </listitem>
419  </varlistentry>
420</variablelist>
421</para>
422<para>
423<!-- .LP -->
424<link linkend="Text_Functions">See section 5.4</link> for a description of
425<function>XawTextPosition</function> and <function>XawTextBlock</function>.
426The <xref linkend='XawTextSearch' xrefstyle='select: title'/> function will begin at the insertion point
427and search in the
428direction specified for a string that matches the one passed in
429<emphasis remap='I'>text</emphasis>.  If the string is found the location of the first
430character in the string is returned.  If the string could not be
431found then the value <function>XawTextSearchError</function> is returned.
432</para>
433</sect2>
434<sect2 id="Redisplaying_Text">
435<title>Redisplaying Text</title>
436<para>
437<!-- .LP -->
438To redisplay a range of characters, use <xref linkend='XawTextInvalidate' xrefstyle='select: title'/>:
439<indexterm significance="preferred"><primary>XawTextInvalidate</primary></indexterm>
440<funcsynopsis id='XawTextInvalidate'>
441<funcprototype>
442  <funcdef>void<function> XawTextInvalidate</function></funcdef>
443  <paramdef>Widget<parameter> w</parameter></paramdef>
444  <paramdef>XawTextPositionfrom,<parameter> to</parameter></paramdef>
445</funcprototype>
446</funcsynopsis>
447<!-- .FN -->
448<variablelist>
449  <varlistentry>
450    <term>
451      <emphasis remap='I'>w</emphasis>
452    </term>
453    <listitem>
454      <para>
455Specifies the Text widget.
456      </para>
457    </listitem>
458  </varlistentry>
459  <varlistentry>
460    <term>
461      <emphasis remap='I'>from</emphasis>
462    </term>
463    <listitem>
464      <para>
465Specifies the start of the text to redisplay.
466      </para>
467    </listitem>
468  </varlistentry>
469  <varlistentry>
470    <term>
471      <emphasis remap='I'>to</emphasis>
472    </term>
473    <listitem>
474      <para>
475Specifies the end of the text to redisplay.
476    </para>
477  </listitem>
478  </varlistentry>
479</variablelist>
480</para>
481<para>
482<!-- .LP -->
483<link linkend="Text_Functions">See section 5.4</link>
484for a description of <function>XawTextPosition</function>.
485The <xref linkend='XawTextInvalidate' xrefstyle='select: title'/>
486function causes the specified range of characters to be redisplayed
487immediately if redisplay is enabled or the next time that redisplay is
488enabled.
489</para>
490<para>
491<!-- .LP -->
492<!-- .sp 1 -->
493To enable redisplay, use <xref linkend='XawTextEnableRedisplay' xrefstyle='select: title'/>:
494<indexterm significance="preferred"><primary>XawTextEnableRedisplay</primary></indexterm>
495<funcsynopsis id='XawTextEnableRedisplay'>
496<funcprototype>
497  <funcdef>void<function> XawTextEnableRedisplay</function></funcdef>
498  <paramdef>Widget<parameter> w</parameter></paramdef>
499</funcprototype>
500</funcsynopsis>
501<!-- .FN -->
502<variablelist>
503  <varlistentry>
504    <term>
505      <emphasis remap='I'>w</emphasis>
506    </term>
507    <listitem>
508      <para>
509Specifies the Text widget.
510    </para>
511  </listitem>
512  </varlistentry>
513</variablelist>
514</para>
515<para>
516<!-- .LP -->
517The <xref linkend='XawTextEnableRedisplay' xrefstyle='select: title'/> function flushes any changes due to
518batched updates when <xref linkend='XawTextDisableRedisplay' xrefstyle='select: title'/>
519was called and allows future changes to be reflected immediately.
520</para>
521<para>
522<!-- .LP -->
523<!-- .sp 1 -->
524To disable redisplay while making several changes, use
525<xref linkend='XawTextDisableRedisplay' xrefstyle='select: title'/>.
526<indexterm significance="preferred"><primary>XawTextDisableRedisplay</primary></indexterm>
527<funcsynopsis id='XawTextDisableRedisplay'>
528<funcprototype>
529  <funcdef>void<function> XawTextDisableRedisplay</function></funcdef>
530  <paramdef>Widget<parameter> w</parameter></paramdef>
531</funcprototype>
532</funcsynopsis>
533<!-- .FN -->
534<variablelist>
535  <varlistentry>
536    <term>
537      <emphasis remap='I'>w</emphasis>
538    </term>
539    <listitem>
540      <para>
541Specifies the Text widget.
542    </para>
543  </listitem>
544  </varlistentry>
545</variablelist>
546</para>
547<para>
548<!-- .LP -->
549The <xref linkend='XawTextDisableRedisplay' xrefstyle='select: title'/> function causes all changes to be
550batched until either <xref linkend='XawTextDisplay' xrefstyle='select: title'/> or <xref linkend='XawTextEnableRedisplay' xrefstyle='select: title'/>
551is called.
552</para>
553<para>
554<!-- .LP -->
555<!-- .sp 1 -->
556To display batched updates, use <xref linkend='XawTextDisplay' xrefstyle='select: title'/>:
557<indexterm significance="preferred"><primary>XawTextDisplay</primary></indexterm>
558<funcsynopsis id='XawTextDisplay'>
559<funcprototype>
560  <funcdef>void<function> XawTextDisplay</function></funcdef>
561  <paramdef>Widget<parameter> w</parameter></paramdef>
562</funcprototype>
563</funcsynopsis>
564<!-- .FN -->
565<variablelist>
566  <varlistentry>
567    <term>
568      <emphasis remap='I'>w</emphasis>
569    </term>
570    <listitem>
571      <para>
572Specifies the Text widget.
573    </para>
574  </listitem>
575  </varlistentry>
576</variablelist>
577</para>
578<para>
579<!-- .LP -->
580The <xref linkend='XawTextDisplay' xrefstyle='select: title'/> function forces any accumulated updates to be
581displayed.
582</para>
583</sect2>
584<sect2 id="Resources_Convenience_Routines">
585<title>Resources Convenience Routines</title>
586<para>
587<!-- .LP -->
588To obtain the character position of the left-most character on the
589first line displayed in the widget (the value of the
590<function>displayPosition</function> resource), use <xref linkend='XawTextTopPosition' xrefstyle='select: title'/>.
591<indexterm significance="preferred"><primary>XawTextTopPosition</primary></indexterm>
592<funcsynopsis id='XawTextTopPosition'>
593<funcprototype>
594  <funcdef>XawTextPosition<function> XawTextTopPosition</function></funcdef>
595  <paramdef>Widget<parameter> w</parameter></paramdef>
596</funcprototype>
597</funcsynopsis>
598<!-- .FN -->
599<variablelist>
600  <varlistentry>
601    <term>
602      <emphasis remap='I'>w</emphasis>
603    </term>
604    <listitem>
605      <para>
606Specifies the Text widget.
607    </para>
608  </listitem>
609  </varlistentry>
610</variablelist>
611</para>
612<para>
613<!-- .LP -->
614<!-- .sp 1 -->
615To assign a new selection array to a text widget use
616<xref linkend='XawTextSetSelectionArray' xrefstyle='select: title'/>:
617<indexterm significance="preferred"><primary>XawTextSetSelectionArray</primary></indexterm>
618<funcsynopsis id='XawTextSetSelectionArray'>
619<funcprototype>
620  <funcdef>void<function> XawTextSetSelectionArray</function></funcdef>
621  <paramdef>Widget<parameter> w</parameter></paramdef>
622  <paramdef>XawTextSelectType*<parameter> sarray</parameter></paramdef>
623</funcprototype>
624</funcsynopsis>
625<!-- .FN -->
626<variablelist>
627  <varlistentry>
628    <term>
629      <emphasis remap='I'>w</emphasis>
630    </term>
631    <listitem>
632      <para>
633Specifies the Text widget.
634      </para>
635    </listitem>
636  </varlistentry>
637  <varlistentry>
638    <term>
639      <emphasis remap='I'>sarray</emphasis>
640    </term>
641    <listitem>
642      <para>
643Specifies a selection array as defined in
644<xref linkend="Text_Selections_for_Application_Programmers"/>.
645    </para>
646  </listitem>
647  </varlistentry>
648</variablelist>
649</para>
650<para>
651<!-- .LP -->
652Calling this function is equivalent to setting the value of the
653<function>selectionTypes</function> resource.
654</para>
655<para>
656<!-- .LP -->
657<!-- .sp 1 -->
658To move the insertion point to the specified source position, use
659<xref linkend='XawTextSetInsertionPoint' xrefstyle='select: title'/>:
660<indexterm significance="preferred"><primary>XawTextSetInsertionPoint</primary></indexterm>
661<funcsynopsis id='XawTextSetInsertionPoint'>
662<funcprototype>
663  <funcdef>void<function> XawTextSetInsertionPoint</function></funcdef>
664  <paramdef>Widget<parameter> w</parameter></paramdef>
665  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
666</funcprototype>
667</funcsynopsis>
668<!-- .FN -->
669<variablelist>
670  <varlistentry>
671    <term>
672      <emphasis remap='I'>w</emphasis>
673    </term>
674    <listitem>
675      <para>
676Specifies the Text widget.
677      </para>
678    </listitem>
679  </varlistentry>
680  <varlistentry>
681    <term>
682      <emphasis remap='I'>position</emphasis>
683    </term>
684    <listitem>
685      <para>
686Specifies the new position for the insertion point.
687    </para>
688  </listitem>
689  </varlistentry>
690</variablelist>
691</para>
692<para>
693<!-- .LP -->
694<link linkend="Text_Functions">See section 5.4</link>
695for a description of <function>XawTextPosition</function>.
696The text will be scrolled vertically if necessary to make the line
697containing the insertion point visible.  Calling this function is
698equivalent to setting the <function>insertPosition</function> resource.
699</para>
700<para>
701<!-- .LP -->
702<!-- .sp 1 -->
703To obtain the current position of the insertion point, use
704<xref linkend='XawTextGetInsertionPoint' xrefstyle='select: title'/>:
705<indexterm significance="preferred"><primary>XawTextGetInsertionPoint</primary></indexterm>
706<funcsynopsis id='XawTextGetInsertionPoint'>
707<funcprototype>
708  <funcdef>XawTextPosition<function> XawTextGetInsertionPoint</function></funcdef>
709  <paramdef>Widget<parameter> w</parameter></paramdef>
710</funcprototype>
711</funcsynopsis>
712<!-- .FN -->
713<variablelist>
714  <varlistentry>
715    <term>
716      <emphasis remap='I'>w</emphasis>
717    </term>
718    <listitem>
719      <para>
720Specifies the Text widget.
721    </para>
722  </listitem>
723  </varlistentry>
724</variablelist>
725</para>
726<para>
727<!-- .LP -->
728<link linkend="Text_Functions">See section 5.4</link>
729for a description of <function>XawTextPosition</function>.
730The result is equivalent to retrieving the value of the
731<function>insertPosition</function> resource.
732</para>
733<para>
734<!-- .LP -->
735<!-- .sp 1 -->
736To replace the text source in the specified widget, use
737<xref linkend='XawTextSetSource' xrefstyle='select: title'/>:
738<indexterm significance="preferred"><primary>XawTextSetSource</primary></indexterm>
739<funcsynopsis id='XawTextSetSource'>
740<funcprototype>
741  <funcdef>void<function> XawTextSetSource</function></funcdef>
742  <paramdef>Widget<parameter> w</parameter></paramdef>
743  <paramdef>Widget<parameter> source</parameter></paramdef>
744  <paramdef>XawTextPosition<parameter> position</parameter></paramdef>
745</funcprototype>
746</funcsynopsis>
747<!-- .FN -->
748<variablelist>
749  <varlistentry>
750    <term>
751      <emphasis remap='I'>w</emphasis>
752    </term>
753    <listitem>
754      <para>
755Specifies the Text widget.
756      </para>
757    </listitem>
758  </varlistentry>
759  <varlistentry>
760    <term>
761      <emphasis remap='I'>source</emphasis>
762    </term>
763    <listitem>
764      <para>
765Specifies the text source object.
766      </para>
767    </listitem>
768  </varlistentry>
769  <varlistentry>
770    <term>
771      <emphasis remap='I'>position</emphasis>
772    </term>
773    <listitem>
774      <para>
775Specifies character position that will become the upper left hand corner
776of the displayed text.  This is usually set to zero.
777    </para>
778  </listitem>
779  </varlistentry>
780</variablelist>
781</para>
782<para>
783<!-- .LP -->
784<link linkend="Text_Functions">See section 5.4</link>
785for a description of <function>XawTextPosition</function>.
786A display update will be performed if redisplay is enabled.
787</para>
788<para>
789<!-- .LP -->
790<!-- .sp 1 -->
791To obtain the current text source for the specified widget, use
792<xref linkend='XawTextGetSource' xrefstyle='select: title'/>:
793<indexterm significance="preferred"><primary>XawTextGetSource</primary></indexterm>
794<funcsynopsis id='XawTextGetSource'>
795<funcprototype>
796  <funcdef>Widget<function> XawTextGetSource</function></funcdef>
797  <paramdef>Widget<parameter> w</parameter></paramdef>
798</funcprototype>
799</funcsynopsis>
800<!-- .FN -->
801<variablelist>
802  <varlistentry>
803    <term>
804      <emphasis remap='I'>w</emphasis>
805    </term>
806    <listitem>
807      <para>
808Specifies the Text widget.
809    </para>
810  </listitem>
811  </varlistentry>
812</variablelist>
813</para>
814<para>
815<!-- .LP -->
816This function returns the text source that this Text widget is currently
817using.
818</para>
819<para>
820<!-- .LP -->
821<!-- .sp -->
822To enable and disable the insertion point, use
823<xref linkend='XawTextDisplayCaret' xrefstyle='select: title'/>:
824<indexterm significance="preferred"><primary>XawTextDisplayCaret</primary></indexterm>
825<funcsynopsis id='XawTextDisplayCaret'>
826<funcprototype>
827  <funcdef>void<function> XawTextDisplayCaret</function></funcdef>
828  <paramdef>Widget<parameter> w</parameter></paramdef>
829  <paramdef>Boolean<parameter> visible</parameter></paramdef>
830</funcprototype>
831</funcsynopsis>
832<!-- .FN -->
833<variablelist>
834  <varlistentry>
835    <term>
836      <emphasis remap='I'>w</emphasis>
837    </term>
838    <listitem>
839      <para>
840Specifies the Text widget.
841      </para>
842    </listitem>
843  </varlistentry>
844  <varlistentry>
845    <term>
846      <emphasis remap='I'>visible</emphasis>
847    </term>
848    <listitem>
849      <para>
850Specifies whether or not the caret should be displayed.
851    </para>
852  </listitem>
853  </varlistentry>
854</variablelist>
855</para>
856<para>
857<!-- .LP -->
858If <function>visible</function> is <function>False</function> the insertion point will be disabled.
859The marker is re-enabled either by setting <function>visible</function> to <function>True</function>, by
860calling <xref linkend='XtSetValues' xrefstyle='select: title'/>, or by executing the <function>display-caret</function>
861action routine.
862</para>
863</sect2>
864</sect1>
865