# Text Widgets

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.

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.)

The words insertion point 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 pointer.

The text widget supports three edit modes, controlling the types of modifications a user is allowed to make:

- Append-only

- Editable

- Read-only

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 `XtSetValues`, it cannot be modified via with `XawTextReplace`. 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.

## Text Widget for Users

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.

### Default Key Bindings

The default key bindings are patterned after those in the EMACS text editor:

    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

In addition, the pointer may be used to cut and paste text:

    	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)

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 `translations` resource.

### Search and Replace

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 Control-r or Control-s. If Control-s is used the search will be forward in the file from the current location of the insertion point; if Control-r 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.

At the top of the search popup are two toggle buttons labeled backward and forward. 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.

Directly under the buttons there are two text areas, one labeled Search for: and the other labeled Replace with:. If this is a read-only Text widget the Replace with: 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:

    Carriage Return:	Execute the action, and pop down the search widget.
    Tab:	Execute the action, then move to the next field.
    Shift Carriage Return:	Execute the action, then move to the next field.
    Control-q Tab:	Enter a Tab into a text field.
    Control-c:	Pop down the search popup.

Using these special key sequences should allow simple searches without ever removing one's hands from the keyboard.

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.

Search

  Search for the specified string.

Replace

  Replace the currently highlighted string with the string in the Replace with text field, and move onto the next occurrence of the Search for text field. The functionality is commonly referred to as query-replace.

ReplaceAll

  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.

ReplaceAll

  Remove the search popup from the screen.

Finally, when `international` resource is `true`, 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 `preeditType` resource.

The widget hierarchy for the search popup is show below, all widgets are listed by class and instance name.

    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

### File Insertion

To insert a file into a text widget, type the key sequence Meta-i, 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 Insert File, or type Carriage Return. 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 Cancel. If Meta-i is typed at a text widget that is read-only, it will beep, as no file insertion is allowed.

The widget hierarchy for the file insert popup is show below; all widgets are listed by class and instance name.

    Text  <name of Text widget>
    	TransientShell  insertFile
    		Form  form
    			Label  label
    			Text  text
    			Command  insert
    			Command  cancel

### Text Selections for Users

The text widgets have a text selection mechanism that allows the user to copy pieces of the text into the `PRIMARY` selection, and paste into the text widget some text that another application (or text widget) has put in the `PRIMARY` selection.

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.

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.

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 `PRIMARY` 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.

Rapidly clicking pointer button 1 the following number of times will adjust the selection as described.

`Two`

  Select the word under the pointer. A word boundary is defined by the Text widget to be a Space, Tab, or Carriage Return.

`Three`

  Select the line under the pointer.

`Four`

  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.

`Five`

  Select the entire text buffer.

To unset the text selection, click pointer button 1 without moving it.