Added libXaw

1 files changed, 292 insertions, 0 deletions

diff --git a/libXaw/spec/CH5.intro b/libXaw/spec/CH5.intro
new file mode 100644
index 000000000..69230c0ad
--- /dev/null
+++ b/libXaw/spec/CH5.intro
@@ -0,0 +1,292 @@
+.\" $Xorg: CH5.intro,v 1.3 2000/08/17 19:42:26 cpqbld Exp $
+.LP
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 5\fP\s-1
+
+\s+1\fBText Widgets\fP\s-1
+.sp 2
+.nr H1 5
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 5 - Text Widgets.
+.XE
+.LP
+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.
+.LP
+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.)
+.LP
+The words \fIinsertion point\fP 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 \fIpointer\fP.
+.LP
+The text widget supports three edit modes, controlling the types of
+modifications a user is allowed to make:
+.IN "Text widget" "edit modes"
+.IP \(bu 5
+Append-only
+.IP \(bu 5
+Editable
+.IP \(bu 5
+Read-only
+.LP
+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 \fBXtSetValues\fP, it cannot be modified via
+with \fBXawTextReplace\fP.  Append-only and editable modes allow
+.IN "XawTextReplace" ""
+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.
+.LP
+.NH 2
+Text Widget for Users
+.IN "Text widget" "User's Guide to the Text widget"
+.XS
+	Text Widget for Users
+.XE
+.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.
+.NH 3
+Default Key Bindings
+.IN "Text widget" "default key bindings"
+.LP
+The default key bindings are patterned after those in the EMACS text editor:
+.sp
+.Ds 0
+.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
+.De
+.sp
+.LP
+In addition, the pointer may be used to cut and paste text:
+.LP
+.Ds
+.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)
+
+.De
+.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
+\fBtranslations\fP resource.
+.\"
+.NH 3
+Search and Replace
+.IN "Text widget" "search"
+.IN "Text widget" "query replace"
+.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 \fIControl-r\fP or \fIControl-s\fP.  If \fIControl-s\fP is
+used the search will be forward in the file from the current location of the
+insertion point; if \fIControl-r\fP 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.
+.LP
+At the top of the search popup are two toggle buttons labeled
+\fIbackward\fP and \fIforward\fP.  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.
+.LP
+Directly under the buttons there are two text areas, one labeled
+\fISearch for:\fP and the other labeled \fIReplace with:\fP.  If this is
+a read-only Text widget the \fIReplace with:\fP 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:
+.DS
+.TA 1.75i
+.ta 1.75i
+\fBCarriage Return\fP:	Execute the action, and pop down the search widget.
+\fBTab\fP:	Execute the action, then move to the next field.
+\fBShift Carriage Return\fP:	Execute the action, then move to the next field.
+\fBControl-q Tab\fP:	Enter a Tab into a text field.
+\fBControl-c\fP:	Pop down the search popup.
+.DE
+.LP
+Using these special key sequences should allow simple
+searches without ever removing one's hands from the keyboard.
+.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.
+.IP \fBSearch\fP 15
+Search for the specified string.
+.IP \fBReplace\fP 15
+Replace the currently highlighted string with the string in the
+\fIReplace with\fP text field, and move onto the next occurrence of the
+\fISearch for\fP text field.  The functionality is commonly referred to as
+query-replace.
+.IP \fBReplace-All\fP 15
+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.
+.IP \fBCancel\fP 15
+Remove the search popup from the screen.
+.LP
+Finally, when \fBinternational\fP resource is \fBtrue\fP, 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 \fBpreeditType\fP
+resource.
+.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
+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
+.fi
+.NH 3
+File Insertion
+.LP
+.IN "Text widget" "file insertion"
+To insert a file into a text widget, type the key sequence \fIMeta-i\fP,
+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 \fIInsert File\fP, or type
+\fICarriage Return\fP.  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 \fICancel\fP.  If \fIMeta-i\fP is typed at a text widget that is
+read-only, it will beep, as no file insertion is allowed.
+.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
+Text  <name of Text widget>
+	TransientShell  insertFile
+		Form  form
+			Label  label
+			Text  text
+			Command  insert
+			Command  cancel
+.fi
+.NH 3
+Text Selections for Users
+.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 \fBPRIMARY\fP selection,
+and paste
+into the text widget some text that another application (or text
+widget) has put in the \fBPRIMARY\fP selection.
+.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.
+.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.
+.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 \fBPRIMARY\fP 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.
+.LP
+Rapidly clicking pointer button 1 the following number of times will adjust
+the selection as described.
+.IP \fBTwo\fP 1.0i
+Select the word under the pointer.  A word boundary is defined by the
+Text widget to be a Space, Tab, or Carriage Return.
+.IP \fBThree\fP 1.0i
+Select the line under the pointer.
+.IP \fBFour\fP 1.0i
+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.
+.IP \fBFive\fP 1.0i
+Select the entire text buffer.
+.LP
+To unset the text selection, click pointer button 1
+without moving it.