/jEdit/tags/jedit-4-1-pre5/doc/users-guide/macro-index.xml

<!-- jEdit 4.0 Macro Guide, (C) 2001 John Gellene      -->

<!-- jEdit buffer-local properties:                    -->
<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2: -->

<!-- covers index to installed macro set               -->

<appendix id="macro-index"><title>Macros Included With jEdit</title>

<para>
    jEdit comes with a large number of sample macros that perform a variety
    of tasks. The following index provides short descriptions of each macro,
    in some cases accompanied by usage notes.
</para>

<para>
  Macros from earlier versions of jEdit can be found, as well as
  a large number of macros contributed by users, can be found in the
  <quote>Downloads</quote>
  section of the <ulink url="http://community.jedit.org">jEdit
  Community</ulink> web site.
</para>

<sect1 id="macros-files"><title>File Management Macros</title>
<para>
    These macros automate the opening and closing of files.
</para>

<itemizedlist>

<listitem>
    <para><filename>Browse_Directory.bsh</filename></para>
    <abstract><para>
        Opens a directory supplied by the user in the file system
        browser.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Close_All_Except_Active.bsh</filename></para>
    <abstract><para>
        Closes all files except the current buffer.
    </para></abstract>
    <para>
        Prompts the user to save any buffer containing unsaved changes.
    </para>
</listitem>

<listitem>
    <para><filename>Open_Path.bsh</filename></para>
    <abstract><para>
        Opens the file supplied by the user in an input dialog.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Open_Selection.bsh</filename></para>
    <abstract><para>
        Opens the file named by the current buffer's selected text.
    </para></abstract>
</listitem>


</itemizedlist>

</sect1>

<sect1 id="macros-text"><title>Text Macros</title>
<para>
    These macros generate various forms of formatted text.
</para>

<itemizedlist>

<listitem>
    <para><filename>Add_Prefix_and_Suffix.bsh</filename></para>
    <abstract><para>
        Adds user-supplied <quote>prefix</quote> and <quote>suffix</quote>
        text to each line in a group of selected lines.
    </para></abstract>
    <para>
        Text is added after leading whitespace and before trailing whitespace.
        A dialog window receives input and <quote>remembers</quote> past entries.
    </para>
</listitem>

<listitem>
    <para><filename>Color_Picker.bsh</filename></para>
    <abstract><para>
        Displays a color picker and inserts the selected color in
        hexadecimal format, prefixed with a <quote>#</quote>.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Duplicate_Line.bsh</filename></para>
    <abstract><para>
        Duplicates the line on which the caret lies immediately
        beneath it and moves the caret to the new line.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Insert_Date.bsh</filename></para>
    <abstract><para>
        Inserts the current date and time in the current buffer.
    </para></abstract>
    <para>
        The inserted text includes a representation of the time in the
        <quote>Internet Time</quote> format.
    </para>
</listitem>

<listitem>
    <para><filename>Insert_Tag.bsh</filename></para>
    <abstract><para>
        Inserts a balanced pair of HTML/SGML/XML markup tags as supplied
        in a input dialog.  The tags will surround any selected text.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Next_Char.bsh</filename></para>
    <abstract><para>
        Finds next occurrence of character on current line.
    </para></abstract>
    <para>
        The macro takes the next character typed after macro execution
        as the character being searched.  That character is not
        displayed.  If the character does not appear in the balance of
        the current line, no action occurs.
    </para>
    <para>
        This macro illustrates the use of
        <function>InputHandler.readNextChar()</function> as a means of
        obtaining user input. See <xref linkend="macro-tips-single-char"
        />.
    </para>
</listitem>

<listitem>
  <para><filename>Toggle_Line_Comment.bsh</filename></para>
  <abstract><para>
	  Toggles line comments, alternately inserting and deleting them
    at the beginning of each selected line. If there is no selection,
    the macro operates on the current line.
  </para></abstract>
	<para>
		 A <quote>line comment</quote> is a token that designates the entire
     contents of a line as commented text; it does not use or require
     a closing token. If the editing mode does not provide for line
     comments (for example, text or XML modes), the macro will
     display an error message.
	</para>
