aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/CH5.xml
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2011-03-25 15:37:13 +0000
committermarha <marha@users.sourceforge.net>2011-03-25 15:37:13 +0000
commit41a502478a2972358dec934d82ee401c61a5cd36 (patch)
tree3fda8100e6da9b4a2863789e393016a750502067 /libXaw/specs/CH5.xml
parent81aeaf653a832c4054d9a40b1cc796911521a739 (diff)
parent272e57235cd60a2e65ac8258d96a02eb3939b687 (diff)
downloadvcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.gz
vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.bz2
vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.zip
svn merge ^/branches/released .
Diffstat (limited to 'libXaw/specs/CH5.xml')
-rw-r--r--libXaw/specs/CH5.xml397
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-&lt; Beginning Of File
+Ctrl-p Previous Line Meta-&gt; 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 &lt;name of Text widget&gt;
+ 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 &lt;name of Text widget&gt;
+ 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>