specs/CH5.xml

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