<!-- jEdit buffer-local properties:                               -->
<!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
<!-- :xml.root=users-guide.xml: -->

<chapter id="using-macros"><title>Using Macros</title>
  <para>
    Macros in jEdit are short scripts written in a scripting language called
    <firstterm>BeanShell</firstterm>. They provide an easy way to
    automate repetitive keyboard and menu procedures,
    as well as access to the objects and methods created by
    jEdit. Macros
    also provide a powerful facility for customizing jEdit and automating
    complex text processing and programming tasks. This section
    describes how to record and run macros. A detailed guide on
    writing macros appears later; see <xref linkend="writing-macros-part"/>.
  </para>

  <sidebar><title>Other scripting languages</title>
  <para>
   A number of jEdit plugins provide support for writing scripts in alternative programming languages, like Python and Prolog. Consult the documentation for the appropriate plugins for more information.
  </para>
  </sidebar>

<sect1 id="recording-macros"><title>Recording Macros</title>

  <para>
     The simplest use of macros is to record a series of key strokes and
     menu commands as a BeanShell script, and play them back later.
     While this doesn't let you take advantage of the full power of
     BeanShell, it is still a great time saver and can even be used to
     <quote>prototype</quote> more complicated macros.
  </para>

  <para>
    <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Macro</guimenuitem>
    (shortcut: <keycap>C+m C+r</keycap>) prompts
    for a macro name and begins recording.
  </para>

  <para>
    While recording is in progress, the string <quote>Macro
    recording</quote> is displayed in the status bar. jEdit records the
    following:
  </para>

  <itemizedlist>
    <listitem><para>Key strokes</para></listitem>
    <listitem><para>Menu item commands</para></listitem>
    <listitem><para>Tool bar clicks</para></listitem>
    <listitem><para>All search and replace operations, except incremental
    search</para></listitem>
  </itemizedlist>

  <para>
   Mouse clicks in the text area are <emphasis>not</emphasis> recorded;
   use text selection commands or arrow keys instead.
  </para>

  <para>
   <guimenu>Macros</guimenu>&gt;<guimenuitem>Stop Recording</guimenuitem>
   (shortcut: <keycap>C+m C+s</keycap>) stops
   recording. It also switches to the buffer containing the recorded macro,
   giving you a chance to check over the recorded commands and make any
   necessary changes. When you are happy with the macro, save the buffer and it
   will appear in the <guimenu>Macros</guimenu> menu. To discard the macro,
   close the buffer without saving it.
  </para>
  <para>
   The file name extension <filename>.bsh</filename> is
   automatically appended to the macro name, and all spaces are converted
   to underscore characters, in order to make the macro name a valid file
   name. These two operations are reversed when macros are displayed in the
   <guimenu>Macros</guimenu> menu; see <xref linkend="organizing-macros"/>
   for details.
  </para>
  <para>
   If a complicated operation only needs to be repeated a few
   times, using the temporary macro feature is quicker than saving a new
   macro file.
  </para>
  <para>
   <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Temporary
   Macro</guimenuitem> (shortcut: <keycap>C+m C+m</keycap>) begins
   recording to a buffer named <filename>Temporary_Macro.bsh</filename>.
   Once recording of a temporary macro is complete, jEdit does not display
   the buffer containing the recorded commands, but the name
   <filename>Temporary_Macro.bsh</filename> will be visible on any list of
   open buffers. By switching to that buffer, you can view the commands,
   edit them, and save them if you wish to
   a permanent macro file. Whether or not you look at or save the temporary
   macro contents, it is immediately available for playback.
  </para>

  <para>
   <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Temporary
   Macro</guimenuitem> (shortcut: <keycap>C+m C+p</keycap>) plays
   the macro recorded to the <filename>Temporary_Macro.bsh</filename> buffer.
  </para>

  <para>
    Only one temporary macro is available at a time. If you begin recording
    a second temporary macro, the first is erased and cannot be recovered
    unless you have saved the contents to a file with a name other than
    <filename>Temporary_Macro.bsh</filename>.
    If you do not save the temporary macro, you must keep the buffer
    containing the macro script open during your jEdit session. To have the
    macro available for your next jEdit session, save the buffer
    <filename>Temporary_Macro.bsh</filename> as an ordinary macro with a
    descriptive name of your choice. The new name will then be displayed in
    the <guimenu>Macros</guimenu> menu.
  </para>
