/jEdit/tags/jedit-4-3-pre5/doc/users-guide/using-macros.xml

  1<!-- jEdit buffer-local properties:                               -->
  2<!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
  3<!-- :xml.root=users-guide.xml: -->
  4
  5<chapter id="using-macros"><title>Using Macros</title>
  6  <para>
  7    Macros in jEdit are short scripts written in a scripting language called
  8    <firstterm>BeanShell</firstterm>. They provide an easy way to
  9    automate repetitive keyboard and menu procedures,
 10    as well as access to the objects and methods created by
 11    jEdit. Macros
 12    also provide a powerful facility for customizing jEdit and automating
 13    complex text processing and programming tasks. This section
 14    describes how to record and run macros. A detailed guide on
 15    writing macros appears later; see <xref linkend="writing-macros-part"/>.
 16  </para>
 17
 18  <sidebar><title>Other scripting languages</title>
 19  <para>
 20   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.
 21  </para>
 22  </sidebar>
 23
 24<sect1 id="recording-macros"><title>Recording Macros</title>
 25
 26  <para>
 27     The simplest use of macros is to record a series of key strokes and
 28     menu commands as a BeanShell script, and play them back later.
 29     While this doesn't let you take advantage of the full power of
 30     BeanShell, it is still a great time saver and can even be used to
 31     <quote>prototype</quote> more complicated macros.
 32  </para>
 33
 34  <para>
 35    <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Macro</guimenuitem>
 36    (shortcut: <keycap>C+m C+r</keycap>) prompts
 37    for a macro name and begins recording.
 38  </para>
 39
 40  <para>
 41    While recording is in progress, the string <quote>Macro
 42    recording</quote> is displayed in the status bar. jEdit records the
 43    following:
 44  </para>
 45
 46  <itemizedlist>
 47    <listitem><para>Key strokes</para></listitem>
 48    <listitem><para>Menu item commands</para></listitem>
 49    <listitem><para>Tool bar clicks</para></listitem>
 50    <listitem><para>All search and replace operations, except incremental
 51    search</para></listitem>
 52  </itemizedlist>
 53
 54  <para>
 55   Mouse clicks in the text area are <emphasis>not</emphasis> recorded;
 56   use text selection commands or arrow keys instead.
 57  </para>
 58
 59  <para>
 60   <guimenu>Macros</guimenu>&gt;<guimenuitem>Stop Recording</guimenuitem>
 61   (shortcut: <keycap>C+m C+s</keycap>) stops
 62   recording. It also switches to the buffer containing the recorded macro,
 63   giving you a chance to check over the recorded commands and make any
 64   necessary changes. When you are happy with the macro, save the buffer and it
 65   will appear in the <guimenu>Macros</guimenu> menu. To discard the macro,
 66   close the buffer without saving it.
 67  </para>
 68  <para>
 69   The file name extension <filename>.bsh</filename> is
 70   automatically appended to the macro name, and all spaces are converted
 71   to underscore characters, in order to make the macro name a valid file
 72   name. These two operations are reversed when macros are displayed in the
 73   <guimenu>Macros</guimenu> menu; see <xref linkend="organizing-macros"/>
 74   for details.
 75  </para>
 76  <para>
 77   If a complicated operation only needs to be repeated a few
 78   times, using the temporary macro feature is quicker than saving a new
 79   macro file.
 80  </para>
 81  <para>
 82   <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Temporary
 83   Macro</guimenuitem> (shortcut: <keycap>C+m C+m</keycap>) begins
 84   recording to a buffer named <filename>Temporary_Macro.bsh</filename>.
 85   Once recording of a temporary macro is complete, jEdit does not display
 86   the buffer containing the recorded commands, but the name
 87   <filename>Temporary_Macro.bsh</filename> will be visible on any list of
 88   open buffers. By switching to that buffer, you can view the commands,
 89   edit them, and save them if you wish to
 90   a permanent macro file. Whether or not you look at or save the temporary
 91   macro contents, it is immediately available for playback.
 92  </para>
 93
 94  <para>
 95   <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Temporary
 96   Macro</guimenuitem> (shortcut: <keycap>C+m C+p</keycap>) plays
 97   the macro recorded to the <filename>Temporary_Macro.bsh</filename> buffer.
 98  </para>
 99
