293 lines
11 KiB
Plaintext
293 lines
11 KiB
Plaintext
.\" $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.
|