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