1<chapter id='Text_Widgets'> 2<title>Text Widgets</title> 3 4<para> 5The Text widget provides a window that will allow an application 6to display and edit one or more lines of text. Options are provided to 7allow the user to add Scrollbars to its window, search for a specific 8string, and modify the text in the buffer. 9</para> 10<para> 11The Text widget is made up of a number of pieces; it was modularized to 12ease customization. The AsciiText widget class (actually not limited to 13ASCII but so named for compatibility) is be general enough to most 14needs. If more flexibility, special features, or extra functionality is 15needed, they can be added by implementing a new TextSource or TextSink, or 16by subclassing the Text Widget 17(<link linkend='Customizing_the_Text_Widget'>See Section 5.8</link> 18for customization details.) 19</para> 20<para> 21The words <emphasis remap='I'>insertion point</emphasis> are used in this chapter to refer to the text 22caret. This is the symbol that is displayed between two characters in 23the file. The insertion point marks the location where any new characters 24will be added to the file. To avoid confusion the pointer cursor will 25always be referred to as the <emphasis remap='I'>pointer</emphasis>. 26</para> 27<para> 28The text widget supports three edit modes, controlling the types of 29modifications a user is allowed to make: 30</para> 31<para> 32<itemizedlist> 33 <listitem><para>Append-only</para></listitem> 34 <listitem><para>Editable</para></listitem> 35 <listitem><para>Read-only</para></listitem> 36</itemizedlist> 37</para> 38<para> 39Read-only mode does not allow the user or the programmer to modify the text 40in the widget. While the entire string may be reset in 41read-only mode with <xref linkend='XtSetValues' xrefstyle='select: title'/>, it cannot be modified via 42with <xref linkend='XawTextReplace' xrefstyle='select: title'/>. Append-only and editable modes allow 43the text at the insertion point to be modified. The only difference is 44that text may only be added to or removed from the end of a buffer in 45append-only mode. 46</para> 47<sect1 id="Text_Widget_for_Users"> 48<title>Text Widget for Users</title> 49<indexterm><primary>Text widget</primary><secondary>User's Guide to the Text widget</secondary></indexterm> 50<!-- .XS --> 51<!-- Text Widget for Users --> 52<!-- .XE --> 53<para> 54<!-- .LP --> 55The Text widget provides many of the common keyboard editing commands. 56These commands allow users to move around and edit the buffer. If an 57illegal operation is attempted, (such as deleting characters in a 58read-only text widget), the X server will beep. 59</para> 60<sect2 id="Default_Key_Bindings"> 61<title>Default Key Bindings</title> 62<indexterm><primary>Text widget</primary><secondary>default key bindings</secondary></indexterm> 63<para> 64<!-- .LP --> 65The default key bindings are patterned after those in the EMACS text editor: 66<!-- .sp --> 67<literallayout class="monospaced"> 68<!-- .TA 1.0i 3.0i 4.5i --> 69<!-- .ta 1.0i 3.0i 4.5i --> 70Ctrl-a Beginning Of Line Meta-b Backward Word 71Ctrl-b Backward Character Meta-f Forward Word 72Ctrl-d Delete Next Character Meta-i Insert File 73Ctrl-e End Of Line Meta-k Kill To End Of Paragraph 74Ctrl-f Forward Character Meta-q Form Paragraph 75Ctrl-g Multiply Reset Meta-v Previous Page 76Ctrl-h Delete Previous Character Meta-y Insert Current Selection 77Ctrl-j Newline And Indent Meta-z Scroll One Line Down 78Ctrl-k Kill To End Of Line Meta-d Delete Next Word 79Ctrl-l Redraw Display Meta-D Kill Word 80Ctrl-m Newline Meta-h Delete Previous Word 81Ctrl-n Next Line Meta-H Backward Kill Word 82Ctrl-o Newline And Backup Meta-< Beginning Of File 83Ctrl-p Previous Line Meta-> End Of File 84Ctrl-r Search/Replace Backward Meta-] Forward Paragraph 85Ctrl-s Search/Replace Forward Meta-[ Backward Paragraph 86Ctrl-t Transpose Characters 87Ctrl-u Multiply by 4 Meta-Delete Delete Previous Word 88Ctrl-v Next Page Meta-Shift Delete Kill Previous Word 89Ctrl-w Kill Selection Meta-Backspace Delete Previous Word 90Ctrl-y Unkill Meta-Shift Backspace Kill Previous Word 91Ctrl-z Scroll One Line Up 92Ctrl-\\ Reconnect to input method 93Kanji Reconnect to input method 94</literallayout> 95<!-- .sp --> 96</para> 97<para> 98<!-- .LP --> 99In addition, the pointer may be used to cut and paste text: 100</para> 101<para> 102<!-- .LP --> 103<literallayout class="monospaced"> 104<!-- .TA .5i 2.0i --> 105<!-- .ta .5i 2.0i --> 106 Button 1 Down Start Selection 107 Button 1 Motion Adjust Selection 108 Button 1 Up End Selection (cut) 109 110 Button 2 Down Insert Current Selection (paste) 111 112 Button 3 Down Extend Current Selection 113 Button 3 Motion Adjust Selection 114 Button 3 Up End Selection (cut) 115 116</literallayout> 117</para> 118<para> 119<!-- .LP --> 120Since all of these key and pointer bindings are set through the 121translations and resource manager, the user and the application 122programmer can modify them by changing the Text widget's 123<function>translations</function> resource. 124<!-- .\" --> 125</para> 126</sect2> 127<sect2 id="Search_and_Replace"> 128<title>Search and Replace</title> 129<indexterm><primary>Text widget</primary><secondary>search</secondary></indexterm> 130<indexterm><primary>Text widget</primary><secondary>query replace</secondary></indexterm> 131<para> 132<!-- .LP --> 133The Text widget provides a search popup that can be used to search for a 134string within the current Text widget. The popup can be activated by 135typing either <emphasis remap='I'>Control-r</emphasis> or <emphasis remap='I'>Control-s</emphasis>. If <emphasis remap='I'>Control-s</emphasis> is 136used the search will be forward in the file from the current location of the 137insertion point; if <emphasis remap='I'>Control-r</emphasis> is used the search will be backward. The 138activated popup is placed under the pointer. It has a number of buttons 139that allow both text searches and text replacements to be performed. 140</para> 141<para> 142<!-- .LP --> 143At the top of the search popup are two toggle buttons labeled 144<emphasis remap='I'>backward</emphasis> and <emphasis remap='I'>forward</emphasis>. One of these buttons will always be 145highlighted; this is the direction in which the search will be 146performed. The user can change the direction at any time by clicking on 147the appropriate button. 148</para> 149<para> 150<!-- .LP --> 151Directly under the buttons there are two text areas, one labeled 152<emphasis remap='I'>Search for:</emphasis> and the other labeled <emphasis remap='I'>Replace with:</emphasis>. If this is 153a read-only Text widget the <emphasis remap='I'>Replace with:</emphasis> field will be insensitive 154and no replacements will be allowed. After each of these labels will be 155a text field. This field will allow the user to enter a string to 156search for and the string to replace it with. Only one of these text 157fields will have a window border around it; this is the active text 158field. Any key presses that occur when the focus in in the search popup 159will be directed to the active text field. There are also a few special 160key sequences: 161<literallayout class="monospaced"> 162<!-- .TA 1.75i --> 163<!-- .ta 1.75i --> 164<function>Carriage Return</function>: Execute the action, and pop down the search widget. 165<function>Tab</function>: Execute the action, then move to the next field. 166<function>Shift Carriage Return</function>: Execute the action, then move to the next field. 167<function>Control-q Tab</function>: Enter a Tab into a text field. 168<function>Control-c</function>: Pop down the search popup. 169</literallayout> 170</para> 171<para> 172<!-- .LP --> 173Using these special key sequences should allow simple 174searches without ever removing one's hands from the keyboard. 175</para> 176<para> 177<!-- .LP --> 178Near the bottom of the search popup is a row of buttons. These buttons 179allow the same actions to to be performed as the key sequences, but the 180buttons will leave the popup active. This can be quite useful if many 181searches are being performed, as the popup will be left on the display. 182Since the search popup is a transient window, it may be picked 183up with the window manager and pulled off to the side for use 184at a later time. 185</para> 186<variablelist> 187 <varlistentry> 188 <term>Search</term> 189 <listitem> 190 <para> 191Search for the specified string. 192 </para> 193 </listitem> 194 </varlistentry> 195 <varlistentry> 196 <term>Replace</term> 197 <listitem> 198 <para> 199Replace the currently highlighted string with the string in the 200<emphasis remap='I'>Replace with</emphasis> text field, and move onto the next occurrence of the 201<emphasis remap='I'>Search for</emphasis> text field. The functionality is commonly referred to as 202query-replace. 203 </para> 204 </listitem> 205 </varlistentry> 206 <varlistentry> 207 <term>ReplaceAll</term> 208 <listitem> 209 <para> 210Replace all occurrences of the search string with the replace string from 211the current insertion point position to the end (or beginning) of the 212file. There is no key sequence to perform this action. 213 </para> 214 </listitem> 215 </varlistentry> 216 <varlistentry> 217 <term>ReplaceAll</term> 218 <listitem> 219 <para> 220Remove the search popup from the screen. 221 </para> 222 </listitem> 223 </varlistentry> 224</variablelist> 225<para> 226<!-- .LP --> 227Finally, when <function>international</function> resource is <function>true</function>, there may be a 228pre-edit buffer below the button row, for composing input. Its presence 229is determined by the X locale in use and the VendorShell's <function>preeditType</function> 230resource. 231</para> 232<para> 233<!-- .LP --> 234The widget hierarchy for the search popup is show below, all widgets 235are listed by class and instance name. 236<!-- .sp --> 237<!-- .nf --> 238<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i --> 239<literallayout class="monospaced"> 240Text <name of Text widget> 241 TransientShell search 242 Form form 243 Label label1 244 Label label2 245 Toggle backwards 246 Toggle forwards 247 Label searchLabel 248 Text searchText 249 Label replaceLabel 250 Text replaceText 251 Command search 252 Command replaceOne 253 Command replaceAll 254 Command cancel 255</literallayout> 256<!-- .fi --> 257</para> 258</sect2> 259<sect2 id="File_Insertion"> 260<title>File Insertion</title> 261<para> 262<!-- .LP --> 263<indexterm><primary>Text widget</primary><secondary>file insertion</secondary></indexterm> 264To insert a file into a text widget, type the key sequence <emphasis remap='I'>Meta-i</emphasis>, 265which will activate the file insert popup. This popup will appear under 266the pointer, and any text typed while the focus is in this popup will be 267redirected to the text field used for the filename. When the desired 268filename has been entered, click on <emphasis remap='I'>Insert File</emphasis>, or type 269<emphasis remap='I'>Carriage Return</emphasis>. The named file will then be inserted in the text 270widget beginning at the insertion point position. If an error occurs when 271opening the file, an error message will be printed, prompting the user 272to enter the filename again. The file insert may be aborted by clicking 273on <emphasis remap='I'>Cancel</emphasis>. If <emphasis remap='I'>Meta-i</emphasis> is typed at a text widget that is 274read-only, it will beep, as no file insertion is allowed. 275</para> 276<para> 277<!-- .LP --> 278The widget hierarchy for the file insert popup is show below; all widgets 279are listed by class and instance name. 280<!-- .sp --> 281<!-- .nf --> 282<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i --> 283<literallayout class="monospaced"> 284Text <name of Text widget> 285 TransientShell insertFile 286 Form form 287 Label label 288 Text text 289 Command insert 290 Command cancel 291</literallayout> 292<!-- .fi --> 293</para> 294</sect2> 295<sect2 id="Text_Selections_for_Users"> 296<title>Text Selections for Users</title> 297<para> 298<!-- .LP --> 299<indexterm><primary>Text widget</primary><secondary>Text Selections for Users</secondary></indexterm> 300The text widgets have a text selection mechanism that allows 301the user to copy pieces of the text into the <function>PRIMARY</function> selection, 302and paste 303into the text widget some text that another application (or text 304widget) has put in the <function>PRIMARY</function> selection. 305</para> 306<para> 307<!-- .LP --> 308One method of selecting text is to press pointer button 1 309on the beginning of the text to be selected, drag the pointer until all 310of the desired text is highlighted, and then release the button to 311activate the selection. Another method is to click pointer button 1 at 312one end of the text to be selected, then click pointer button 3 at the 313other end. 314</para> 315<para> 316<!-- .LP --> 317To modify a currently active selection, press pointer button 3 near 318either the end of the selection that you want to 319adjust. This end of the selection may be moved while holding down pointer 320button 3. When the proper area has been highlighted release the pointer 321button to activate the selection. 322</para> 323<para> 324<!-- .LP --> 325The selected text may now be pasted into another application, and 326will remain active until some other client makes a selection. 327To paste text that some other application has 328put into the <function>PRIMARY</function> selection use pointer button 2. 329First place the insertion point where you would like the text to be inserted, 330then click and release pointer button 2. 331</para> 332<para> 333<!-- .LP --> 334Rapidly clicking pointer button 1 the following number of times will adjust 335the selection as described. 336<variablelist> 337 <varlistentry> 338 <term> 339 <function>Two</function> 340 </term> 341 <listitem> 342 <para> 343Select the word under the pointer. A word boundary is defined by the 344Text widget to be a Space, Tab, or Carriage Return. 345 </para> 346 </listitem> 347 </varlistentry> 348 <varlistentry> 349 <term> 350 <function>Three</function> 351 </term> 352 <listitem> 353 <para> 354Select the line under the pointer. 355 </para> 356 </listitem> 357 </varlistentry> 358 <varlistentry> 359 <term> 360 <function>Four</function> 361 </term> 362 <listitem> 363 <para> 364Select the paragraph under the pointer. A paragraph boundary is 365defined by the text widget as two Carriage Returns in a row with only 366Spaces or Tabs between them. 367 </para> 368 </listitem> 369 </varlistentry> 370 <varlistentry> 371 <term> 372 <function>Five</function> 373 </term> 374 <listitem> 375 <para> 376Select the entire text buffer. 377 </para> 378 </listitem> 379 </varlistentry> 380</variablelist> 381</para> 382<para> 383To unset the text selection, click pointer button 1 without moving it. 384</para> 385</sect2> 386</sect1> 387 388<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_text_widget_actions.xml"/> 389<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_default_translation_bindings.xml"/> 390<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextFuncs.xml"/> 391<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiText.xml"/> 392<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSource.xml"/> 393<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSink.xml"/> 394<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextCustom.xml"/> 395<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Text.xml"/> 396<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSource.xml"/> 397<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSink.xml"/> 398 399</chapter> 400