PageRenderTime 80ms CodeModel.GetById 70ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-2-pre4/doc/users-guide/macro-index.xml

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