/jEdit/tags/jedit-4-3-pre5/doc/users-guide/macro-index.xml
XML | 733 lines | 623 code | 105 blank | 5 comment | 0 complexity | 9b620a86d9649ea8d20a90d03204b8d3 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
1<!-- jEdit 4.0 Macro Guide, (C) 2001 John Gellene -->
2
3<!-- jEdit buffer-local properties: -->
4<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2: -->
5<!-- :xml.root=users-guide.xml: -->
6
7<!-- covers index to installed macro set -->
8
9<appendix id="macro-index"><title>Macros Included With jEdit</title>
10
11<para>
12 jEdit comes with a large number of sample macros that perform a variety
13 of tasks. The following index provides short descriptions of each macro,
14 in some cases accompanied by usage notes.
15</para>
16
17<para>
18 In addition to the macros included with jEdit,
19 a very large collection of user-contributed macros is available
20 in the <quote>Downloads</quote> section of the
21 <ulink url="http://community.jedit.org">community.jedit.org</ulink>
22 web site. There are detailed descriptions for
23 each macro as well as a search facility.
24</para>
25
26<sect1 id="macros-clipboard"><title>Clipboard Macros</title>
27<para>
28 These macros copy or cut text to the clipboard.
29</para>
30
31<itemizedlist>
32
33<listitem>
34 <para><filename>Copy_Lines_Containing.bsh</filename></para>
35 <para>
36 Copies all lines from the current buffer, containing a
37 user-supplied string, to the clipboard.
38 </para>
39</listitem>
40
41<listitem>
42 <para><filename>Cut_Lines_Containing.bsh</filename></para>
43 <para>
44 Cuts all lines from the current buffer, containing a
45 user-supplied string, to the clipboard.
46 </para>
47</listitem>
48
49<listitem>
50 <para><filename>Copy_Selection_or_Line.bsh</filename></para>
51 <para>
52 If no text is selected, the current line is copied to
53 the clipboard, otherwise the selected text is copied
54 to the clipboard. Some editors have this has the default copy behavior. To achieve the same effect in jEdit, bind this macro to <keycap>C+c</keycap> in the <guibutton>Shortcuts</guibutton> pane of the <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem> dialog box.
55 </para>
56</listitem>
57
58<listitem>
59 <para><filename>Cut_Selection_or_Line.bsh</filename></para>
60 <para>
61 If no text is selected, the current line is cut to the clipboard,
62 otherwise the selected text is cut to the clipboard. Some editors have this has the default cut behavior. To achieve the same effect in jEdit, bind this macro to <keycap>C+x</keycap> in the <guibutton>Shortcuts</guibutton> pane of the <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem> dialog box.
63 </para>
64</listitem>
65
66<listitem>
67<para><filename>Copy_Visible_Lines.bsh</filename></para>
68<para>Copies the visible lines from the current
69 buffer to the Clipboard. Lines that are not visible
70 becuase they are folded are not copied.
71 </para>
72</listitem>
73
74</itemizedlist>
75
76</sect1>
77
78<sect1 id="macros-editing"><title>Editing Macros</title>
79<para>
80 These macros automate various text editing tasks.
81</para>
82<itemizedlist>
83
84<listitem>
85 <para><filename>Emacs_Next_Line.bsh</filename></para>
86 <para>
87 Moves the cursor to the next line, centering
88 the current line in the middle of the text area
89 if the cursor is at the bottom of the text area.
90 </para>
91</listitem>
92
93<listitem>
94 <para><filename>Emacs_Previous_Line.bsh</filename></para>
95 <para>
96 Moves the cursor to the previous line, centering
97 the current line in the middle of the text area
98 if the cursor is at the top of the text area.
99 </para>
100 </listitem>
101
102
103<listitem>
104 <para><filename>Go_to_Column.bsh</filename></para>
105 <para>
106 Prompts the user for a column position on the
107 current line, then moves the caret there.
108 </para>
109</listitem>
110
111<listitem>
112 <para><filename>Greedy_Backspace.bsh</filename></para>
113 <para>
114 If buffer is using soft tabs, this macro will backspace
115 to the previous tab stop, if all characters between the
116 caret and the tab stop are spaces. In all other cases a
117 single character is removed.
118 </para>
119</listitem>
120
121<listitem>
122 <para><filename>Greedy_Delete.bsh</filename></para>
123 <para>
124 If a buffer is using soft tabs, this macro will
125 delete tabSize number of spaces, if all the characters
126 between the caret and the next tab stop are spaces. In
127 all other cases a single character is deleted.
128 </para>
129</listitem>
130
131<listitem>
132 <para><filename>Greedy_Left.bsh</filename></para>
133 <para>
134 If a buffer is using soft tabs, this macro
135 will move the caret tabSize spaces to the left,
136 if all the characters between the caret and the previous
137 tab stop are all spaces. In all other cases, the caret
138 is moved a single character to the left.
139 </para>
140</listitem>
141
142<listitem>
143 <para><filename>Greedy_Right.bsh</filename></para>
144 <para>
145 If a buffer is using soft tabs, this macro will
146 move the caret tabSize spaces to the right,
147 if all the characters between the caret and the next
148 tab stop are all spaces. In all other cases, the caret
149 is moved a single character to the right.
150 </para>
151</listitem>
152
153<listitem>
154 <para><filename>Keywords_to_Upper_Case.bsh</filename></para>
155 <para>
156 Converts all keywords in the current buffer to upper case.
157 </para>
158</listitem>
159
160<listitem>
161 <para><filename>Mode_Switcher.bsh</filename></para>
162 <para>
163 Displays a modal dialog with the current buffer's mode in a text field,
164 allowing one to change the mode by typing in its name.
165 </para>
166 <para>
167 <keycap>ENTER</keycap> selects the current mode; if the text is not a
168 valid mode, the dialog still dismisses, but a warning is logged to the
169 activity log.
170 <keycap>ESACPE</keycap> closes the dialog with no further action.
171 <keycap>TAB</keycap> attempts to auto-complete the mode name. Pressing
172 <keycap>TAB</keycap> repeatedly cycles through the possible completions.
173 <keycap>SHIFT-TAB</keycap> cycles through the completions in reverse.
174 </para>
175</listitem>
176
177<listitem>
178 <para><filename>Move_Line_Down.bsh</filename></para>
179 <para>Moves the current line down one, with automatic
180 indentation.</para>
181 </listitem>
182
183<listitem>
184 <para><filename>Move_Line_Up.bsh</filename></para>
185 <para>Moves the current line up one, with automatic
186 indentation.</para>
187 </listitem>
188
189</itemizedlist>
190
191</sect1>
192
193<sect1 id="macros-files"><title>File Management Macros</title>
194<para>
195 These macros automate the opening and closing of files.
196</para>
197
198<itemizedlist>
199
200<listitem>
201 <para><filename>Browse_Directory.bsh</filename></para>
202 <para>
203 Opens a directory supplied by the user in the file system
204 browser.
205 </para>
206</listitem>
207
208<listitem>
209 <para><filename>Buffer_Switcher.bsh</filename></para>
210 <para>
211 Displays a modal dialog listing all open buffers,
212 allowing one to switch to and/or close buffers.
213 <keycap>ENTER</keycap> switches to a buffer and closes the dialog,
214 <keycap>DELETE</keycap> closes a buffer, <keycap>SPACE</keycap>
215 switches to a buffer but does not close the dialog.
216 </para>
217</listitem>
218
219<listitem>
220 <para><filename>Close_All_Except_Active.bsh</filename></para>
221 <para>
222 Closes all files except the current buffer.
223 </para>
224 <para>
225 Prompts the user to save any buffer containing unsaved changes.
226 </para>
227</listitem>
228
229<listitem>
230 <para><filename>Copy_Path_to_Clipboad.bsh</filename></para>
231 <para>Copies the current buffer's path
232 to the clipboard.
233 </para>
234</listitem>
235
236<listitem>
237 <para><filename>Copy_Name_to_Clipboad.bsh</filename></para>
238 <para>Copies the current buffer's filename
239 to the clipboard.
240 </para>
241</listitem>
242
243<listitem>
244 <para><filename>Delete_Current.bsh</filename></para>
245 <para>
246 Deletes the current buffer's file on disk, but
247 doesn't close the buffer.
248 </para>
249</listitem>
250
251<listitem>
252 <para><filename>Glob_Close.bsh</filename></para>
253 <para>
254 Closes all open buffers matching a given glob pattern.
255 </para>
256</listitem>
257
258<listitem>
259 <para><filename>Insert_Selection.bsh</filename></para>
260 <para>Assumes the current selection is
261 file path and tries replaces the selection with the
262 contents of the file. Does nothing if no text is
263 selected or the selection spans multiple lines.
264 </para>
265</listitem>
266
267<listitem>
268 <para><filename>Next_Dirty_Buffer.bsh</filename></para>
269 <para>Switches to the next dirty buffer, if there is one.</para>
270</listitem>
271
272<listitem>
273 <para><filename>Open_Path.bsh</filename></para>
274 <para>
275 Opens the file supplied by the user in an input dialog.
276 </para>
277</listitem>
278
279<listitem>
280 <para><filename>Open_Selection.bsh</filename></para>
281 <para>
282 Opens the file named by the current buffer's selected text.
283 </para>
284</listitem>
285
286<listitem>
287 <para><filename>Toggle_ReadOnly.bsh</filename></para>
288 <para>
289 Toggles a local file's read-only flag. Uses platform-specific commands, so it only works on Windows, Unix and MacOS X.
290 </para>
291</listitem>
292
293</itemizedlist>
294
295</sect1>
296
297<sect1 id="macros-interface"><title>User Interface Macros</title>
298
299<para>
300 Description.
301</para>
302
303<itemizedlist>
304
305<listitem>
306 <para><filename>Decrease_Font_Size.bsh</filename></para>
307 <para>
308 Decreases the font size in the gutter and text area by 1 point.
309 </para>
310</listitem>
311
312<listitem>
313 <para><filename>Increase_Font_Size.bsh</filename></para>
314 <para>
315 Increases the font size in the gutter and text area by 1 point.
316 </para>
317</listitem>
318
319<listitem>
320 <para><filename>Open_Context_Menu.bsh</filename></para>
321 <para>
322 Opens the text area context menu just below and to
323 the right of the caret.
324 </para>
325</listitem>
326
327<listitem>
328 <para><filename>Toggle_Bottom_Docking_Area.bsh</filename></para>
329 <para>
330 Expands or collapses the bottom docking area,
331 depending on it's current state.
332 </para>
333</listitem>
334
335<listitem>
336 <para><filename>Toggle_Left_Docking_Area.bsh</filename></para>
337 <para>
338 Expands or collapses the left docking area,
339 depending on it's current state.
340 </para>
341</listitem>
342
343<listitem>
344 <para><filename>Toggle_Right_Docking_Area.bsh</filename></para>
345 <para>
346 Expands or collapses the right docking area,
347 depending on it's current state.
348 </para>
349</listitem>
350
351<listitem>
352 <para><filename>Toggle_Top_Docking_Area.bsh</filename></para>
353 <para>
354 Expands or collapses the top docking area,
355 depending on it's current state.
356 </para>
357</listitem>
358
359</itemizedlist>
360
361</sect1>
362
363<sect1 id="macros-java"><title>Java Code Macros</title>
364<para>
365 These macros handle text formatting and generation tasks that are
366 particularly useful in writing Java code.
367</para>
368
369<itemizedlist>
370
371<listitem>
372 <para><filename>Create_Constructor.bsh</filename></para>
373 <para>
374 Inserts constructor for the class at the current caret position.
375 </para>
376</listitem>
377
378<listitem>
379 <para><filename>Get_Class_Name.bsh</filename></para>
380 <para>
381 Inserts a Java class name based upon the buffer's file name.
382 </para>
383</listitem>
384
385<listitem>
386 <para><filename>Get_Package_Name.bsh</filename></para>
387 <para>
388 Inserts a plausible Java package name for the current buffer.
389 </para>
390 <para>
391 The macro compares the buffer's path name with the elements of the
392 classpath being used by the jEdit session. An error message will be
393 displayed if no suitable package name is found. This macro will not
394 work if jEdit is being run as a JAR file without specifying a
395 classpath; in that case the classpath seen by the macro consists
396 solely of the JAR file.
397 </para>
398</listitem>
399
400<listitem>
401 <para><filename>Java_File_Save.bsh</filename></para>
402 <abstract><para>Acts as a wrapper script to the Save As action. If the buffer
403 is a new file, it scans the first 250 lines for a Java class or interface
404 declaration. On finding one, it extracts the appropriate filename to be
405 used in the Save As dialog.</para></abstract>
406 </listitem>
407
408<listitem>
409 <para><filename>Make_Get_and_Set_Methods.bsh</filename></para>
410 <para>
411 Creates <function>getXXX()</function> or <function>setXXX()</function>
412 methods that can be pasted into the buffer text.
413 </para>
414 <para>
415 This macro presents a dialog that will <quote>grab</quote> the names
416 of instance variables from the caret line of the current buffer
417 and paste a corresponding <function>getXXX()</function> or
418 <function>setXXX()</function> method to one of two text areas in the
419 dialog. The text can be edited in the dialog and then pasted into the
420 current buffer using the <guilabel>Insert...</guilabel> buttons. If
421 the caret is set to a line containing something other than an instance
422 variable, the text grabbing routine is likely to generate nonsense.
423 </para>
424 <para>
425 As explained in the notes accompanying the source code, the macro
426 uses a global variable which can be set to configure the macro to work
427 with either Java or C++ code. When set for use with C++ code,
428 the macro will also write (in commented text) definitions of
429 <function>getXXX()</function> or <function>setXXX()</function>
430 suitable for inclusion in a header file.
431 </para>
432</listitem>
433
434<listitem>
435 <para><filename>Preview_Javadoc_of_Buffer.bsh</filename></para>
436 <para>
437 Create and display API documentation for the current buffer.
438 </para>
439 <para>
440 The macro includes various configuration variables you can change; see the comment at the beginning of the macro source for details.
441 </para>
442 </listitem>
443
444</itemizedlist>
445
446</sect1>
447
448<sect1 id="macros-misc"><title>Miscellaneous Macros</title>
449<para>
450 While these macros do not fit easily into the other categories, they all provide
451 interesting and useful functions.
452</para>
453
454<itemizedlist>
455
456<listitem>
457 <para><filename>Display_Abbreviations.bsh</filename></para>
458 <para>
459 Displays the abbreviations registered for each of jEdit's
460 editing modes.
461 </para>
462 <para>
463 The macro provides a read-only view of the abbreviations
464 contained in the <quote>Abbreviations</quote> option pane. Pressing
465 a letter key will scroll the table to the first entry beginning with
466 that letter. A further option is provided to write a selected mode's
467 abbreviations or all abbreviations in a text buffer for printing as a
468 reference. Notes in the source code listing point out some display options
469 that are configured by modifying global variables.
470 </para>
471</listitem>
472
473<listitem>
474 <para><filename>Display_Actions.bsh</filename></para>
475 <para>
476 Displays a list of all the actions known to jEdit categorised by
477 their action set.
478 </para>
479 <para>
480 This macro can be a useful reference if you want to use the jEdit 4.2 action bar.
481 </para>
482</listitem>
483
484<listitem>
485 <para><filename>Display_Character_Code.bsh</filename></para>
486 <para>
487 Display int and hex values for the character at the caret,
488 in the status bar.
489 </para>
490</listitem>
491
492<listitem>
493 <para><filename>Display_Shortcuts.bsh</filename></para>
494 <para>
495 Displays a sorted list of the keyboard shortcuts currently in effect.
496 </para>
497 <para>
498 The macro provides a combined read-only view of command, macro
499 and plugin shortcuts. Pressing a letter key will
500 scroll the table to the first entry beginning with that letter.
501 A further option is provided to write the shortcut assignments in a
502 text buffer for printing as a reference. Notes in the source code
503 listing point out some display options that are configured by
504 modifying global variables.
505 </para>
506</listitem>
507
508<listitem>
509 <para><filename>Evaluate_Buffer_in_BeanShell.bsh</filename></para>
510 <para>
511 Evaluates contents of current buffer as a BeanShell script,
512 and opens a new
513 buffer to receive any text output.
514 </para>
515 <para>
516 This is a quick way to test a macro script even before its text
517 is saved to a file. Opening a new buffer for output is a precaution
518 to prevent the macro from inadvertently erasing or overwriting
519 itself. BeanShell scripts that operate on the contents of the
520 current buffer will not work meaningfully when tested using this
521 macro.
522 </para>
523</listitem>
524
525<listitem>
526 <para><filename>Hex_Convert.bsh</filename></para>
527 <para>
528 Converts byte characters to their hex equivalent, and vice versa.
529 </para>
530</listitem>
531
532<listitem>
533 <para><filename>HyperSearch_Results_to_Buffer.bsh</filename></para>
534 <para>
535 Writes HyperSeach results to a new buffer.
536 </para>
537</listitem>
538
539
540<listitem>
541 <para><filename>Include_Guard.bsh</filename></para>
542 <para>
543 Intended for C/C++ header files, this macro inserts a preprocessor
544 directive in the current buffer to ensure that the header is
545 included only once per compilation unit.
546 </para>
547 <para>
548 To use the macro, first place the caret at the beginning of the
549 header file before any uncommented text. The macro will return to
550 this position upon completion. The defined term that triggers the
551 <quote>include guard</quote> is taken from the buffer's name.
552 </para>
553</listitem>
554
555<listitem>
556 <para><filename>Make_Bug_Report.bsh</filename></para>
557 <para>
558 Creates a new buffer with installation and error information
559 extracted from the activity log.
560 </para>
561 <para>
562 The macro extracts initial messages written to the activity log
563 describing the user's operating system, JDK, jEdit version and
564 installed plugins. It then appends the last set of error messages
565 written to the activity log. The new text buffer can be saved and
566 attached to an email message or a bug report made on SourceForge.
567 </para>
568</listitem>
569
570<listitem>
571 <para><filename>Run_Script.bsh</filename></para>
572 <para>
573 Runs script using interpreter based upon buffer's editing mode
574 (by default, determined using file extension). You must have the
575 appropriate interpreter (such as Perl, Python, or Windows Script Host)
576 installed on your system.
577 </para>
578</listitem>
579
580<listitem>
581 <para><filename>Show_Threads.bsh</filename></para>
582 <para>
583 Displays in a tree format all running Java threads of the current
584 Java Virtual Machine.
585 </para>
586</listitem>
587
588</itemizedlist>
589
590</sect1>
591
592<sect1 id="macros-properties"><title>Property Macros</title>
593<para>
594 These macros produce lists or tables containing properties
595 used by the Java platform or jEdit itself.
596</para>
597
598
599<itemizedlist>
600
601<listitem>
602 <para><filename>Insert_Buffer_Properties.bsh</filename></para>
603 <para>
604 Inserts buffer-local properties into the current buffer.
605 </para>
606 <para>
607 If the buffer's
608 mode has a line comment defined, or comment start and end
609 defined, the inserted properties will be commented out.
610 </para>
611</listitem>
612
613<listitem>
614 <para><filename>jEdit_Properties.bsh</filename></para>
615 <para>
616 Writes an unsorted list of jEdit properties in a new buffer.
617 </para>
618</listitem>
619
620<listitem>
621 <para><filename>Look_and_Feel_Properties.bsh</filename></para>
622 <para>
623 Writes an unsorted list of the names of Java Look and Feel
624 properties in a new buffer.
625 </para>
626</listitem>
627
628<listitem>
629 <para><filename>System_Properties.bsh</filename></para>
630 <para>
631 Writes an unsorted list of all Java system properties in a new
632 buffer.
633 </para>
634</listitem>
635
636</itemizedlist>
637
638</sect1>
639
640<sect1 id="macros-text"><title>Text Macros</title>
641<para>
642 These macros generate various forms of formatted text.
643</para>
644
645<itemizedlist>
646
647<listitem>
648 <para><filename>Add_Prefix_and_Suffix.bsh</filename></para>
649 <para>
650 Adds user-supplied <quote>prefix</quote> and <quote>suffix</quote>
651 text to each line in a group of selected lines.
652 </para>
653 <para>
654 Text is added after leading whitespace and before trailing whitespace.
655 A dialog window receives input and <quote>remembers</quote> past entries.
656 </para>
657</listitem>
658
659<listitem>
660 <para><filename>Color_Picker.bsh</filename></para>
661 <para>
662 Displays a color picker and inserts the selected color in
663 hexadecimal format, prefixed with a <quote>#</quote>.
664 </para>
665</listitem>
666
667<listitem>
668 <para><filename>Duplicate_Line.bsh</filename></para>
669 <para>
670 Duplicates the line on which the caret lies immediately
671 beneath it and moves the caret to the new line.
672 </para>
673</listitem>
674
675<listitem>
676 <para><filename>Insert_Date.bsh</filename></para>
677 <para>
678 Inserts the current date and time in the current buffer.
679 </para>
680 <para>
681 The inserted text includes a representation of the time in the
682 <quote>Internet Time</quote> format.
683 </para>
684</listitem>
685
686<listitem>
687 <para><filename>Insert_Tag.bsh</filename></para>
688 <para>
689 Inserts a balanced pair of HTML/SGML/XML markup tags as supplied
690 in an input dialog. The tags will surround any selected text.
691 </para>
692</listitem>
693
694<listitem>
695 <para><filename>Next_Char.bsh</filename></para>
696 <para>
697 Finds next occurrence of character on current line.
698 </para>
699 <para>
700 The macro takes the next character typed after macro execution
701 as the character being searched. That character is not
702 displayed. If the character does not appear in the balance of
703 the current line, no action occurs.
704 </para>
705 <para>
706 This macro illustrates the use of
707 <function>InputHandler.readNextChar()</function> as a means of
708 obtaining user input. See <xref linkend="macro-tips-single-char"
709 />.
710 </para>
711</listitem>
712
713<listitem>
714 <para><filename>Reverse_Lines.bsh</filename></para>
715 <para>
716 Reverses the selected lines or the entire buffer if no
717 lines are selected. Does not support Rectangular
718 Selections.
719 </para>
720</listitem>
721
722<listitem>
723 <para><filename>Single_Space_Buffer.bsh</filename></para>
724 <para>
725 Removes every second line, if they are all blank.
726 </para>
727</listitem>
728
729</itemizedlist>
730</sect1>
731
732</appendix>
733