/jEdit/tags/jedit-4-0-pre3/doc/users-guide/text-edit.xml
XML | 974 lines | 971 code | 1 blank | 2 comment | 0 complexity | 747d4c8d0990dde51fc94f6829b5be4b MD5 | raw file
1<!-- jEdit buffer-local properties: --> 2<!-- :tabSize=1:indentSize=1:noTabs=true: --> 3 4<chapter id="editing"><title>Editing Text</title> 5 <sect1 id="caret"><title>Moving The Caret</title> 6 <para> 7 The most direct way to move the caret is to click the 8 mouse at the desired location in the text area. It can also be moved 9 using the keyboard. 10 </para> 11 <para> 12 The <keycap>Left</keycap>, <keycap>Right</keycap>, <keycap>Up</keycap> and 13 <keycap>Down</keycap> keys move the caret in the respective direction, and 14 the <keycap>Page Up</keycap> and <keycap>Page Down</keycap> keys move the 15 caret up and down one screenful, respectively. 16 </para> 17 <para> 18 When pressed once, the <keycap>Home</keycap> key moves the caret to the first 19 non-whitespace character of the current line. Pressing it a second time 20 moves the caret to the beginning of the line. Pressing it a third time 21 moves the caret to the first visible line. 22 </para> 23 <para> 24 The <keycap>End</keycap> key behaves in a 25 similar manner, going to the last non-whitespace character, the end of 26 the line, and finally to the last visible line. 27 </para> 28 <para> 29 If there is a selection, <keycap>Home</keycap> and <keycap>End</keycap> 30 behave the same as above, except that instead of operating on the current 31 line, they move the caret to the first and last lines of the selection, 32 respectively. 33 </para> 34 <para> 35 <keycombo><keycap>Control</keycap><keycap>Home</keycap></keycombo> and 36 <keycombo><keycap>Control</keycap><keycap>End</keycap></keycombo> move the 37 caret to the beginning and end of the buffer. 38 </para> 39 <para> 40 More advanced caret movement is covered in 41 <xref linkend="words" />, <xref linkend="lines" /> and 42 <xref linkend="paragraphs" />. 43 </para> 44 </sect1> 45 <sect1 id="selection"><title>Selecting Text</title> 46 <para> 47 A <firstterm>selection</firstterm> is a a block of text marked for further 48 manipulation. Unlike many other applications, jEdit supports both 49 range and rectangular selections, and several chunks of text can be 50 selected simultaneously. 51 </para> 52 <para> 53 Dragging the mouse creates a range selection from where the mouse was 54 pressed to where it was released. 55 Holding down <keycap>Shift</keycap> while clicking a location in the 56 buffer will create a selection from the caret position to the clicked 57 location. 58 </para> 59 <para> 60 Holding down <keycap>Shift</keycap> in addition to a caret movement key 61 (<keycap>Left</keycap>, <keycap>Up</keycap>, <keycap>Home</keycap>, etc) will 62 extend the selection in the specified direction. If no selection exists, one 63 will be created. 64 </para> 65 <para> 66 <guimenu>Edit</guimenu>><guimenuitem>Select All</guimenuitem> (shortcut: 67 <keycombo><keycap>Control</keycap><keycap>A</keycap></keycombo>) selects the 68 entire buffer. 69 </para> 70 <para> 71 <guimenu>Edit</guimenu>><guimenuitem>Select None</guimenuitem> (shortcut: 72 <keycap>Escape</keycap>) deactivates the selection. 73 </para> 74 <sect2><title>Rectangular Selection</title> 75 <para> 76 Holding down <keycap>Control</keycap> and dragging will create a rectangular 77 selection. Holding down 78 <keycap>Shift</keycap> and <keycap>Control</keycap> while clicking a location in 79 the buffer will create a rectangular selection from the caret position to 80 the clicked location. 81 </para> 82 <para> 83 It is possible to select a rectangle with zero width but non-zero height. 84 This can be used to insert a new column between two existing 85 columns, for example. Such zero-width selections are shown as a thin 86 vertical line. 87 </para> 88 <para> 89 Rectangles can be deleted, copied, pasted, and operated on using ordinary 90 editing commands. 91 </para> 92 <note> 93 <para> 94 Rectangular selections are implemented using character offsets, 95 not absolute screen positions, so they might not behave as you might 96 expect if a proportional-width font is being used, or hard tabs are 97 enabled. For information about changing the font used in the text 98 area, see <xref linkend="global-opts" />. For more information about 99 hard and soft tabs, see <xref linkend="soft-tabs" />. 100 </para> 101 </note> 102 </sect2> 103 <sect2 id="multi-select"><title>Multiple Selection</title> 104 <para> 105 Pressing <keycombo><keycap>Control</keycap> <keycap>\</keycap></keycombo> 106 turns multiple selection mode on and 107 off. In multiple selection mode, multiple fragments of text can be selected 108 and operated on simultaneously, and the text <literal>multi</literal> is shown 109 in the status bar. 110 </para> 111 <para> 112 While multiple selection mode is active, you can click and drag the mouse 113 to reposition the caret and create new selections. 114 </para> 115 <para> 116 Various jEdit commands behave differently with multiple selections: 117 </para> 118 <itemizedlist> 119 <listitem><para>Commands that copy text place the contents of 120 each selection, separated by line breaks, in the specified register. Note 121 that the selections are appended in the order they were created, not the 122 order they appear in the buffer. For example, if you select a chunk of 123 text near the end of the buffer, another near the beginning, then invoke 124 <guimenuitem>Copy</guimenuitem>, the clipboard will contain the later chunk, 125 followed by a line break, followed by the earlier chunk. 126 </para></listitem> 127 <listitem><para>Commands that insert (or paste) text replace each selection 128 with the entire text that is being inserted.</para></listitem> 129 <listitem><para>Commands that filter text (such as <guimenuitem>Spaces to 130 Tabs</guimenuitem>, <guimenuitem>Range Comment</guimenuitem>, and even 131 <guimenuitem>Replace in Selection</guimenuitem>) operate on each selection, 132 in turn.</para></listitem> 133 <listitem><para>Line-based commands (such as <guimenuitem>Shift Indent 134 Left</guimenuitem>, <guimenuitem>Shift Indent Right</guimenuitem>, and 135 <guimenuitem>Line Comment</guimenuitem>) operate on each line that contains 136 at least one selection, in addition to the line containing the caret. 137 </para></listitem> 138 <listitem><para>Caret movement commands that would normally deactivate the 139 selection (such as the arrow keys, while <keycap>Shift</keycap> is not being 140 held down), move the caret, leaving the selection as-is.</para></listitem> 141 <listitem><para>Some older plugins may not support multiple selection at 142 all.</para></listitem> 143 </itemizedlist> 144 <para> 145 <guimenu>Edit</guimenu>><guimenuitem>Invert Selection</guimenuitem> 146 (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 147 <keycap>I</keycap>) selects a set of text chunks such that all text 148 that was formely part of a selection is now unselected, and all text that 149 wasn't, is selected. 150 </para> 151 <tip> 152 <para> 153 Deactivating multiple selection 154 mode while a fragmented selection exists will leave the selection in place, 155 but it will prevent you from making further fragmented selections. 156 </para> 157 </tip> 158 </sect2> 159 </sect1> 160 <sect1 id="entering-text"><title>Inserting and Deleting Text</title> 161 <para> 162 Text entered at the keyboard is inserted into the buffer. If 163 overwrite mode is on, one character is deleted from in 164 front of the caret position for every character that is inserted. 165 To activate overwrite mode, press <keycap>Insert</keycap>. The caret is 166 drawn as horizontal line while in overwrite 167 mode; the text <literal>ovr</literal> also appears in the status bar. 168 </para> 169 <para> 170 Inserting text while there is a selection will replace the selection 171 with the inserted text. 172 </para> 173 <para> 174 Inserting text at the end of a line beyond the wrap column will 175 automatically break the line 176 at the appropriate word boundary. The wrap column is indicated in the 177 text area as a faint blue line and its location (specified in number of 178 character positions from the left margin) can be changed in one of 179 several ways: 180 </para> 181 <itemizedlist> 182 <listitem><para>On a global or mode-specific 183 basis in the 184 <guibutton>Editing</guibutton> and <guibutton>Mode-Specific</guibutton> panes 185 of the <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem> 186 dialog box; see <xref linkend="global-opts" />.</para></listitem> 187 <listitem><para>In the current buffer 188 for the duration of the editing session in the 189 <guimenu>Utilities</guimenu>><guimenuitem>Buffer Options</guimenuitem> 190 dialog box; see <xref linkend="buffer-opts" />. 191 </para></listitem> 192 <listitem><para>In the current buffer 193 for future editing sessions by placing 194 the following in one of the first 10 lines of the buffer, where 195 <replaceable>column</replaceable> is the desired wrap column position: 196 </para> 197 <screen>:maxLineLen=<replaceable>column</replaceable>:</screen> 198 </listitem> 199 </itemizedlist> 200 <para> 201 To disable word wrap completely, set the wrap column to 0 using any of the 202 above means. 203 </para> 204 <note> 205 <para> 206 Word wrap is implemented using character offsets, not screen 207 positions, so it might not behave like you expect if a 208 proportional-width font is being used. For information about 209 changing the font used in the text area, see <xref linkend="global-opts" />. 210 </para> 211 </note> 212 <para> 213 When inserting text, keep in mind that the <keycap>Tab</keycap> and 214 <keycap>Enter</keycap> keys might 215 not behave entirely like you expect because of various indentation 216 features; see <xref linkend="indent" /> for details. 217 </para> 218 <para> 219 The simplest way to delete text is with the 220 <keycap>Backspace</keycap> and <keycap>Delete</keycap> keys. If nothing is 221 selected, they delete the character before or after the caret, 222 respectively. If a selection exists, both delete the 223 selection. 224 </para> 225 <para> 226 More advanced deletion commands are described in 227 <xref linkend="words" />, <xref linkend="lines" /> and 228 <xref linkend="paragraphs" />. 229 </para> 230 </sect1> 231 <sect1 id="undo-redo"><title>Undo and Redo</title> 232 <para> 233 <guimenu>Edit</guimenu>><guimenuitem>Undo</guimenuitem> (shortcut: 234 <keycombo><keycap>Control</keycap><keycap>Z</keycap></keycombo>) undoes the 235 effects of the most recent text editing command. For example, this can be 236 used to restore unintentionally deleted text. More complicated operations, 237 such as a search and replace, can also be undone. By default, the undo 238 queue remembers the last 100 edits; older edits are discarded. 239 The undo queue size can be changed in the <guibutton>Editing</guibutton> pane 240 of the <guimenu>Utilities</guimenu>><guimenuitem>Global 241 Options</guimenuitem> dialog box. 242 </para> 243 <para> 244 <guimenu>Edit</guimenu>><guimenuitem>Redo</guimenuitem> (shortcut: 245 <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>) goes forward 246 in the undo queue, redoing changes which were undone. For example, if some 247 text was inserted, <guimenuitem>Undo</guimenuitem> will remove it from the 248 buffer. <guimenuitem>Redo</guimenuitem> will insert it again. 249 </para> 250 </sect1> 251 <sect1 id="words"><title>Working With Words</title> 252 <para> 253 Holding down <keycap>Control</keycap> in addition to <keycap>Left</keycap> or 254 <keycap>Right</keycap> moves the caret a word at 255 a time. Holding down <keycap>Shift</keycap> and <keycap>Control</keycap> 256 in addition to <keycap>Left</keycap> or <keycap>Right</keycap> 257 extends the selection a word at a time. 258 </para> 259 <para> 260 A single word can be selected by double-clicking with the mouse, 261 or using the 262 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Select 263 Word</guimenuitem> command (shortcut: 264 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycap>W</keycap>). 265 A selection that begins and ends on word boundaries can be created by 266 double-clicking and dragging. 267 </para> 268 <para> 269 Pressing <keycap>Control</keycap> in addition to 270 <keycap>Backspace</keycap> or <keycap>Delete</keycap> deletes the word 271 before or after the caret, respectively. 272 </para> 273 <para> 274 <guimenu>Edit</guimenu>><guimenuitem>Word Count</guimenuitem> 275 displays a dialog box with the number of characters, 276 words and lines in the current buffer. 277 </para> 278 <para> 279 <guimenu>Edit</guimenu>><guimenuitem>Complete Word</guimenuitem> (shortcut: 280 <keycombo><keycap>Control</keycap><keycap>B</keycap></keycombo>) searches the 281 current buffer for possible completions of the current word. 282 This feature be used to avoid retyping 283 previously entered identifiers in program source, for example. 284 </para> 285 <para> 286 If there is only one completion, it will be inserted into the buffer 287 immediately. 288 If multiple completions were found, they will be listed in a popup below 289 the caret position. To insert a completion from the list, either click it 290 with the mouse, 291 or select it using the <keycap>Up</keycap> and <keycap>Down</keycap> keys and 292 press <keycap>Enter</keycap>. To close the popup without inserting a 293 completion, press <keycap>Escape</keycap>. 294 </para> 295 </sect1> 296 <sect1 id="lines"><title>Working With Lines</title> 297 <para> 298 An entire line can be selected by triple-clicking with the mouse, 299 or using the 300 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Select 301 Line</guimenuitem> command (shortcut: 302 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycap>L</keycap>). 303 A selection that begins and ends on line boundaries can be created 304 by triple-clicking and dragging. 305 </para> 306 <para> 307 <guimenu>Edit</guimenu>><guimenuitem>Go to Line</guimenuitem> (shortcut: 308 <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>) displays an 309 input dialog box and moves the caret to the specified line number. 310 </para> 311 <para> 312 <guimenu>Edit</guimenu>><guimenuitem>Select Line Range</guimenuitem> 313 (shortcut 314 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 315 <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>) 316 selects all text between between two specified line numbers, inclusive. 317 </para> 318 <para> 319 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Join 320 Lines</guimenuitem> (shortcut: 321 <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>) 322 removes any whitespace from the start of the next line and joins it with 323 the current line. For example, invoking <guimenuitem>Join Lines</guimenuitem> 324 on the first line of the following Java code: 325 </para> 326 <screen>new Widget(Foo 327 .createDefaultFoo());</screen> 328 <para> 329 Will change it to: 330 </para> 331 <screen>new Widget(Foo.createDefaultFoo());</screen> 332 <para> 333 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Delete 334 Line</guimenuitem> 335 (shortcut: <keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo>) 336 deletes the current line. 337 </para> 338 <para> 339 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Delete 340 to Start Of Line</guimenuitem> 341 (shortcut: 342 <keycombo><keycap>Shift</keycap><keycap>Backspace</keycap></keycombo>) 343 deletes all text from the start of the current line to the caret. 344 </para> 345 <para> 346 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Delete 347 to End Of Line</guimenuitem> 348 (shortcut: 349 <keycombo><keycap>Shift</keycap><keycap>Delete</keycap></keycombo>) deletes 350 all text from the caret to the end of the current line. 351 </para> 352 <para> 353 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Remove 354 Trailing Whitespace</guimenuitem> 355 (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 356 <keycap>R</keycap>) removes all whitespace from the end of each selected line, or 357 the current line if there is no selection. 358 </para> 359 </sect1> 360 <sect1 id="paragraphs"><title>Working With Paragraphs</title> 361 <para> 362 As far as jEdit is concerned, <quote>paragraphs</quote> are delimited by 363 double newlines. This is also how <application>TeX</application> 364 defines a paragraph. Note that jEdit doesn't parse HTML files for 365 <quote><P></quote> tags, nor does it support paragraphs delimited only 366 by a leading indent. 367 </para> 368 <para> 369 Holding down <keycap>Control</keycap> in addition to <keycap>Up</keycap> 370 or <keycap>Down</keycap> 371 moves the caret to the previous and next paragraph, respectively. 372 As with other caret movement commands, holding down <keycap>Shift</keycap> 373 in addition to the above 374 extends the selection, a paragraph at a time. 375 </para> 376 <para> 377 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Select 378 Paragraph</guimenuitem> (shortcut: 379 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 380 <keycap>P</keycap>) 381 selects the paragraph containing the caret. 382 </para> 383 <para> 384 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Delete 385 Paragraph</guimenuitem> (shortcut: 386 <keycombo><keycap>Control</keycap><keycap>E</keycap> 387 </keycombo> <keycap>D</keycap>) 388 deletes the paragraph containing the caret. 389 </para> 390 <para> 391 <guimenu>Edit</guimenu>><guisubmenu>Text</guisubmenu>><guimenuitem>Format 392 Paragraph</guimenuitem> (shortcut: 393 <keycombo><keycap>Control</keycap><keycap>E</keycap> 394 </keycombo> <keycap>F</keycap>) splits and joins lines in the current 395 paragraph to make them fit within the wrap column position. See 396 <xref linkend="entering-text" /> for information and word wrap and 397 changing the wrap column. 398 </para> 399 </sect1> 400 <sect1 id="scrolling"><title>Scrolling</title> 401 <para> 402 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Scroll to 403 Current Line</guimenuitem> (shortcut: 404 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 405 <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>) centers the 406 line containing the caret on the screen. 407 </para> 408 <para> 409 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Center Caret 410 on Screen</guimenuitem> (shortcut: 411 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 412 <keycombo><keycap>Control</keycap><keycap>I</keycap></keycombo>) 413 moves the caret to the 414 line in the middle of the screen. 415 </para> 416 <para> 417 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Line 418 Scroll Up</guimenuitem> (shortcut: 419 <keycombo><keycap>Control</keycap><keycap>'</keycap></keycombo>) 420 scrolls the text area up by one line. 421 </para> 422 <para> 423 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Line 424 Scroll Down</guimenuitem> (shortcut: 425 <keycombo><keycap>Control</keycap><keycap>/</keycap></keycombo>) scrolls the 426 text area down by one line. 427 </para> 428 <para> 429 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Page 430 Scroll Up</guimenuitem> (shortcut: 431 <keycombo><keycap>Alt</keycap><keycap>'</keycap></keycombo>) scrolls the text 432 area up by one screenful. 433 </para> 434 <para> 435 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Page 436 Scroll Down</guimenuitem> (shortcut: 437 <keycombo><keycap>Alt</keycap><keycap>/</keycap></keycombo>) scrolls the text 438 area down by one screenful. 439 </para> 440 <para> 441 The above scrolling commands differ from the caret movement commands 442 in that they don't actually move the caret; they just change the 443 scroll bar position. 444 </para> 445 <para> 446 <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Synchronized 447 Scrolling</guimenuitem> is a check box menu item, that if selected, 448 forces scrolling performed in one text area to be propagated to all 449 other text areas in the current view. Invoking the command a second 450 time disables the feature. 451 </para> 452 </sect1> 453 <sect1 id="text-transfer"><title>Transferring Text</title> 454 <para> 455 jEdit provides a rich set of commands for moving and copying text 456 using <firstterm>registers</firstterm>. A register is a holding 457 area with a single-character name that can hold once piece of text at a time. 458 Registers are global to the editor; all buffers share the same set. With the 459 exception of the clipboard, register contents are only accessable inside 460 jEdit. 461 </para> 462 <para> 463 jEdit has three sets of commands for working with registers. 464 The <quote>quick copy</quote> and system clipboard features allow easy 465 access to two specific registers. A third set of commands allows access to 466 all other registers. 467 </para> 468 <sect2><title>Quick Copy</title> 469 <para> 470 Holding down the <keycap>Alt</keycap> key and clicking the left mouse button 471 in the text area inserts the most recently 472 selected text at the clicked location. If you have a three-button mouse, you 473 can simply click the middle mouse button, without holding down 474 <keycap>Alt</keycap>. 475 </para> 476 <para> 477 Internally, this is implemented by storing the most recently selected text 478 in the <filename>%</filename> register (recall that registers have 479 single-character names). 480 </para> 481 <sidebar><title>X Windows primary selection</title> 482 <para> 483 If jEdit is being run under Java 2 version 1.4 on Unix, you will be 484 able to transfer text with other X Windows applications using the 485 quick copy feature. On other platforms and Java versions, the contents 486 of the quick copy register are only accessable from within jEdit. 487 </para> 488 </sidebar> 489 </sect2> 490 <sect2><title>The System Clipboard</title> 491 <para> 492 Quick copy is very useful in many situations, but it has a number of 493 drawbacks; it requires the use of the mouse, it cannot be used to replace an 494 existing selection, and it cannot be used to transfer text between different 495 applications (unless you are using Java 2 version 1.4 on Unix). 496 </para> 497 <para> 498 The system clipboard, internally known as the <filename>$</filename> 499 register, does not have these limitations, but can be slightly less 500 convinient to use. 501 </para> 502 <para> 503 <guimenu>Edit</guimenu>><guimenuitem>Cut</guimenuitem> 504 (shortcut: <keycombo><keycap>Control</keycap><keycap>X</keycap></keycombo>) 505 places the selected text in the clipboard and removes it from the buffer. 506 </para> 507 <para> 508 <guimenu>Edit</guimenu>><guimenuitem>Copy</guimenuitem> 509 (shortcut: <keycombo><keycap>Control</keycap><keycap>C</keycap></keycombo>) 510 places the selected text in the clipboard and leaves it in the buffer. 511 </para> 512 <para> 513 <guimenu>Edit</guimenu>><guimenuitem>Cut Append</guimenuitem> 514 (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 515 <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo>) 516 appends the selected text to the clipboard, then removes it from the 517 buffer. After this command has been invoked, the clipboard will consist of 518 the former clipboard contents, followed by a newline, followed by the 519 selected text. 520 </para> 521 <para> 522 <guimenu>Edit</guimenu>><guimenuitem>Copy Append</guimenuitem> 523 (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 524 <keycombo><keycap>Control</keycap><keycap>A</keycap></keycombo>) 525 appends the selected text to the clipboard, and leaves it in the 526 buffer. After this command has been invoked, the clipboard will consist of 527 the former clipboard contents, followed by a newline, followed by the 528 selected text. 529 </para> 530 <para> 531 <guimenu>Edit</guimenu>><guimenuitem>Paste</guimenuitem> 532 (shortcut: <keycombo><keycap>Control</keycap><keycap>V</keycap></keycombo>) 533 inserts the clipboard contents in place of the selection (or at the 534 caret position, if there is no selection). 535 </para> 536 </sect2> 537 <sect2><title>General Register Commands</title> 538 <para> 539 These commands are slightly less convinient to use than the two methods of 540 transferring text described above, but have the advantage that they allow 541 any number of strings to be copied simultaneously. 542 </para> 543 <para> 544 These commands all expect a single-character 545 register name to be typed at the keyboard after the command is 546 invoked, and subsequently operate on that register. 547 Pressing <keycap>Escape</keycap> instead of specifying a register name 548 will cancel the operation. 549 </para> 550 <para> 551 <guimenu>Edit</guimenu>><guisubmenu>Registers</guisubmenu>><guimenuitem>Cut 552 to Register</guimenuitem> 553 (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo> 554 <keycombo><keycap>Control</keycap><keycap>X</keycap></keycombo> 555 <keycap><replaceable>key</replaceable></keycap>) 556 stores the selected text in the specified 557 register, removing it from the buffer. 558 </para> 559 <para> 560 <guimenu>Edit</guimenu>><guisubmenu>Registers</guisubmenu>><guimenuitem>Copy 561 to Register</guimenuitem> 562 (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo> 563 <keycombo><keycap>Control</keycap><keycap>C</keycap></keycombo> 564 <keycap><replaceable>key</replaceable></keycap>) 565 stores the selected text in the specified 566 register, leaving it in the buffer. 567 </para> 568 <para> 569 <guimenu>Edit</guimenu>><guisubmenu>Registers</guisubmenu>><guimenuitem>Cut 570 Append to Register</guimenuitem> 571 (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo> 572 <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo> 573 <keycap><replaceable>key</replaceable></keycap>) 574 adds the selected text to the existing contents of the specified 575 register, and removes it from the buffer. 576 </para> 577 <para> 578 <guimenu>Edit</guimenu>><guisubmenu>Registers</guisubmenu>><guimenuitem>Copy 579 Append to Register</guimenuitem> 580 (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo> 581 <keycombo><keycap>Control</keycap><keycap>A</keycap></keycombo> 582 <keycap><replaceable>key</replaceable></keycap>) 583 adds the selected text to the existing contents of the specified 584 register, without removing it from the buffer. 585 </para> 586 <para> 587 <guimenu>Edit</guimenu>><guisubmenu>Registers</guisubmenu>><guimenuitem>Paste 588 from Register</guimenuitem> 589 (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo> 590 <keycombo><keycap>Control</keycap><keycap>V</keycap></keycombo> 591 <keycap><replaceable>key</replaceable></keycap>) 592 replaces the selection with the 593 contents of the specified register. 594 </para> 595 <para> 596 <guimenu>Edit</guimenu>><guimenuitem>Paste Previous</guimenuitem> 597 (shortcut: 598 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 599 <keycombo><keycap>Control</keycap><keycap>V</keycap></keycombo>) 600 displays a dialog box listing recently copied and 601 pasted text. By default, the last 20 strings are remembered; this can be 602 changed in the <guibutton>General</guibutton> pane of the 603 <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem> 604 dialog box; see <xref linkend="global-opts" />. 605 </para> 606 <para> 607 <guimenu>Edit</guimenu>><guisubmenu>Registers</guisubmenu>><guimenuitem>View 608 Registers</guimenuitem> displays a dialog box for 609 viewing the contents of registers (including the clipboard). 610 </para> 611 </sect2> 612 </sect1> 613 <sect1 id="markers"><title>Markers</title> 614 <para> 615 Each buffer can have any number of <firstterm>markers</firstterm> defined, 616 pointing to 617 specific locations within that buffer. Each line in a buffer can have 618 at most one marker set pointing to it. Markers are persistent; they are 619 saved to 620 <filename>.<replaceable>filename</replaceable>.marks</filename>, where 621 <filename><replaceable>filename</replaceable></filename> is the file 622 name. (The dot prefix 623 makes the markers file hidden on Unix systems.) Marker 624 saving can be 625 disabled in the <guibutton>Loading and Saving</guibutton> pane of the 626 <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem> 627 dialog box; see <xref linkend="global-opts" />. 628 </para> 629 <para> 630 Markers are listed in the <guimenu>Markers</guimenu> menu; selecting a marker 631 from this menu is the simplest way to return to its location. 632 Each marker can optionally have a single-character shortcut; markers without 633 a shortcut can only be returned to using the menu, markers with a shortcut 634 can be accessed more quickly from the keyboard. 635 </para> 636 <para> 637 Lines which contain markers are indicated in the gutter with a highlight. 638 Moving the mouse over the highlight displays a tool tip showing the marker's 639 shortcut, if it has one. See <xref linkend="textarea" /> for information 640 about the gutter. 641 </para> 642 <para> 643 <guimenu>Markers</guimenu>><guimenuitem>Add/Remove Marker</guimenuitem> 644 (shortcut: 645 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 646 <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>) adds a 647 marker without a shortcut pointing to the current line. If a marker is 648 already set on the current line, the marker is removed instead. 649 If text is selected, 650 markers are added to the first and last line of each selection. 651 </para> 652 <para> 653 <guimenu>Markers</guimenu>><guimenuitem>Add Marker With 654 Shortcut</guimenuitem> 655 (shortcut: <keycombo><keycap>Control</keycap><keycap>T</keycap></keycombo> 656 <keycap><replaceable>key</replaceable></keycap>) 657 reads the next character entered at the keyboard, and adds a marker with that 658 shortcut pointing to the current line. If a previously-defined marker already 659 has that shortcut, it will no longer have that shortcut, but will remain 660 in the buffer. Pressing <keycap>Escape</keycap> instead of specifying a 661 marker shortcut after invoking the command will cancel the operation. 662 </para> 663 <para> 664 <guimenu>Markers</guimenu>><guimenuitem>Go to Marker</guimenuitem> 665 (shortcut: <keycombo><keycap>Control</keycap><keycap>Y</keycap></keycombo> 666 <keycap><replaceable>key</replaceable></keycap>) 667 reads the next character entered at the keyboard, and moves the caret to the 668 location of the marker with that shortcut. Pressing <keycap>Escape</keycap> 669 instead of specifying a marker 670 shortcut after invoking the command will cancel the operation. 671 </para> 672 <para> 673 <guimenu>Markers</guimenu>><guimenuitem>Select to Marker</guimenuitem> 674 (shortcut: <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo> 675 <keycap><replaceable>key</replaceable></keycap>) 676 reads the next character entered at the keyboard, and extends 677 the selection to the location of the marker with that shortcut. 678 Pressing <keycap>Escape</keycap> instead of specifying a marker 679 shortcut after invoking the command will cancel the operation. 680 </para> 681 <para> 682 <guimenu>Markers</guimenu>><guimenuitem>Swap Caret and 683 Marker</guimenuitem> (shortcut: 684 <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo> 685 <keycap><replaceable>key</replaceable></keycap>) 686 reads the next character entered at the keyboard, and swaps the 687 position of the caret with the location of the marker with that shortcut. 688 Pressing <keycap>Escape</keycap> instead of specifying a marker 689 shortcut after invoking the command will cancel the operation. 690 </para> 691 <para> 692 <guimenu>Markers</guimenu>><guimenuitem>Go to Previous 693 Marker</guimenuitem> 694 (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 695 <keycap>,</keycap>) goes 696 to the marker immediately before the caret position. 697 </para> 698 <para> 699 <guimenu>Markers</guimenu>><guimenuitem>Go to Next Marker</guimenuitem> 700 (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 701 <keycap>.</keycap>) 702 goes to the marker immediately after the caret position. 703 </para> 704 <para> 705 <guimenu>Markers</guimenu>><guimenuitem>Remove All Markers</guimenuitem> 706 removes all markers set in the current buffer. 707 </para> 708 </sect1> 709 <sect1 id="search-replace"><title>Search and Replace</title> 710 <sect2><title>Searching For Text</title> 711 <para> 712 <guimenu>Search</guimenu>><guimenuitem>Find</guimenuitem> (shortcut: 713 <keycombo><keycap>Control</keycap><keycap>F</keycap></keycombo>) displays 714 the search and replace dialog box. If text is selected and the selection 715 does not span a line break, the selected text becomes the default search 716 string. 717 </para> 718 <para> 719 If the selection does span one or more line breaks, the default 720 search string is empty, and the <guibutton>Search in Selection</guibutton> 721 and <guibutton>HyperSearch</guibutton> 722 buttons are pre-selected. Note that finding the next or previous 723 ocurrence cannot be constrained to a selected range; only 724 replacement and HyperSearch can be (see <xref linkend="hypersearch" />). 725 </para> 726 <para> 727 The search string can be entered in the <guibutton>Search for</guibutton> 728 text field. This text field remembers previously entered strings; see 729 <xref linkend="history" /> for details. 730 </para> 731 <para> 732 The search can be made case insensitive (for example, searching for 733 <quote>Hello</quote> will match <quote>hello</quote>, <quote>HELLO</quote> 734 and <quote>HeLlO</quote>) by selecting the <guibutton>Ignore 735 case</guibutton> check box. Regular expressions may be used to match inexact 736 sequences of text if the <guibutton>Regular expressions</guibutton> check 737 box is selected; see <xref linkend="regexps" /> for more information about 738 regular expressions. Note that regular expressions can only be used when 739 searching forwards. 740 </para> 741 <para> 742 Clicking <guibutton>Find</guibutton> will locate the next (or previous, if 743 searching backwards) occurrence of the 744 search string after the caret position. If the 745 <guibutton>Keep dialog</guibutton> check box is selected, the dialog box 746 will remain open; otherwise, it will be closed after the search string is 747 located. 748 </para> 749 <para> 750 If no occurrences could be found and the 751 <guibutton>Auto wrap</guibutton> check box is selected, the search will 752 automatically be restarted and a message will be shown in the status bar 753 to indicate that. If the check box is not selected, a dialog 754 box will be displayed, offering to restart the search. 755 </para> 756 <para> 757 <guimenu>Search</guimenu>><guimenuitem>Find Next</guimenuitem> (shortcut: 758 <keycombo><keycap>Control</keycap><keycap>G</keycap></keycombo>) locates the 759 next occurrence of the most recent search string without displaying the 760 search and replace dialog box. 761 </para> 762 <para> 763 <guimenu>Search</guimenu>><guimenuitem>Find Previous</guimenuitem> 764 (shortcut: <keycombo><keycap>Control</keycap><keycap>H</keycap></keycombo>) 765 locates the previous occurrence of the most recent search string without 766 displaying the search and replace dialog box. 767 </para> 768 </sect2> 769 <sect2><title>Replacing Text</title> 770 <para> 771 Occurrences of the search string can be replaced with either a replacement 772 string or the result of a BeanShell script snippet. Two radio buttons in 773 the search and replace dialog box can be used to choose between these two 774 behaviors. 775 </para> 776 <para> 777 The replace string text field remembers previously entered strings; 778 see <xref linkend="history" /> for details. 779 </para> 780 <para> 781 Clicking <guibutton>Replace</guibutton> will perform a replacement in each 782 text selection. 783 Clicking <guibutton>Replace & Find</guibutton> will perform a 784 replacement in each text selection and locate the next occurrence of the 785 search string. Clicking <guibutton>Replace All</guibutton> will perform a 786 replacement in each buffer to be searched. 787 </para> 788 <para> 789 In text replacement mode, the search string is replaced with the replacement 790 string. If regular expressions are enabled, positional parameters 791 (<literal>$0</literal>, <literal>$1</literal>, <literal>$2</literal>, and so 792 on) can be used to insert the contents of matched subexpressions in the 793 replacement text; see <xref linkend="regexps" /> for more information. 794 </para> 795 <para> 796 In BeanShell replacement mode, the search string is replaced with the return 797 value of a BeanShell snippet. The following predefined variables can be 798 referenced in the snippet: 799 </para> 800 <itemizedlist><listitem><para><varname>_0</varname> -- the text to be 801 replaced</para> 802 </listitem><listitem><para><varname>_1</varname> - <varname>_9</varname> -- 803 if regular expressions are enabled, these contain the values of matched 804 subexpressions. 805 </para></listitem></itemizedlist> 806 <para> 807 BeanShell syntax and features are covered in great detail in 808 <xref linkend="writing-macros-part" />, but here are some examples: 809 </para> 810 <informalexample> 811 <para> 812 To convert all HTML tags to lower case, search 813 for the following regular expression: 814 </para> 815 <programlisting><![CDATA[<(.*?)>]]></programlisting> 816 <para> 817 Replacing it with the following BeanShell snippet: 818 </para> 819 <programlisting><![CDATA["<" + _1.toLowerCase() + ">"]]></programlisting> 820 </informalexample> 821 <informalexample> 822 <para> 823 To replace arithmetic expressions between curly braces with their result, 824 search for the following regular expression: 825 </para> 826 <programlisting><![CDATA[\{(.+)\}]]></programlisting> 827 <para> 828 Replacing it with the following BeanShell snippet: 829 </para> 830 <programlisting><![CDATA[eval(_1)]]></programlisting> 831 </informalexample> 832 <para> 833 These two examples only scratch the surface; the possibilities are endless. 834 </para> 835 </sect2> 836 <sect2 id="hypersearch"><title>HyperSearch</title> 837 <para> 838 If the <guibutton>HyperSearch</guibutton> check box in the search and 839 replace dialog box is selected, clicking <guibutton>Find</guibutton> will 840 list all occurrences of the search string, rather than locating them one 841 by one. 842 </para> 843 <para> 844 By default, HyperSearch results are shown in a floating window; 845 the window can be set to dock into the view 846 in the <guibutton>Docking</guibutton> pane of the 847 <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem> 848 dialog box; see <xref linkend="docking" />. 849 </para> 850 <para> 851 Running searches can be stopped in the 852 <guimenu>Utilities</guimenu>><guimenuitem>I/O Progress 853 Monitor</guimenuitem> dialog box. 854 </para> 855 </sect2> 856 <sect2><title>Multiple File Search</title> 857 <para> 858 Searching, replacement and HyperSearch can also be performed in all 859 open buffers or all files in a directory. 860 </para> 861 <para> 862 If the <guibutton>All buffers</guibutton> radio button in the search and 863 replace dialog box is selected, all open buffers whose names match the glob 864 pattern 865 entered in the <guibutton>Filter</guibutton> text field will be searched. 866 See <xref linkend="globs" /> for more information about glob patterns. 867 </para> 868 <para> 869 If the <guibutton>Directory</guibutton> radio button is selected, all files 870 in the directory whose names match the glob will be searched. The 871 directory to search in can either be entered in the 872 <guibutton>Directory</guibutton> text field, or chosen in a file selector 873 dialog box by clicking <guibutton>Choose</guibutton>. 874 If the <guibutton>Search subdirectories</guibutton> check box is selected, 875 all subdirectories of the specified directory will also be searched. Keep 876 in mind that searching through directories with many files can take 877 a long time and consume a large amount of memory. 878 </para> 879 <para> 880 The <guibutton>Directory</guibutton> and <guibutton>Filter</guibutton> 881 text fields remember previously entered strings; see <xref linkend="history" /> 882 for details. 883 </para> 884 <para> 885 Note that selecting the <guibutton>All Buffers</guibutton> or 886 <guibutton>Directory</guibutton> radio buttons also selects the 887 <guibutton>HyperSearch</guibutton> check box. This is merely for 888 convinience, however; normal searching is supported as well. 889 </para> 890 <para> 891 Two convinience commands are provided for performing multiple file searches. 892 </para> 893 <para> 894 <guimenu>Search</guimenu>><guimenuitem>Search in Open 895 Buffers</guimenuitem> (shortcut: 896 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 897 <keycombo><keycap>Control</keycap><keycap>B</keycap></keycombo>) displays 898 the search and replace dialog box, and selects the <guibutton>All 899 buffers</guibutton> radio button. 900 </para> 901 <para> 902 <guimenu>Search</guimenu>><guimenuitem>Search in Directory</guimenuitem> 903 (shortcut: 904 <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> 905 <keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo>) displays 906 the search and replace dialog box, and selects the 907 <guibutton>Directory</guibutton> radio button. 908 </para> 909 </sect2> 910 <sect2><title>The Search Bar</title> 911 <para> 912 The search bar at the top of the view provides a convenient way to 913 perform simple searches without 914 opening the search and replace dialog box first. Neither multiple file 915 search nor replacement can be done from the search bar. 916 The search bar remembers 917 previously entered strings; see <xref linkend="history" /> for details. 918 </para> 919 <para> 920 Unless the <guibutton>HyperSearch</guibutton> check box is selected, the 921 search bar will perform an <firstterm>incremental search</firstterm>. 922 In incremental search mode, the first occurrence of the search 923 string is located in the current buffer as is it is being typed. 924 Pressing <keycap>Enter</keycap> 925 and <keycombo><keycap>Shift</keycap><keycap>Enter</keycap></keycombo> 926 searches for the next and previous occurrence, respectively. 927 Once the desired occurrence has been found, press <keycap>Escape</keycap> 928 to return keyboard focus to the text area. 929 </para> 930 <para> 931 If the <guibutton>HyperSearch</guibutton> check box is selected, entering a 932 search string and pressing <keycap>Enter</keycap> will perform a 933 HyperSearch. 934 </para> 935 <para> 936 <guimenu>Search</guimenu>><guimenuitem>Incremental Search</guimenuitem> 937 (shortcut: <keycombo><keycap>Control</keycap><keycap>,</keycap></keycombo>) 938 moves keyboard focus to the search bar. If text is selected when this 939 command is invoked, the selection is inserted into the search bar 940 automatically. 941 </para> 942 <para> 943 <guimenu>Search</guimenu>><guimenuitem>Quick HyperSearch</guimenuitem> 944 (shortcut: <keycombo><keycap>Control</keycap><keycap>.</keycap></keycombo>) 945 moves keyboard focus to the search bar and pre-selects the 946 <guibutton>HyperSearch</guibutton> check box. If text is selected when this 947 command is invoked, a HyperSearch for that text is performed immediately. 948 </para> 949 <para> 950 The 951 <guimenu>Search</guimenu>><guimenuitem>Incremental Search 952 for Word</guimenuitem> 953 (shortcut: <keycombo><keycap>Alt</keycap><keycap>,</keycap></keycombo>) 954 and <guimenu>Search</guimenu>><guimenuitem>Quick HyperSearch 955 for Word</guimenuitem> 956 (shortcut: <keycombo><keycap>Alt</keycap><keycap>.</keycap></keycombo>) 957 commands perform an incremental search and HyperSearch, respectively, 958 for the word under the caret. 959 </para> 960 <para> 961 The search bar can be disabled in the <guibutton>General</guibutton> pane of 962 the <guimenu>Utilities</guimenu>><guimenuitem>Global 963 Options</guimenuitem> dialog box. 964 </para> 965 <note> 966 <para> 967 Incremental searches cannot be not recorded in macros. Use the 968 search and replace dialog box instead. See <xref linkend="using-macros" /> 969 for information about macros. 970 </para> 971 </note> 972 </sect2> 973 </sect1> 974</chapter>