</listitem>

</itemizedlist>
</sect1>

<sect1 id="macros-java"><title>Java Code Macros</title>
<para>
    These macros handle text formatting and generation tasks that are
    particularly useful in writing Java code.
</para>

<itemizedlist>

<listitem>
    <para><filename>Get_Class_Name.bsh</filename></para>
    <abstract><para>
        Inserts a Java class name based upon the buffer's file name.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Get_Package_Name.bsh</filename></para>
    <abstract><para>
        Inserts a plausible Java package name for the current buffer.
    </para></abstract>
    <para>
        The macro compares the buffer's path name with the elements of the
        classpath being used by the jEdit session.  An error message will be
        displayed if no suitable package name is found. This macro will not
        work if jEdit is being run as a JAR file without specifying a
        classpath; in that case the classpath seen by the macro consists
        solely of the JAR file.
    </para>
</listitem>

<listitem>
    <para><filename>Make_Get_and_Set_Methods.bsh</filename></para>
    <abstract><para>
        Creates <function>getXXX()</function> or <function>setXXX()</function>
        methods that can be pasted into the buffer text.
    </para></abstract>
    <para>
        This macro presents a dialog that will <quote>grab</quote> the names
        of instance variables from the caret line of the current buffer
        and paste a corresponding <function>getXXX()</function> or
        <function>setXXX()</function> method to one of two text areas in the
        dialog.  The text can be edited in the dialog and then pasted into the
        current buffer using the <guilabel>Insert...</guilabel> buttons.  If
        the caret is set to a line containing something other than an instance
        variable, the text grabbing routine is likely to generate nonsense.
    </para>
    <para>
        As explained in the notes accompanying the source code, the macro
        uses a global variable which can be set to configure the macro to work
        with either Java or C++ code.  When set for use with C++ code,
        the macro will also write (in commented text) definitions of
        <function>getXXX()</function> or <function>setXXX()</function>
        suitable for inclusion in a header file.
    </para>
</listitem>

<listitem>
   <para><filename>Preview_Javadoc_of_Buffer.bsh</filename></para>
   <abstract><para>
     Creates and displays javadoc for current buffer.
   </para></abstract>
   <para>
      The macro includes configuration variables for using
      different doclets for generating javadocs and for generating
      javadocs of the package of which the current buffer is a part.
      Details for use are included in the note accompanying the macro's
      source code.
   </para>
</listitem>

</itemizedlist>

</sect1>

<sect1 id="macros-properties"><title>Macros for Listing Properties</title>
<para>
    These macros produce lists or tables containing properties
    used by the Java platform or jEdit itself.
</para>


<itemizedlist>

<listitem>
    <para><filename>jEdit_Properties.bsh</filename></para>
    <abstract><para>
       Writes an unsorted list of jEdit properties in a new buffer.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>System_Properties.bsh</filename></para>
    <abstract><para>
        Writes an unsorted list of all Java system properties in a new
        buffer.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Look_and_Feel_Properties.bsh</filename></para>
    <abstract><para>
        Writes an unsorted list of the names of Java Look and Feel
        properties in a new buffer.
    </para></abstract>
</listitem>

</itemizedlist>

</sect1>

<sect1 id="macros-misc"><title>Miscellaneous Macros</title>
<para>
    While these macros do not fit easily into the other categories, they all provide
    interesting and useful functions.
</para>

<itemizedlist>

<listitem>
    <para><filename>Cascade_jEdit_Windows.bsh</filename></para>
    <abstract><para>
        Rearranges view and floating plugin windows.
    </para></abstract>
    <para>
        The windows are arranged in an overlapping <quote>cascade</quote>
        pattern beginning near the upper left corner of the display.
    </para>
</listitem>

