specs/TextFuncs.xml

   1 <sect1 id="Text_Functions">
   2 <title>Text Functions</title>
   3 <!-- .XS -->
   4 <!--    Text Functions -->
   5 <!-- .XE -->
   6 <para>
   7 <!-- .LP -->
   8 The following functions are provided as convenience routines for use with
   9 the Text widget.  Although many of these actions can be performed by
  10 modifying resources, these interfaces are frequently more efficient.
  11 </para>
  12 <para>
  13 <!-- .LP -->
  14 These 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@" -->
  20 typedef long XawTextPosition;
  21 <!-- .sp -->
  22 </para>
  23 <para>
  24 <!-- .LP -->
  25 Character positions in the Text widget begin at 0 and end at n, where
  26 n 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 -->
  34 typedef 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>
  52 The first position, or index, to use within the <emphasis remap='I'>ptr</emphasis> field.
  53 The 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>
  63 The number of characters to be used from the <emphasis remap='I'>ptr</emphasis> field.
  64 The number of characters used is commonly the number of characters
  65 in <emphasis remap='I'>ptr</emphasis>, and must not be greater than the length of the string
  66 in <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>
  76 Contains 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>
  86 This flag indicates whether the data pointed to by <function>ptr</function> is char
  87 or wchar_t.  When the associated widget has <function>international</function> set
  88 to <function>false</function> this field must be XawFmt8Bit.  When the associated
  89 widget has <function>international</function> set to <function>true</function> this field must be
  90 either XawFmt8Bit or XawFmtWide.
  91     </para>
  92   </listitem>
  93   </varlistentry>
  94 </variablelist>
  95 </para>
  96 <note>
  97 <para>
  98 <!-- .LP -->
  99 Note: Previous versions of Xaw used
 100 <function>FMT8BIT ,</function>
 101 which has been retained for backwards compatibility. <function>FMT8BIT</function> is
 102 deprecated 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 -->
 109 To 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>
 127 Specifies 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>
 137 Specifies 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>
 147 Specifies the character position at which the selection ends.
 148     </para>
 149   </listitem>
 150   </varlistentry>
 151 </variablelist>
 152 </para>
 153 <para>
 154 <!-- .LP -->
 155 See section 5.4 for a description of <function>XawTextPosition</function>.  <!-- xref -->
 156 If redisplay is enabled, this function highlights the text and
 157 makes it the <function>PRIMARY</function> selection.  This function does not have any
 158 effect 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 -->
 168 To 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>
 185 Specifies 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 -->
 196 To retrieve the text that has been selected by this
 197 text 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>
 214 Specifies 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>
 224 Returns 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>
 234 Returns the end of the text selection.
 235     </para>
 236   </listitem>
 237   </varlistentry>
 238 </variablelist>
 239 </para>
 240 <para>
 241 <!-- .LP -->
 242 See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
 243 If 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 -->
 250 To 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>
 268 Specifies 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>
 278 Specifies 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>
 288 Specifies 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>
 298 Specifies the text to be inserted into the file.
 299     </para>
 300   </listitem>
 301   </varlistentry>
 302 </variablelist>
 303 </para>
 304 <para>
 305 <!-- .LP -->
 306 This function will not
 307 be able to replace text in read-only text widgets.  It will also only
 308 be able to append text to an append-only text widget.
 309 </para>
 310 <para>
 311 <!-- .LP -->
 312 See section 5.4 for a description of <function>XawTextPosition</function> and <!-- xref -->
 313 <function>XawTextBlock</function>.
 314 </para>
 315 <para>
 316 <!-- .LP -->
 317 This 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" "" -->
 326 The 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" "" -->
 337 The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the position of
 338 the 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" "" -->
 349 Either the Source was read-only or the range to be deleted is larger
 350 than the length of the Source.
 351
 352     </para>
 353   </listitem>
 354   </varlistentry>
 355 </variablelist>
 356 </para>
 357 <para>
 358 <!-- .LP -->
 359 The <function>XawTextReplace</function> arguments <function>start</function> and
 360 <emphasis remap='I'>end</emphasis> represent the text source character positions for the
 361 existing text that is to be replaced by the text in the text block.
 362 The characters from <emphasis remap='I'>start</emphasis> up to
 363 but not including <emphasis remap='I'>end</emphasis> are deleted, and the characters
 364 specified 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
 366 text 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 -->
 373 To 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>
 392 Specifies 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>
 402 Specifies 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>
 413 Specifies 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 -->
 421 See section 5.4 for a description of <function>XawTextPosition</function> and <function>XawTextBlock</function>. <!-- xref -->
 422 The <function>XawTextSearch</function> function will begin at the insertion point
 423 and search in the
 424 direction 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
 426 character in the string is returned.  If the string could not be
 427 found 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 -->
 434 To 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>
 451 Specifies 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>
 461 Specifies 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>
 471 Specifies the end of the text to redisplay.
 472     </para>
 473   </listitem>
 474   </varlistentry>
 475 </variablelist>
 476 </para>
 477 <para>
 478 <!-- .LP -->
 479 See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
 480 The <function>XawTextInvalidate</function>
 481 function causes the specified range of characters to be redisplayed
 482 immediately if redisplay is enabled or the next time that redisplay is
 483 enabled.
 484 </para>
 485 <para>
 486 <!-- .LP -->
 487 <!-- .sp 1 -->
 488 To 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>
 504 Specifies the Text widget.
 505     </para>
 506   </listitem>
 507   </varlistentry>
 508 </variablelist>
 509 </para>
 510 <para>
 511 <!-- .LP -->
 512 The <function>XawTextEnableRedisplay</function> function flushes any changes due to
 513 batched updates when <function>XawTextDisableRedisplay</function>
 514 was called and allows future changes to be reflected immediately.
 515 </para>
 516 <para>
 517 <!-- .LP -->
 518 <!-- .sp 1 -->
 519 To 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>
 536 Specifies the Text widget.
 537     </para>
 538   </listitem>
 539   </varlistentry>
 540 </variablelist>
 541 </para>
 542 <para>
 543 <!-- .LP -->
 544 The <function>XawTextDisableRedisplay</function> function causes all changes to be
 545 batched until either <function>XawTextDisplay</function> or <function>XawTextEnableRedisplay</function>
 546 is called.
 547 </para>
 548 <para>
 549 <!-- .LP -->
 550 <!-- .sp 1 -->
 551 To 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>
 567 Specifies the Text widget.
 568     </para>
 569   </listitem>
 570   </varlistentry>
 571 </variablelist>
 572 </para>
 573 <para>
 574 <!-- .LP -->
 575 The <function>XawTextDisplay</function> function forces any accumulated updates to be
 576 displayed.
 577 </para>
 578 </sect2>
 579 <sect2 id="Resources_Convenience_Routines">
 580 <title>Resources Convenience Routines</title>
 581 <para>
 582 <!-- .LP -->
 583 To obtain the character position of the left-most character on the
 584 first 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>
 601 Specifies the Text widget.
 602     </para>
 603   </listitem>
 604   </varlistentry>
 605 </variablelist>
 606 </para>
 607 <para>
 608 <!-- .LP -->
 609 <!-- .sp 1 -->
 610 To 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>
 628 Specifies 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>
 638 Specifies a selection array as defined in the section called \fBText
 639 Selections for Application Programmers\fP.
 640     </para>
 641   </listitem>
 642   </varlistentry>
 643 </variablelist>
 644 </para>
 645 <para>
 646 <!-- .LP -->
 647 Calling this function is equivalent to setting the value of the
 648 <function>selectionTypes</function> resource.
 649 </para>
 650 <para>
 651 <!-- .LP -->
 652 <!-- .sp 1 -->
 653 To 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>
 671 Specifies 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>
 681 Specifies the new position for the insertion point.
 682     </para>
 683   </listitem>
 684   </varlistentry>
 685 </variablelist>
 686 </para>
 687 <para>
 688 <!-- .LP -->
 689 See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
 690 The text will be scrolled vertically if necessary to make the line
 691 containing the insertion point visible.  Calling this function is
 692 equivalent to setting the <function>insertPosition</function> resource.
 693 </para>
 694 <para>
 695 <!-- .LP -->
 696 <!-- .sp 1 -->
 697 To 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>
 714 Specifies the Text widget.
 715     </para>
 716   </listitem>
 717   </varlistentry>
 718 </variablelist>
 719 </para>
 720 <para>
 721 <!-- .LP -->
 722 See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
 723 The result is equivalent to retrieving the value of the
 724 <function>insertPosition</function> resource.
 725 </para>
 726 <para>
 727 <!-- .LP -->
 728 <!-- .sp 1 -->
 729 To 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>
 748 Specifies 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>
 758 Specifies 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>
 768 Specifies character position that will become the upper left hand corner
 769 of the displayed text.  This is usually set to zero.
 770     </para>
 771   </listitem>
 772   </varlistentry>
 773 </variablelist>
 774 </para>
 775 <para>
 776 <!-- .LP -->
 777 See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref -->
 778 A display update will be performed if redisplay is enabled.
 779 </para>
 780 <para>
 781 <!-- .LP -->
 782 <!-- .sp 1 -->
 783 To 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>
 800 Specifies the Text widget.
 801     </para>
 802   </listitem>
 803   </varlistentry>
 804 </variablelist>
 805 </para>
 806 <para>
 807 <!-- .LP -->
 808 This function returns the text source that this Text widget is currently
 809 using.
 810 </para>
 811 <para>
 812 <!-- .LP -->
 813 <!-- .sp -->
 814 To 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>
 832 Specifies 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>
 842 Specifies whether or not the caret should be displayed.
 843     </para>
 844   </listitem>
 845   </varlistentry>
 846 </variablelist>
 847 </para>
 848 <para>
 849 <!-- .LP -->
 850 If <function>visible</function> is <function>False</function> the insertion point will be disabled.
 851 The marker is re-enabled either by setting <function>visible</function> to <function>True</function>, by
 852 calling <function>XtSetValues</function>, or by executing the <function>display-caret</function>
 853 action routine.
 854 </para>
 855 </sect2>
 856 </sect1>