diff options
Diffstat (limited to 'libXaw/specs/CH5.xml')
| -rw-r--r-- | libXaw/specs/CH5.xml | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/libXaw/specs/CH5.xml b/libXaw/specs/CH5.xml new file mode 100644 index 000000000..eb3f2fb3e --- /dev/null +++ b/libXaw/specs/CH5.xml @@ -0,0 +1,397 @@ +<chapter id="text_widgets"> +<title>Text Widgets</title> + +<para> +The Text widget provides a window that will allow an application +to display and edit one or more lines of text. Options are provided to +allow the user to add Scrollbars to its window, search for a specific +string, and modify the text in the buffer. +</para> +<para> +The Text widget is made up of a number of pieces; it was modularized to +ease customization. The AsciiText widget class (actually not limited to +ASCII but so named for compatibility) is be general enough to most +needs. If more flexibility, special features, or extra functionality is +needed, they can be added by implementing a new TextSource or TextSink, or +by subclassing the Text Widget (See Section 5.8 for customization +details.) <!-- xref --> +</para> +<para> +The words <emphasis remap='I'>insertion point</emphasis> are used in this chapter to refer to the text +caret. This is the symbol that is displayed between two characters in +the file. The insertion point marks the location where any new characters +will be added to the file. To avoid confusion the pointer cursor will +always be referred to as the <emphasis remap='I'>pointer</emphasis>. +</para> +<para> +The text widget supports three edit modes, controlling the types of +modifications a user is allowed to make: +</para> +<para> +<itemizedlist> + <listitem><para>Append-only</para></listitem> + <listitem><para>Editable</para></listitem> + <listitem><para>Read-only</para></listitem> +</itemizedlist> +</para> +<para> +Read-only mode does not allow the user or the programmer to modify the text +in the widget. While the entire string may be reset in +read-only mode with <function>XtSetValues</function>, it cannot be modified via +with <function>XawTextReplace</function>. Append-only and editable modes allow +the text at the insertion point to be modified. The only difference is +that text may only be added to or removed from the end of a buffer in +append-only mode. +</para> +<sect1 id="Text_Widget_for_Users"> +<title>Text Widget for Users</title> +<!-- .IN "Text widget" "User's Guide to the Text widget" --> +<!-- .XS --> +<!-- Text Widget for Users --> +<!-- .XE --> +<para> +<!-- .LP --> +The Text widget provides many of the common keyboard editing commands. +These commands allow users to move around and edit the buffer. If an +illegal operation is attempted, (such as deleting characters in a +read-only text widget), the X server will beep. +</para> +<sect2 id="Default_Key_Bindings"> +<title>Default Key Bindings</title> +<!-- .IN "Text widget" "default key bindings" --> +<para> +<!-- .LP --> +The default key bindings are patterned after those in the EMACS text editor: +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA 1.0i 3.0i 4.5i --> +<!-- .ta 1.0i 3.0i 4.5i --> +Ctrl-a Beginning Of Line Meta-b Backward Word +Ctrl-b Backward Character Meta-f Forward Word +Ctrl-d Delete Next Character Meta-i Insert File +Ctrl-e End Of Line Meta-k Kill To End Of Paragraph +Ctrl-f Forward Character Meta-q Form Paragraph +Ctrl-g Multiply Reset Meta-v Previous Page +Ctrl-h Delete Previous Character Meta-y Insert Current Selection +Ctrl-j Newline And Indent Meta-z Scroll One Line Down +Ctrl-k Kill To End Of Line Meta-d Delete Next Word +Ctrl-l Redraw Display Meta-D Kill Word +Ctrl-m Newline Meta-h Delete Previous Word +Ctrl-n Next Line Meta-H Backward Kill Word +Ctrl-o Newline And Backup Meta-< Beginning Of File +Ctrl-p Previous Line Meta-> End Of File +Ctrl-r Search/Replace Backward Meta-] Forward Paragraph +Ctrl-s Search/Replace Forward Meta-[ Backward Paragraph +Ctrl-t Transpose Characters +Ctrl-u Multiply by 4 Meta-Delete Delete Previous Word +Ctrl-v Next Page Meta-Shift Delete Kill Previous Word +Ctrl-w Kill Selection Meta-Backspace Delete Previous Word +Ctrl-y Unkill Meta-Shift Backspace Kill Previous Word +Ctrl-z Scroll One Line Up +Ctrl-\\ Reconnect to input method +Kanji Reconnect to input method +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +In addition, the pointer may be used to cut and paste text: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.0i --> +<!-- .ta .5i 2.0i --> + Button 1 Down Start Selection + Button 1 Motion Adjust Selection + Button 1 Up End Selection (cut) + + Button 2 Down Insert Current Selection (paste) + + Button 3 Down Extend Current Selection + Button 3 Motion Adjust Selection + Button 3 Up End Selection (cut) + +</literallayout> +</para> +<para> +<!-- .LP --> +Since all of these key and pointer bindings are set through the +translations and resource manager, the user and the application +programmer can modify them by changing the Text widget's +<function>translations</function> resource. +<!-- .\" --> +</para> +</sect2> +<sect2 id="Search_and_Replace"> +<title>Search and Replace</title> +<!-- .IN "Text widget" "search" --> +<!-- .IN "Text widget" "query replace" --> +<para> +<!-- .LP --> +The Text widget provides a search popup that can be used to search for a +string within the current Text widget. The popup can be activated by +typing either <emphasis remap='I'>Control-r</emphasis> or <emphasis remap='I'>Control-s</emphasis>. If <emphasis remap='I'>Control-s</emphasis> is +used the search will be forward in the file from the current location of the +insertion point; if <emphasis remap='I'>Control-r</emphasis> is used the search will be backward. The +activated popup is placed under the pointer. It has a number of buttons +that allow both text searches and text replacements to be performed. +</para> +<para> +<!-- .LP --> +At the top of the search popup are two toggle buttons labeled +<emphasis remap='I'>backward</emphasis> and <emphasis remap='I'>forward</emphasis>. One of these buttons will always be +highlighted; this is the direction in which the search will be +performed. The user can change the direction at any time by clicking on +the appropriate button. +</para> +<para> +<!-- .LP --> +Directly under the buttons there are two text areas, one labeled +<emphasis remap='I'>Search for:</emphasis> and the other labeled <emphasis remap='I'>Replace with:</emphasis>. If this is +a read-only Text widget the <emphasis remap='I'>Replace with:</emphasis> field will be insensitive +and no replacements will be allowed. After each of these labels will be +a text field. This field will allow the user to enter a string to +search for and the string to replace it with. Only one of these text +fields will have a window border around it; this is the active text +field. Any key presses that occur when the focus in in the search popup +will be directed to the active text field. There are also a few special +key sequences: +<literallayout class="monospaced"> +<!-- .TA 1.75i --> +<!-- .ta 1.75i --> +<function>Carriage Return</function>: Execute the action, and pop down the search widget. +<function>Tab</function>: Execute the action, then move to the next field. +<function>Shift Carriage Return</function>: Execute the action, then move to the next field. +<function>Control-q Tab</function>: Enter a Tab into a text field. +<function>Control-c</function>: Pop down the search popup. +</literallayout> +</para> +<para> +<!-- .LP --> +Using these special key sequences should allow simple +searches without ever removing one's hands from the keyboard. +</para> +<para> +<!-- .LP --> +Near the bottom of the search popup is a row of buttons. These buttons +allow the same actions to to be performed as the key sequences, but the +buttons will leave the popup active. This can be quite useful if many +searches are being performed, as the popup will be left on the display. +Since the search popup is a transient window, it may be picked +up with the window manager and pulled off to the side for use +at a later time. +</para> +<variablelist> + <varlistentry> + <term>Search</term> + <listitem> + <para> +Search for the specified string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Replace</term> + <listitem> + <para> +Replace the currently highlighted string with the string in the +<emphasis remap='I'>Replace with</emphasis> text field, and move onto the next occurrence of the +<emphasis remap='I'>Search for</emphasis> text field. The functionality is commonly referred to as +query-replace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ReplaceAll</term> + <listitem> + <para> +Replace all occurrences of the search string with the replace string from +the current insertion point position to the end (or beginning) of the +file. There is no key sequence to perform this action. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ReplaceAll</term> + <listitem> + <para> +Remove the search popup from the screen. + </para> + </listitem> + </varlistentry> +</variablelist> +<para> +<!-- .LP --> +Finally, when <function>international</function> resource is <function>true</function>, there may be a +pre-edit buffer below the button row, for composing input. Its presence +is determined by the X locale in use and the VendorShell's <function>preeditType</function> +resource. +</para> +<para> +<!-- .LP --> +The widget hierarchy for the search popup is show below, all widgets +are listed by class and instance name. +<!-- .sp --> +<!-- .nf --> +<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i --> +<literallayout class="monospaced"> +Text <name of Text widget> + TransientShell search + Form form + Label label1 + Label label2 + Toggle backwards + Toggle forwards + Label searchLabel + Text searchText + Label replaceLabel + Text replaceText + Command search + Command replaceOne + Command replaceAll + Command cancel +</literallayout> +<!-- .fi --> +</para> +</sect2> +<sect2 id="File_Insertion"> +<title>File Insertion</title> +<para> +<!-- .LP --> +<!-- .IN "Text widget" "file insertion" --> +To insert a file into a text widget, type the key sequence <emphasis remap='I'>Meta-i</emphasis>, +which will activate the file insert popup. This popup will appear under +the pointer, and any text typed while the focus is in this popup will be +redirected to the text field used for the filename. When the desired +filename has been entered, click on <emphasis remap='I'>Insert File</emphasis>, or type +<emphasis remap='I'>Carriage Return</emphasis>. The named file will then be inserted in the text +widget beginning at the insertion point position. If an error occurs when +opening the file, an error message will be printed, prompting the user +to enter the filename again. The file insert may be aborted by clicking +on <emphasis remap='I'>Cancel</emphasis>. If <emphasis remap='I'>Meta-i</emphasis> is typed at a text widget that is +read-only, it will beep, as no file insertion is allowed. +</para> +<para> +<!-- .LP --> +The widget hierarchy for the file insert popup is show below; all widgets +are listed by class and instance name. +<!-- .sp --> +<!-- .nf --> +<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i --> +<literallayout class="monospaced"> +Text <name of Text widget> + TransientShell insertFile + Form form + Label label + Text text + Command insert + Command cancel +</literallayout> +<!-- .fi --> +</para> +</sect2> +<sect2 id="Text_Selections_for_Users"> +<title>Text Selections for Users</title> +<para> +<!-- .LP --> +<!-- .IN "Text widget" "Text Selections for Users" --> +The text widgets have a text selection mechanism that allows +the user to copy pieces of the text into the <function>PRIMARY</function> selection, +and paste +into the text widget some text that another application (or text +widget) has put in the <function>PRIMARY</function> selection. +</para> +<para> +<!-- .LP --> +One method of selecting text is to press pointer button 1 +on the beginning of the text to be selected, drag the pointer until all +of the desired text is highlighted, and then release the button to +activate the selection. Another method is to click pointer button 1 at +one end of the text to be selected, then click pointer button 3 at the +other end. +</para> +<para> +<!-- .LP --> +To modify a currently active selection, press pointer button 3 near +either the end of the selection that you want to +adjust. This end of the selection may be moved while holding down pointer +button 3. When the proper area has been highlighted release the pointer +button to activate the selection. +</para> +<para> +<!-- .LP --> +The selected text may now be pasted into another application, and +will remain active until some other client makes a selection. +To paste text that some other application has +put into the <function>PRIMARY</function> selection use pointer button 2. +First place the insertion point where you would like the text to be inserted, +then click and release pointer button 2. +</para> +<para> +<!-- .LP --> +Rapidly clicking pointer button 1 the following number of times will adjust +the selection as described. +<variablelist> + <varlistentry> + <term> + <function>Two</function> + </term> + <listitem> + <para> +Select the word under the pointer. A word boundary is defined by the +Text widget to be a Space, Tab, or Carriage Return. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Three</function> + </term> + <listitem> + <para> +Select the line under the pointer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Four</function> + </term> + <listitem> + <para> +Select the paragraph under the pointer. A paragraph boundary is +defined by the text widget as two Carriage Returns in a row with only +Spaces or Tabs between them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Five</function> + </term> + <listitem> + <para> +Select the entire text buffer. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +To unset the text selection, click pointer button 1 without moving it. +</para> +</sect2> +</sect1> + +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_text_widget_actions.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_default_translation_bindings.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextFuncs.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextCustom.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Text.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSink.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSource.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSink.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSource.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiText.xml"/> +</chapter> |