home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / CH5.intro < prev    next >
Encoding:
Text File  |  1991-07-29  |  10.5 KB  |  284 lines
  1. .LP
  2. .bp
  3. \&
  4. .sp 1
  5. .ce 3
  6. \s+1\fBChapter 5\fP\s-1
  7.  
  8. \s+1\fBText Widgets\fP\s-1
  9. .sp 2
  10. .nr H1 5
  11. .nr H2 0
  12. .nr H3 0
  13. .nr H4 0
  14. .nr H5 0
  15. .na
  16. .LP
  17. .XS
  18. Chapter 5 - Text Widgets.
  19. .XE
  20. .LP
  21. The Text widget provides a window that will allow an application
  22. to display and edit one or more lines of text.  Options are provided to
  23. allow the user to add Scrollbars to its window, search for a specific
  24. string, and modify the text in the buffer.
  25. .LP
  26. The Text widget is made up of a number of pieces.  The modularization of
  27. functionality is intended to ease customization.  For most applications,
  28. the AsciiText widget will be general enough to meet the programmer's
  29. needs.  If more flexibility, special features, or extra functionality is
  30. needed, it can be added by implementing a new TextSource or TextSink, or
  31. by subclassing the Text Widget (See Section 5.8 for customization
  32. details.)
  33. .LP
  34. The words \fIinsertion point\fP are used in this chapter to refer to the text
  35. caret.  This is the symbol that is displayed between two characters in
  36. the file.  The insertion point marks the location where any new characters
  37. will be added to the file.  To avoid confusion the pointer cursor will 
  38. always be referred to as the \fIpointer\fP.
  39. .LP
  40. The text widget supports three edit modes, controlling the types of
  41. modifications a user is allowed to make:
  42. .IN "Text widget" "edit modes"
  43. .IP \(bu 5
  44. Append-only 
  45. .IP \(bu 5
  46. Editable
  47. .IP \(bu 5
  48. Read-only 
  49. .LP
  50. Read-only mode does not allow the user or the programmer to modify the text
  51. in the widget.  While the programmer may reset the entire string in
  52. read-only mode with \fBXtSetValues\fP, he may not modify parts of the
  53. text with \fBXawTextReplace\fP.  Append-only and editable modes allow
  54. .IN "XawTextReplace" ""
  55. the text at the insertion point to be modified.  The only difference is
  56. that text may only be added to or removed from the end of a buffer in
  57. append-only mode.
  58. .LP
  59. .NH 2
  60. Text Widget for Users
  61. .IN "Text widget" "User's Guide to the Text widget"
  62. .XS
  63.     Text Widget for Users
  64. .XE
  65. .LP
  66. The Text widget provides many of the common keyboard editing commands.
  67. These commands allow users to move around and edit the buffer.  If an
  68. illegal operation is attempted, (such as deleting characters in a
  69. read-only text widget), the terminal bell will be rung.
  70. .NH3
  71. Default Key Bindings
  72. .IN "Text widget" "default key bindings"
  73. .LP
  74. The default key bindings are patterned after those in the EMACS text editor:
  75. .sp
  76. .Ds 0
  77. .TA 1.0i 3.0i 4.5i
  78. .ta 1.0i 3.0i 4.5i
  79. Ctrl-a    Beginning Of Line    Meta-b    Backward Word
  80. Ctrl-b    Backward Character    Meta-f    Forward Word
  81. Ctrl-d    Delete Next Character    Meta-i    Insert File
  82. Ctrl-e    End Of Line    Meta-k    Kill To End Of Paragraph
  83. Ctrl-f    Forward Character    Meta-q    Form Paragraph
  84. Ctrl-g    Multiply Reset    Meta-v    Previous Page
  85. Ctrl-h    Delete Previous Character    Meta-y    Insert Current Selection
  86. Ctrl-j    Newline And Indent    Meta-z    Scroll One Line Down
  87. Ctrl-k    Kill To End Of Line    Meta-d    Delete Next Word
  88. Ctrl-l    Redraw Display    Meta-D    Kill Word
  89. Ctrl-m    Newline    Meta-h    Delete Previous Word
  90. Ctrl-n    Next Line    Meta-H    Backward Kill Word
  91. Ctrl-o    Newline And Backup    Meta-<    Beginning Of File
  92. Ctrl-p    Previous Line    Meta->    End Of File
  93. Ctrl-r    Search/Replace Backward    Meta-]    Forward Paragraph
  94. Ctrl-s    Search/Replace Forward    Meta-[    Backward Paragraph
  95. Ctrl-t    Transpose Characters
  96. Ctrl-u    Multiply by 4    Meta-Delete    Delete Previous Word
  97. Ctrl-v    Next Page    Meta-Shift Delete    Kill Previous Word
  98. Ctrl-w    Kill Selection    Meta-Backspace    Delete Previous Word
  99. Ctrl-y    Unkill    Meta-Shift Backspace    Kill Previous Word
  100. Ctrl-z    Scroll One Line Up
  101. .De
  102. .sp
  103. .LP
  104. In addition, the pointer may be used to cut and paste text:
  105. .LP
  106. .Ds
  107. .TA .5i 2.0i
  108. .ta .5i 2.0i
  109.     Button 1 Down    Start Selection
  110.     Button 1 Motion    Adjust Selection
  111.     Button 1 Up    End Selection (cut)
  112.  
  113.     Button 2 Down    Insert Current Selection (paste)
  114.  
  115.     Button 3 Down    Extend Current Selection
  116.     Button 3 Motion    Adjust Selection
  117.     Button 3 Up    End Selection (cut)
  118.  
  119. .De
  120. .LP
  121. Since all of these key and pointer bindings are set through the
  122. translations and resource manager, the user and the application
  123. programmer can modify them by changing the Text widget's
  124. \fBtranslations\fP resource.
  125. .bs 1
  126. .NH 3
  127. Search and Replace
  128. .IN "Text widget" "search"
  129. .IN "Text widget" "query replace"
  130. .LP
  131. The Text widget provides a search popup that can be used to search for a
  132. string within the current Text widget.  The popup can be activated by
  133. typing either \fIControl-r\fP or \fIControl-s\fP.  If \fIControl-s\fP is
  134. used the search will be forward in the file from the current location of the
  135. insertion point; if \fIControl-r\fP is used the search will be backward.  The
  136. activated popup is placed under the pointer.  It has a number of buttons
  137. that allow both text searches and text replacements to be performed.
  138. .LP
  139. At the top of the search popup are two toggle buttons labeled
  140. \fIbackward\fP and \fIforward\fP.  One of these buttons will always be
  141. highlighted; this is the direction in which the search will be
  142. performed.  The user can change the direction at any time by clicking on
  143. the appropriate button.
  144. .LP
  145. Directly under the buttons there are two text areas, one labeled
  146. \fISearch for:\fP and the other labeled \fIReplace with:\fP.  If this is
  147. a read-only Text widget the \fIReplace with:\fP field will be insensitive
  148. and no replacements will be allowed.  After each of these labels will be
  149. a text field.  This field will allow the user to enter a string to
  150. search for and the string to replace it with.  Only one of these text
  151. fields will have a window border around it; this is the active text
  152. field.  Any key presses that occur when the focus in in the search popup
  153. will be directed to the active text field.  There are also a few special
  154. key sequences:
  155. .DS
  156. .TA 1.75i
  157. .ta 1.75i
  158. \fBCarriage Return\fP:    Execute the action, and pop down the search widget.
  159. \fBTab\fP:    Execute the action, then move to the next field.
  160. \fBShift Carriage Return\fP:    Execute the action, then move to the next field.
  161. \fBControl-q Tab\fP:    Enter a Tab into a text field.
  162. \fBControl-c\fP:    Pop down the search popup.
  163. .DE
  164. .LP
  165. Using these special key sequences should allow simple
  166. searches without ever removing one's hands from the keyboard.
  167. .LP
  168. At the bottom of the search popup is a row of buttons.  These buttons
  169. allow the same actions to to be performed as the key sequences, but the
  170. buttons will leave the popup active.  This can be quite useful if many
  171. searches are being performed, as the popup will be left on the display.
  172. Since the search popup is a transient window, it may be picked
  173. up with the window manager and pulled off to the side for use 
  174. at a later time.
  175. .IP \fBSearch\fP 15
  176. Search for the specified string.
  177. .IP \fBReplace\fP 15
  178. Replace the currently highlighted string with the string in the
  179. \fIReplace with\fP text field, and move onto the next occurrence of the
  180. \fISearch for\fP text field.  The functionality is commonly referred to as
  181. query-replace.
  182. .IP \fBReplace-All\fP 15
  183. Replace all occurrences of the search string with the replace string from
  184. the current insertion point position to the end (or beginning) of the
  185. file.  There is no key sequence to perform this action.
  186. .IP \fBCancel\fP 15
  187. Remove the search popup from the screen.
  188. .LP
  189. The widget hierarchy for the search popup is show below, all widgets
  190. are listed by class and instance name.
  191. .sp
  192. .nf
  193. .ta .5i 1.0i 1.5i 2.0i 2.5i
  194. Text  <name of Text widget>
  195.     TransientShell  search
  196.         Form  form
  197.             Label label1
  198.             Label  label2
  199.             Toggle  backwards
  200.             Toggle  forwards
  201.             Label  searchLabel
  202.             Text  searchText
  203.             Label  replaceLabel
  204.             Text  replaceText
  205.             Command  search
  206.             Command  replaceOne
  207.             Command  replaceAll
  208.             Command  cancel
  209. .fi
  210. .NH 3
  211. File Insertion
  212. .LP
  213. .IN "Text widget" "file insertion"
  214. To insert a file into a text widget, type the key sequence \fIMeta-i\fP,
  215. which will activate the file insert popup.  This popup will appear under
  216. the pointer, and any text typed while the focus is in this popup will be
  217. redirected to the text field used for the filename.  When the desired
  218. filename has been entered, click on \fIInsert File\fP, or type
  219. \fICarriage Return\fP.  The named file will then be inserted in the text
  220. widget beginning at the insertion point position.  If an error occurs when
  221. opening the file, an error message will be printed, prompting the user
  222. to enter the filename again.  The file insert may be aborted by clicking
  223. on \fICancel\fP.  If \fIMeta-i\fP is typed at a text widget that is
  224. read-only, it will beep, as no file insertion is allowed.
  225. .LP
  226. The widget hierarchy for the file insert popup is show below, all widgets
  227. are listed by class and instance name.
  228. .sp
  229. .nf
  230. .ta .5i 1.0i 1.5i 2.0i 2.5i
  231. Text  <name of Text widget>
  232.     TransientShell  insertFile
  233.         Form  form
  234.             Label  label 
  235.             Text  text
  236.             Command  insert
  237.             Command  cancel
  238. .fi
  239. .NH 3
  240. Text Selections for Users
  241. .LP
  242. .IN "Text widget" "Text Selections for Users"
  243. The text widgets have a very powerful text selection mechanism that allows
  244. the user to copy pieces of the text into the \fBPRIMARY\fP selection,
  245. and paste 
  246. into the text widget some text that another application (or text
  247. widget) has put in the \fBPRIMARY\fP selection.
  248. .LP
  249. The simplest method of selecting text is to press pointer button 1
  250. on the beginning of the text to be selected, drag the pointer until all
  251. of the desired text is highlighted, and then release the button to
  252. activate the selection.  The text may now be pasted into any other
  253. application.  This selection will remain active until some other client
  254. makes a selection.
  255. .LP
  256. To modify a currently active selection, click pointer button 3 near
  257. either the end or the beginning of the selection that you want to
  258. adjust.  This end of the selection may be moved while holding down pointer
  259. button 3.  When the proper area has been highlighted release the pointer
  260. button to activate the selection.
  261. .LP
  262. To paste text that some other application or Text widget has
  263. put into the \fBPRIMARY\fP selection use pointer button 2.  
  264. First place the insertion point where you would like the text to be inserted,
  265. then click and release pointer button 2.  The text
  266. that is in the \fBPRIMARY\fP selection will be placed into the Text widget.
  267. .LP
  268. Rapidly clicking pointer button 1 the following number of times will adjust
  269. the selection as described.
  270. .IP \fBTwo\fP 1.0i
  271. Select the word under the pointer.  A word boundary is defined by the
  272. Text widget to be a Space, Tab, or Carriage Return.
  273. .IP \fBThree\fP 1.0i
  274. Select the line under the pointer.
  275. .IP \fBFour\fP 1.0i
  276. Select the paragraph under the pointer.  A paragraph boundary is
  277. defined by the text widget as two Carriage Returns in a row with only
  278. Spaces or Tabs between them. 
  279. .IP \fBFive\fP 1.0i
  280. Select the entire text buffer.
  281. .LP
  282. To unset the text selection just click and release pointer button 1
  283. without moving it.
  284.