100  <para>
101    Only one temporary macro is available at a time. If you begin recording
102    a second temporary macro, the first is erased and cannot be recovered
103    unless you have saved the contents to a file with a name other than
104    <filename>Temporary_Macro.bsh</filename>.
105    If you do not save the temporary macro, you must keep the buffer
106    containing the macro script open during your jEdit session. To have the
107    macro available for your next jEdit session, save the buffer
108    <filename>Temporary_Macro.bsh</filename> as an ordinary macro with a
109    descriptive name of your choice. The new name will then be displayed in
110    the <guimenu>Macros</guimenu> menu.
111  </para>
112</sect1>
113
114<sect1 id="running-macros"><title>Running Macros</title>
115
116  <para>
117    Macros supplied with jEdit, as well as macros that you record or write,
118    are displayed under the <guimenu>Macros</guimenu> menu in a
119    hierarchical structure. The jEdit installation includes about 30 macros
120    divided into several major categories. Each category corresponds to a
121    nested submenu under the <guimenu>Macros</guimenu> menu. An index of
122    these macros containing short descriptions and usage notes is found in
123    <xref linkend="macro-index"/>.
124  </para>
125
126  <para>
127    To run a macro, choose the <guimenu>Macros</guimenu> menu,
128    navigate through the hierarchy of submenus, and select the name
129    of the macro to execute.  You can also assign execution of a
130    particular macro to a keyboard shortcut, toolbar button or
131    context menu using the
132    <guimenuitem>Macro Shortcuts</guimenuitem>,
133    <guimenuitem>Tool Bar</guimenuitem> or
134    <guimenuitem>Context Menu</guimenuitem> panes of the
135    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
136    Options</guimenuitem> dialog; see
137    <xref linkend="global-opts"/>.
138  </para>
139
140</sect1>
141
142<sect1 id="organizing-macros"><title>How jEdit Organizes Macros</title>
143  <para>
144   Every macro, whether or not you originally recorded it, is stored on
145   disk and can be edited as a text file. The file name of a macro
146   must have a <filename>.bsh</filename> extension in order for jEdit
147   to be aware of it.
148   By default, jEdit associates a
149   <filename>.bsh</filename> file with the BeanShell edit
150   mode for purposes of syntax highlighting, indentation and other
151   formatting. However, BeanShell syntax does not impose any indentation or
152   line break requirements.
153  </para>
154
155  <para>
156   The <guimenu>Macros</guimenu> menu
157   lists all macros stored in two places: the <filename>macros</filename>
158   subdirectory of the jEdit home directory, and the
159   <filename>macros</filename> subdirectory of the user-specific
160   settings directory (see <xref linkend="settings-directory"/> for
161   information about the settings directory). Any macros you record will be
162   stored in the user-specific directory.
163  </para>
164
165  <para>
166    Macros stored elsewhere can be run using the
167    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other Macro</guimenuitem>
168    command, which
169    displays a file chooser dialog box, and runs the specified file.
170  </para>
171
172  <para>
173   The listing of individual macros in the <guimenu>Macros</guimenu> menu
174   can be organized in a hierarchy using subdirectories in the general
175   or user-specific macro directories; each subdirectory
176   appears as a submenu. You will find such a hierarchy in the
177   default macro set included with jEdit.
178  </para>
179
180  <para>
181   When jEdit first loads, it scans the designated macro directories and
182   assembles a listing of individual macros in the <guimenu>Macros</guimenu>
183   menu. When scanning the names, jEdit will delete underscore characters
184   and the <filename>.bsh</filename> extension for menu labels, so that
185   <filename>List_Useful_Information.bsh</filename>, for example, will be
186   displayed in the <guimenu>Macros</guimenu> menu as <guimenuitem>List
187   Useful Information</guimenuitem>.
188  </para>
189
190  <para>
191   You can browse the user and system macro directories by opening the
192   <filename>macros</filename> directory from the
193   <guimenu>Utilities</guimenu>&gt;<guimenuitem>jEdit Home Directory</guimenuitem>
194   and <guimenu>Utilities</guimenu>&gt;<guimenuitem>Settings Directory</guimenuitem>
195   menus.
196  </para>
197
198  <para>
199    Macros can be opened and edited much like ordinary files from the
200    file system browser. Editing macros from within jEdit will
201    automatically update the macros menu; however, if you modify macros
202    from another program or add macro files to the macro directories, you
203    should run the
204    <guimenu>Macros</guimenu>&gt;<guimenuitem>Rescan Macros</guimenuitem>
205    command to update the macro list.
206  </para>
207 </sect1>
208
209</chapter>
210