/jEdit/tags/jedit-4-1-pre5/doc/users-guide/macro-index.xml
XML | 418 lines | 357 code | 57 blank | 4 comment | 0 complexity | bdab41ed2cfa4b3297c1d3b5e97aa1cf 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
6<!-- covers index to installed macro set -->
7
8<appendix id="macro-index"><title>Macros Included With jEdit</title>
9
10<para>
11 jEdit comes with a large number of sample macros that perform a variety
12 of tasks. The following index provides short descriptions of each macro,
13 in some cases accompanied by usage notes.
14</para>
15
16<para>
17 Macros from earlier versions of jEdit can be found, as well as
18 a large number of macros contributed by users, can be found in the
19 <quote>Downloads</quote>
20 section of the <ulink url="http://community.jedit.org">jEdit
21 Community</ulink> web site.
22</para>
23
24<sect1 id="macros-files"><title>File Management Macros</title>
25<para>
26 These macros automate the opening and closing of files.
27</para>
28
29<itemizedlist>
30
31<listitem>
32 <para><filename>Browse_Directory.bsh</filename></para>
33 <abstract><para>
34 Opens a directory supplied by the user in the file system
35 browser.
36 </para></abstract>
37</listitem>
38
39<listitem>
40 <para><filename>Close_All_Except_Active.bsh</filename></para>
41 <abstract><para>
42 Closes all files except the current buffer.
43 </para></abstract>
44 <para>
45 Prompts the user to save any buffer containing unsaved changes.
46 </para>
47</listitem>
48
49<listitem>
50 <para><filename>Open_Path.bsh</filename></para>
51 <abstract><para>
52 Opens the file supplied by the user in an input dialog.
53 </para></abstract>
54</listitem>
55
56<listitem>
57 <para><filename>Open_Selection.bsh</filename></para>
58 <abstract><para>
59 Opens the file named by the current buffer's selected text.
60 </para></abstract>
61</listitem>
62
63
64</itemizedlist>
65
66</sect1>
67
68<sect1 id="macros-text"><title>Text Macros</title>
69<para>
70 These macros generate various forms of formatted text.
71</para>
72
73<itemizedlist>
74
75<listitem>
76 <para><filename>Add_Prefix_and_Suffix.bsh</filename></para>
77 <abstract><para>
78 Adds user-supplied <quote>prefix</quote> and <quote>suffix</quote>
79 text to each line in a group of selected lines.
80 </para></abstract>
81 <para>
82 Text is added after leading whitespace and before trailing whitespace.
83 A dialog window receives input and <quote>remembers</quote> past entries.
84 </para>
85</listitem>
86
87<listitem>
88 <para><filename>Color_Picker.bsh</filename></para>
89 <abstract><para>
90 Displays a color picker and inserts the selected color in
91 hexadecimal format, prefixed with a <quote>#</quote>.
92 </para></abstract>
93</listitem>
94
95<listitem>
96 <para><filename>Duplicate_Line.bsh</filename></para>
97 <abstract><para>
98 Duplicates the line on which the caret lies immediately
99 beneath it and moves the caret to the new line.
100 </para></abstract>
101</listitem>
102
103<listitem>
104 <para><filename>Insert_Date.bsh</filename></para>
105 <abstract><para>
106 Inserts the current date and time in the current buffer.
107 </para></abstract>
108 <para>
109 The inserted text includes a representation of the time in the
110 <quote>Internet Time</quote> format.
111 </para>
112</listitem>
113
114<listitem>
115 <para><filename>Insert_Tag.bsh</filename></para>
116 <abstract><para>
117 Inserts a balanced pair of HTML/SGML/XML markup tags as supplied
118 in a input dialog. The tags will surround any selected text.
119 </para></abstract>
120</listitem>
121
122<listitem>
123 <para><filename>Next_Char.bsh</filename></para>
124 <abstract><para>
125 Finds next occurrence of character on current line.
126 </para></abstract>
127 <para>
128 The macro takes the next character typed after macro execution
129 as the character being searched. That character is not
130 displayed. If the character does not appear in the balance of
131 the current line, no action occurs.
132 </para>
133 <para>
134 This macro illustrates the use of
135 <function>InputHandler.readNextChar()</function> as a means of
136 obtaining user input. See <xref linkend="macro-tips-single-char"
137 />.
138 </para>
139</listitem>
140
141<listitem>
142 <para><filename>Toggle_Line_Comment.bsh</filename></para>
143 <abstract><para>
144 Toggles line comments, alternately inserting and deleting them
145 at the beginning of each selected line. If there is no selection,
146 the macro operates on the current line.
147 </para></abstract>
148 <para>
149 A <quote>line comment</quote> is a token that designates the entire
150 contents of a line as commented text; it does not use or require
151 a closing token. If the editing mode does not provide for line
152 comments (for example, text or XML modes), the macro will
153 display an error message.
154 </para>
155</listitem>
156
157</itemizedlist>
158</sect1>
159
160<sect1 id="macros-java"><title>Java Code Macros</title>
161<para>
162 These macros handle text formatting and generation tasks that are
163 particularly useful in writing Java code.
164</para>
165
166<itemizedlist>
167
168<listitem>
169 <para><filename>Get_Class_Name.bsh</filename></para>
170 <abstract><para>
171 Inserts a Java class name based upon the buffer's file name.
172 </para></abstract>
173</listitem>
174
175<listitem>
176 <para><filename>Get_Package_Name.bsh</filename></para>
177 <abstract><para>
178 Inserts a plausible Java package name for the current buffer.
179 </para></abstract>
180 <para>
181 The macro compares the buffer's path name with the elements of the
182 classpath being used by the jEdit session. An error message will be
183 displayed if no suitable package name is found. This macro will not
184 work if jEdit is being run as a JAR file without specifying a
185 classpath; in that case the classpath seen by the macro consists
186 solely of the JAR file.
187 </para>
188</listitem>
189
190<listitem>
191 <para><filename>Make_Get_and_Set_Methods.bsh</filename></para>
192 <abstract><para>
193 Creates <function>getXXX()</function> or <function>setXXX()</function>
194 methods that can be pasted into the buffer text.
195 </para></abstract>
196 <para>
197 This macro presents a dialog that will <quote>grab</quote> the names
198 of instance variables from the caret line of the current buffer
199 and paste a corresponding <function>getXXX()</function> or
200 <function>setXXX()</function> method to one of two text areas in the
201 dialog. The text can be edited in the dialog and then pasted into the
202 current buffer using the <guilabel>Insert...</guilabel> buttons. If
203 the caret is set to a line containing something other than an instance
204 variable, the text grabbing routine is likely to generate nonsense.
205 </para>
206 <para>
207 As explained in the notes accompanying the source code, the macro
208 uses a global variable which can be set to configure the macro to work
209 with either Java or C++ code. When set for use with C++ code,
210 the macro will also write (in commented text) definitions of
211 <function>getXXX()</function> or <function>setXXX()</function>
212 suitable for inclusion in a header file.
213 </para>
214</listitem>
215
216<listitem>
217 <para><filename>Preview_Javadoc_of_Buffer.bsh</filename></para>
218 <abstract><para>
219 Creates and displays javadoc for current buffer.
220 </para></abstract>
221 <para>
222 The macro includes configuration variables for using
223 different doclets for generating javadocs and for generating
224 javadocs of the package of which the current buffer is a part.
225 Details for use are included in the note accompanying the macro's
226 source code.
227 </para>
228</listitem>
229
230</itemizedlist>
231
232</sect1>
233
234<sect1 id="macros-properties"><title>Macros for Listing Properties</title>
235<para>
236 These macros produce lists or tables containing properties
237 used by the Java platform or jEdit itself.
238</para>
239
240
241<itemizedlist>
242
243<listitem>
244 <para><filename>jEdit_Properties.bsh</filename></para>
245 <abstract><para>
246 Writes an unsorted list of jEdit properties in a new buffer.
247 </para></abstract>
248</listitem>
249
250<listitem>
251 <para><filename>System_Properties.bsh</filename></para>
252 <abstract><para>
253 Writes an unsorted list of all Java system properties in a new
254 buffer.
255 </para></abstract>
256</listitem>
257
258<listitem>
259 <para><filename>Look_and_Feel_Properties.bsh</filename></para>
260 <abstract><para>
261 Writes an unsorted list of the names of Java Look and Feel
262 properties in a new buffer.
263 </para></abstract>
264</listitem>
265
266</itemizedlist>
267
268</sect1>
269
270<sect1 id="macros-misc"><title>Miscellaneous Macros</title>
271<para>
272 While these macros do not fit easily into the other categories, they all provide
273 interesting and useful functions.
274</para>
275
276<itemizedlist>
277
278<listitem>
279 <para><filename>Cascade_jEdit_Windows.bsh</filename></para>
280 <abstract><para>
281 Rearranges view and floating plugin windows.
282 </para></abstract>
283 <para>
284 The windows are arranged in an overlapping <quote>cascade</quote>
285 pattern beginning near the upper left corner of the display.
286 </para>
287</listitem>
288
289<listitem>
290 <para><filename>Display_Abbreviations.bsh</filename></para>
291 <abstract><para>
292 Displays the abbreviations registered for each of jEdit's
293 editing modes.
294 </para></abstract>
295 <para>
296 The macro provides a read-only view of the abbreviations
297 contained in the <quote>Abbreviations</quote> option pane. Pressing
298 a letter key will scroll the table to the first entry beginning with
299 that letter. A further option is provided to write a selected mode's
300 abbreviations or all abbreviations in a text buffer for printing as a
301 reference. Notes in the source code listing point out some display options
302 that are configured by modifying global variables.
303 </para>
304</listitem>
305
306<listitem>
307 <para><filename>Display_Shortcuts.bsh</filename></para>
308 <abstract><para>
309 Displays a sorted list of the keyboard shortcuts currently in effect.
310 </para></abstract>
311 <para>
312 The macro provides a combined read-only view of command, macro
313 and plugin shortcuts. Pressing a letter key will
314 scroll the table to the first entry beginning with that letter.
315 A further option is provided to write the shortcut assignments in a
316 text buffer for printing as a reference. Notes in the source code
317 listing point out some display options that are configured by
318 modifying global variables.
319 </para>
320</listitem>
321
322<listitem>
323 <para><filename>Evaluate_Buffer_in_BeanShell.bsh</filename></para>
324 <abstract><para>
325 Evaluates contents of current buffer as a BeanShell script,
326 and opens a new
327 buffer to receive any text output.
328 </para></abstract>
329 <para>
330 This is a quick way to test a macro script even before its text
331 is saved to a file. Opening a new buffer for output is a precaution
332 to prevent the macro from inadvertently erasing or overwriting
333 itself. BeanShell scripts that operate on the contents of the
334 current buffer will not work meaningfully when tested using this
335 macro.
336 </para>
337</listitem>
338
339<listitem>
340 <para><filename>Hex_Convert.bsh</filename></para>
341 <abstract><para>
342 Converts byte characters to their hex equivalent, and vice versa.
343 </para></abstract>
344</listitem>
345
346
347<listitem>
348 <para><filename>Include_Guard.bsh</filename></para>
349 <abstract><para>
350 Intended for C/C++ header files, this macro inserts a preprocessor
351 directive in the current buffer to ensure that the header is
352 included only once per compilation unit.
353 </para></abstract>
354 <para>
355 To use the macro, first place the caret at the beginning of the
356 header file before any uncommented text. The macro will return to
357 this position upon completion. The defined term that triggers the
358 <quote>include guard</quote> is taken from the buffer's name.
359 </para>
360</listitem>
361
362<listitem>
363 <para><filename>Make_Bug_Report.bsh</filename></para>
364 <abstract><para>
365 Creates a new buffer with installation and error information
366 extracted from the activity log.
367 </para></abstract>
368 <para>
369 The macro extracts initial messages written to the activity log
370 describing the user's operating system, JDK, jEdit version and
371 installed plugins. It then appends the last set of error messages
372 written to the activity log. The new text buffer can be saved and
373 attached to an email message or a bug report made on SourceForge.
374 </para>
375</listitem>
376
377<listitem>
378 <para><filename>Run_Script.bsh</filename></para>
379 <abstract><para>
380 Runs script using interpreter based upon buffer's editing mode
381 (by default, determined using file extension). You must have the
382 appropriate interpreter (such as Perl, Python, or Windows Script Host)
383 installed on your system.
384 </para></abstract>
385</listitem>
386
387<listitem>
388 <para><filename>Show_Threads.bsh</filename></para>
389 <abstract><para>
390 Displays in a tree format all running Java threads of the current
391 Java Virtual Machine.
392 </para></abstract>
393</listitem>
394
395<listitem>
396 <para><filename>Write_HyperSearch_Results.bsh</filename></para>
397 <abstract><para>
398 This macro writes the contents of the <quote>HyperSearch
399 Results</quote> window to a new text buffer.
400 </para></abstract>
401 <para>
402 The macro employs a simple text report format. Since
403 the HyperSearch window's object does not maintain the search
404 settings that produced the displayed results, the macro examines the
405 current settings in the <classname>SearchAndReplace</classname> object.
406 It confirms that the HyperSearch option is selected before writing
407 the report. However, the only way to be sure that the report's contents
408 are completely accurate is to run the macro immediately after a
409 HyperSearch.
410 </para>
411</listitem>
412
413</itemizedlist>
414
415</sect1>
416
417</appendix>
418