<?xml version="1.0" encoding="UTF-8"?>
<appendix id="macro-index">
    <title>Macros Included With jEdit</title>
    <!-- jEdit 4.0 Macro Guide, (C) 2001 John Gellene      -->
    <!-- jEdit buffer-local properties:                    -->
    <!-- :indentSize=2:noTabs=yes:maxLineLen=80:tabSize=2: -->
    <!-- :xml.root=users-guide.xml:                        -->
    <!-- covers index to installed macro set               -->

    <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>In addition to the macros included with jEdit, a very large collection
    of user-contributed macros is available in the <quote>Downloads</quote>
    section of the <ulink
    url="http://community.jedit.org">community.jedit.org</ulink> web site. There
    are detailed descriptions for each macro as well as a search
    facility.</para>

    <sect1 id="macros-c" >
        <title>C/C++ macros </title>
         <para> These macros are useful for C/C++ programming. </para>
         <itemizedlist>
         <listitem><para> <filename>Include_Guard.bsh</filename> </para>
         <para> Inserts conditional preprocessor directives around a header
         file, to prevent it from being included multiple times. </para>
         <para>The name of the generated preprocessor macro is based on the
          buffer's name. </para>
        </listitem>

         <listitem><para><filename> Toggle_Header_Source</filename></para>
         <para> Toggles between the header and the implementation file. Works for .c, .cxx, and .cpp extensions. </para>
         </listitem>
         </itemizedlist>
    </sect1>
         
    
    <sect1 id="macros-clipboard">
        <title>Clipboard Macros</title>

        <para>These macros copy or cut text to the clipboard.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Copy_Lines_Containing.bsh</filename></para>

                <para>Copies all lines from the current buffer, containing a
                user-supplied string, to the clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Cut_Lines_Containing.bsh</filename></para>

                <para>Cuts all lines from the current buffer, containing a
                user-supplied string, to the clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Selection_or_Line.bsh</filename></para>

                <para>If no text is selected, the current line is copied to the
                clipboard, otherwise the selected text is copied 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>&gt;<guimenuitem>Global
                Options</guimenuitem> dialog box.</para>
            </listitem>

            <listitem>
                <para><filename>Cut_Selection_or_Line.bsh</filename></para>

                <para>If no text is selected, the current line is cut to the
                clipboard, 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>&gt;<guimenuitem>Global
                Options</guimenuitem> dialog box.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Visible_Lines.bsh</filename></para>

                <para>Copies the visible lines from the current buffer to the
                Clipboard. Lines that are not visible becuase they are folded
                are not copied.</para>
            </listitem>
        </itemizedlist>
    </sect1>

    <sect1 id="macros-editing">
        <title>Editing Macros</title>

        <para>These macros automate various text editing tasks.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Emacs_Ctrl-K.bsh</filename></para>
                <para>Cuts and appends text, from the cursor to the end of the line, into the copy buffer.   </para>
            </listitem>
        
            <listitem>
                <para><filename>Emacs_Next_Line.bsh</filename></para>

                <para>Moves the cursor to the next line, centering the current
                line in the middle of the text area if the cursor is at the
                bottom of the text area.</para>
            </listitem>

            <listitem>
                <para><filename>Emacs_Previous_Line.bsh</filename></para>

                <para>Moves the cursor to the previous line, centering the
                current line in the middle of the text area if the cursor is at
                the top of the text area.</para>
            </listitem>

            <listitem>
                <para><filename>Go_to_Column.bsh</filename></para>

                <para>Prompts the user for a column position on the current
                line, then moves the caret there.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Backspace.bsh</filename></para>

                <para>If buffer is using soft tabs, this macro will backspace to
                the previous tab stop, if all characters between the caret and
                the tab stop are spaces. In all other cases a single character
                is removed.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Delete.bsh</filename></para>

                <para>If a buffer is using soft tabs, this macro will delete
                tabSize number of spaces, if all the characters between the
                caret and the next tab stop are spaces. In all other cases a
                single character is deleted.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Left.bsh</filename></para>

                <para>If a buffer is using soft tabs, this macro will move the
                caret tabSize spaces to the left, if all the characters between
                the caret and the previous tab stop are all spaces. In all other
                cases, the caret is moved a single character to the left.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Right.bsh</filename></para>

                <para>If a buffer is using soft tabs, this macro will move the
                caret tabSize spaces to the right, if all the characters between
                the caret and the next tab stop are all spaces. In all other
                cases, the caret is moved a single character to the
                right.</para>
            </listitem>

            <listitem>
                <para><filename>Keywords_to_Upper_Case.bsh</filename></para>

                <para>Converts all keywords in the current buffer to upper
                case.</para>
            </listitem>

            <listitem>
                <para><filename>Mode_Switcher.bsh</filename></para>

                <para>Displays a modal dialog with the current buffer's mode in
                a text field, allowing one to change the mode by typing in its
                name.</para>

                <para><keycap>ENTER</keycap> selects the current mode; if the
                text is not a valid mode, the dialog still dismisses, but a
                warning is logged to the activity log. <keycap>ESACPE</keycap>
                closes the dialog with no further action. <keycap>TAB</keycap>
                attempts to auto-complete the mode name. Pressing
                <keycap>TAB</keycap> repeatedly cycles through the possible
                completions. <keycap>SHIFT-TAB</keycap> cycles through the
                completions in reverse.</para>
            </listitem>

            <listitem>
                <para><filename>Move_Line_Down.bsh</filename></para>

                <para>Moves the current line down one, with automatic
                indentation.</para>
            </listitem>

            <listitem>
                <para><filename>Move_Line_Up.bsh</filename></para>

                <para>Moves the current line up one, with automatic
                indentation.</para>
            </listitem>
        </itemizedlist>
    </sect1>

    <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>

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

            <listitem>
                <para><filename>Buffer_Switcher.bsh</filename></para>

                <para>Displays a modal dialog listing all open buffers, allowing
                one to switch to and/or close buffers. <keycap>ENTER</keycap>
                switches to a buffer and closes the dialog,
                <keycap>DELETE</keycap> closes a buffer, <keycap>SPACE</keycap>
                switches to a buffer but does not close the dialog.</para>
            </listitem>

            <listitem>
                <para><filename>Close_All_Except_Active.bsh</filename></para>

                <para>Closes all files except the current buffer.</para>

                <para>Prompts the user to save any buffer containing unsaved
                changes.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Path_to_Clipboad.bsh</filename></para>

                <para>Copies the current buffer's path to the clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Name_to_Clipboad.bsh</filename></para>

                <para>Copies the current buffer's filename to the
                clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Delete_Current.bsh</filename></para>

                <para>Deletes the current buffer's file on disk, but doesn't
                close the buffer.</para>
            </listitem>

            <listitem>
                <para><filename>Glob_Close.bsh</filename></para>

                <para>Closes all open buffers matching a given glob
                pattern.</para>
            </listitem>

            <listitem>
                <para><filename>Insert_Selection.bsh</filename></para>

                <para>Assumes the current selection is file path and tries
                replaces the selection with the contents of the file. Does
                nothing if no text is selected or the selection spans multiple
                lines.</para>
            </listitem>

            <listitem>
                <para><filename>Next_Dirty_Buffer.bsh</filename></para>

                <para>Switches to the next dirty buffer, if there is one.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Path.bsh</filename></para>

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

            <listitem>
                <para><filename>Open_Selection.bsh</filename></para>

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

            <listitem>
                <para><filename>Toggle_ReadOnly.bsh</filename></para>

                <para>Toggles a local file's read-only flag. Uses
                platform-specific commands, so it only works on Windows, Unix
                and MacOS X.</para>
            </listitem>
        </itemizedlist>
    </sect1>

    <sect1 id="macros-interface">
        <title>User Interface Macros</title>

        <para>Description.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Decrease_Font_Size.bsh</filename></para>

                <para>Decreases the font size in the gutter and text area by 1
                point.</para>
            </listitem>

            <listitem>
                <para><filename>Increase_Font_Size.bsh</filename></para>

                <para>Increases the font size in the gutter and text area by 1
                point.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Context_Menu.bsh</filename></para>

                <para>Opens the text area context menu just below and to the
                right of the caret.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Bottom_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the bottom docking area, depending on
                it's current state.</para>
            </listitem>

            <listitem>
               <para><filename>Splitpane_Grow</filename> </para>
               <para> When inside a split EditPane, this macro moves the
               splitter away from the cursor, effectively increasing the size of
               the currently active split pane. </para>
             </listitem>
               
            
            <listitem>
                <para><filename>Toggle_Left_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the left docking area, depending on
                it's current state.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Right_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the right docking area, depending on
                it's current state.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Top_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the top docking area, depending on
                it's current state.</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>Create_Constructor.bsh</filename></para>

                <para>Inserts constructor for the class at the current caret
                position.</para>
            </listitem>

            <listitem>
                <para><filename>Get_Class_Name.bsh</filename></para>

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

            <listitem>
                <para><filename>Get_Package_Name.bsh</filename></para>

                <para>Inserts a plausible Java package name for the current
                buffer.</para>

                <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>Java_File_Save.bsh</filename></para>

                <abstract>
                    <para>Acts as a wrapper script to the Save As action. If the
                    buffer is a new file, it scans the first 250 lines for a
                    Java class or interface declaration. On finding one, it
                    extracts the appropriate filename to be used in the Save As
                    dialog.</para>
                </abstract>
            </listitem>

            <listitem>
                <para><filename>Make_Get_and_Set_Methods.bsh</filename></para>

                <para>Creates <function>getXXX()</function> or
                <function>setXXX()</function> methods that can be pasted into
                the buffer text.</para>

                <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>

                <para>Create and display API documentation for the current
                buffer.</para>

                <para>The macro includes various configuration variables you can
                change; see the comment at the beginning of the macro source for
                details.</para>
            </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>Display_Abbreviations.bsh</filename></para>

                <para>Displays the abbreviations registered for each of jEdit's
                editing modes.</para>

                <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_Actions.bsh</filename></para>

                <para>Displays a list of all the actions known to jEdit
                categorised by their action set.</para>

                <para>This macro can be a useful reference if you want to use
                the jEdit 4.2 action bar.</para>
            </listitem>

            <listitem>
                <para><filename>Display_Character_Code.bsh</filename></para>

                <para>Display int and hex values for the character at the caret,
                in the status bar.</para>
            </listitem>

            <listitem>
                <para><filename>Display_Shortcuts.bsh</filename></para>

                <para>Displays a sorted list of the keyboard shortcuts currently
                in effect.</para>

                <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>

                <para>Evaluates contents of current buffer as a BeanShell
                script, and opens a new buffer to receive any text
                output.</para>

                <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>

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

            <listitem>
                <para><filename>HyperSearch_Results_to_Buffer.bsh</filename></para>

                <para>Writes HyperSeach results to a new buffer.</para>
            </listitem>


            <listitem>
                <para><filename>Make_Bug_Report.bsh</filename></para>

                <para>Creates a new buffer with installation and error
                information extracted from the activity log.</para>

                <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>

                <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>
            </listitem>

            <listitem>
                <para><filename>Show_Threads.bsh</filename></para>

                <para>Displays in a tree format all running Java threads of the
                current Java Virtual Machine.</para>
            </listitem>
        </itemizedlist>
    </sect1>

    <sect1 id="macros-properties">
        <title>Property Macros</title>

        <para>These macros produce lists or tables containing properties used by
        the Java platform or jEdit itself.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Insert_Buffer_Properties.bsh</filename></para>

                <para>Inserts buffer-local properties into the current
                buffer.</para>

                <para>If the buffer's mode has a line comment defined, or
                comment start and end defined, the inserted properties will be
                commented out.</para>
            </listitem>

            <listitem>
                <para><filename>jEdit_Properties.bsh</filename></para>

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

            <listitem>
                <para><filename>Look_and_Feel_Properties.bsh</filename></para>

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

            <listitem>
                <para><filename>System_Properties.bsh</filename></para>

                <para>Writes an unsorted list of all Java system properties in a
                new buffer.</para>
            </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>

                <para>Adds user-supplied <quote>prefix</quote> and
                <quote>suffix</quote> text to each line in a group of selected
                lines.</para>

                <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>

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

            <listitem>
                <para><filename>Duplicate_Line.bsh</filename></para>

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

            <listitem>
                <para><filename>Insert_Date.bsh</filename></para>

                <para>Inserts the current date and time in the current
                buffer.</para>

                <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>

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

            <listitem>
                <para><filename>Next_Char.bsh</filename></para>

                <para>Finds next occurrence of character on current line.</para>

                <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>Reverse_Lines.bsh</filename></para>

                <para>Reverses the selected lines or the entire buffer if no
                lines are selected. Does not support Rectangular
                Selections.</para>
            </listitem>

            <listitem>
                <para><filename>Single_Space_Buffer.bsh</filename></para>

                <para>Removes every second line, if they are all blank.</para>
            </listitem>
        </itemizedlist>
    </sect1>
</appendix>