/jEdit/tags/jedit-4-3-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: -->
<!-- :xml.root=users-guide.xml:                        -->

<!-- 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>
  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-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_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>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>Include_Guard.bsh</filename></para>
    <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>
    <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>
    <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>