<listitem>
    <para><filename>Display_Abbreviations.bsh</filename></para>
    <abstract><para>
        Displays the abbreviations registered for each of jEdit's
        editing modes.
    </para></abstract>
    <para>
        The macro provides a read-only view of the abbreviations
        contained in the <quote>Abbreviations</quote> option pane.  Pressing
        a letter key will scroll the table to the first entry beginning with
        that letter.  A further option is provided to write a selected mode's
        abbreviations or all abbreviations in a text buffer for printing as a
        reference. Notes in the source code listing point out some display options
        that are configured by modifying global variables.
    </para>
</listitem>

<listitem>
    <para><filename>Display_Shortcuts.bsh</filename></para>
    <abstract><para>
        Displays a sorted list of the keyboard shortcuts currently in effect.
    </para></abstract>
    <para>
        The macro provides a combined read-only view of command, macro
        and plugin shortcuts. Pressing a letter key will
        scroll the table to the first entry beginning with that letter.
        A further option is provided to write the shortcut assignments in a
        text buffer for printing as a reference. Notes in the source code
        listing point out some display options that are configured by
        modifying global variables.
    </para>
</listitem>

<listitem>
    <para><filename>Evaluate_Buffer_in_BeanShell.bsh</filename></para>
    <abstract><para>
        Evaluates contents of current buffer as a BeanShell script,
        and opens a new
        buffer to receive any text output.
    </para></abstract>
    <para>
        This is a quick way to test a macro script even before its text
        is saved to a file.  Opening a new buffer for output is a precaution
        to prevent the macro from inadvertently erasing or overwriting
        itself.  BeanShell scripts that operate on the contents of the
        current buffer will not work meaningfully when tested using this
        macro.
    </para>
</listitem>

<listitem>
  <para><filename>Hex_Convert.bsh</filename></para>
  <abstract><para>
    Converts byte characters to their hex equivalent, and vice versa.
  </para></abstract>
</listitem>


<listitem>
    <para><filename>Include_Guard.bsh</filename></para>
    <abstract><para>
		Intended for C/C++ header files, this macro inserts a preprocessor
		directive in the current buffer to ensure that the header is
		included only once per compilation unit.
    </para></abstract>
    <para>
        To use the macro, first place the caret at the beginning of the
		header file before any uncommented text.  The macro will return to
		this position upon completion.  The defined term that triggers the
		<quote>include guard</quote> is taken from the buffer's name.
    </para>
</listitem>

<listitem>
    <para><filename>Make_Bug_Report.bsh</filename></para>
    <abstract><para>
      Creates a new buffer with installation and error information
	    extracted from the activity log.
    </para></abstract>
	<para>
	  The macro extracts initial messages written to the activity log
	  describing the user's operating system, JDK, jEdit version and
	  installed plugins. It then appends the last set of error messages
	  written to the activity log.  The new text buffer can be saved and
	  attached to an email message or a bug report made on SourceForge.
	</para>
</listitem>

<listitem>
  <para><filename>Run_Script.bsh</filename></para>
  <abstract><para>
    Runs script using interpreter based upon buffer's editing mode
    (by default, determined using file extension). You must have the
    appropriate interpreter (such as Perl, Python, or Windows Script Host)
    installed on your system.
  </para></abstract>
</listitem>

<listitem>
    <para><filename>Show_Threads.bsh</filename></para>
    <abstract><para>
      Displays in a tree format all running Java threads of the current
      Java Virtual Machine.
    </para></abstract>
</listitem>

<listitem>
    <para><filename>Write_HyperSearch_Results.bsh</filename></para>
    <abstract><para>
        This macro writes the contents of the <quote>HyperSearch
        Results</quote> window to a new text buffer.
    </para></abstract>
    <para>
        The macro employs a simple text report format. Since
        the HyperSearch window's object does not maintain the search
        settings that produced the displayed results, the macro examines the
        current settings in the <classname>SearchAndReplace</classname> object.
        It confirms that the HyperSearch option is selected before writing
        the report. However, the only way to be sure that the report's contents
        are completely accurate is to run the macro immediately after a
        HyperSearch.
    </para>
</listitem>

</itemizedlist>

</sect1>

</appendix>