</sect1>

<sect1 id="running-macros"><title>Running Macros</title>

  <para>
    Macros supplied with jEdit, as well as macros that you record or write,
    are displayed under the <guimenu>Macros</guimenu> menu in a
    hierarchical structure. The jEdit installation includes about 30 macros
    divided into several major categories. Each category corresponds to a
    nested submenu under the <guimenu>Macros</guimenu> menu. An index of
    these macros containing short descriptions and usage notes is found in
    <xref linkend="macro-index"/>.
  </para>

  <para>
    To run a macro, choose the <guimenu>Macros</guimenu> menu,
    navigate through the hierarchy of submenus, and select the name
    of the macro to execute.  You can also assign execution of a
    particular macro to a keyboard shortcut, toolbar button or
    context menu using the
    <guimenuitem>Macro Shortcuts</guimenuitem>,
    <guimenuitem>Tool Bar</guimenuitem> or
    <guimenuitem>Context Menu</guimenuitem> panes of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
    Options</guimenuitem> dialog; see
    <xref linkend="global-opts"/>.
  </para>

  <para>
    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Last Macro</guimenuitem>
    (shortcut: <keycap>C+m C+l</keycap>)
    runs the last macro run by jEdit again.
  </para>

</sect1>

<sect1 id="organizing-macros"><title>How jEdit Organizes Macros</title>
  <para>
   Every macro, whether or not you originally recorded it, is stored on
   disk and can be edited as a text file. The file name of a macro
   must have a <filename>.bsh</filename> extension in order for jEdit
   to be aware of it.
   By default, jEdit associates a
   <filename>.bsh</filename> file with the BeanShell edit
   mode for purposes of syntax highlighting, indentation and other
   formatting. However, BeanShell syntax does not impose any indentation or
   line break requirements.
  </para>

  <para>
   The <guimenu>Macros</guimenu> menu
   lists all macros stored in two places: the <filename>macros</filename>
   subdirectory of the jEdit home directory, and the
   <filename>macros</filename> subdirectory of the user-specific
   settings directory (see <xref linkend="settings-directory"/> for
   information about the settings directory). Any macros you record will be
   stored in the user-specific directory.
  </para>

  <para>
    Macros stored elsewhere can be run using the
    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other Macro</guimenuitem>
    command, which
    displays a file chooser dialog box, and runs the specified file.
  </para>

  <para>
   The listing of individual macros in the <guimenu>Macros</guimenu> menu
   can be organized in a hierarchy using subdirectories in the general
   or user-specific macro directories; each subdirectory
   appears as a submenu. You will find such a hierarchy in the
   default macro set included with jEdit.
  </para>

  <para>
   When jEdit first loads, it scans the designated macro directories and
   assembles a listing of individual macros in the <guimenu>Macros</guimenu>
   menu. When scanning the names, jEdit will delete underscore characters
   and the <filename>.bsh</filename> extension for menu labels, so that
   <filename>List_Useful_Information.bsh</filename>, for example, will be
   displayed in the <guimenu>Macros</guimenu> menu as <guimenuitem>List
   Useful Information</guimenuitem>.
  </para>

  <para>
   You can browse the user and system macro directories by opening the
   <filename>macros</filename> directory from the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>jEdit Home Directory</guimenuitem>
   and <guimenu>Utilities</guimenu>&gt;<guimenuitem>Settings Directory</guimenuitem>
   menus.
  </para>

  <para>
    Macros can be opened and edited much like ordinary files from the
    file system browser. Editing macros from within jEdit will
    automatically update the macros menu; however, if you modify macros
    from another program or add macro files to the macro directories, you
    should run the
    <guimenu>Macros</guimenu>&gt;<guimenuitem>Rescan Macros</guimenuitem>
    command to update the macro list.
  </para>
 </sect1>

</chapter>