/jEdit/tags/jedit-4-2-pre4/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:
 37    <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 38    <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>) prompts
 39    for a macro name and begins recording.
 40  </para>
 41
 42  <para>
 43    While recording is in progress, the string <quote>Macro
 44    recording</quote> is displayed in the status bar. jEdit records the
 45    following:
 46  </para>
 47
 48  <itemizedlist>
 49    <listitem><para>Key strokes</para></listitem>
 50    <listitem><para>Menu item commands</para></listitem>
 51    <listitem><para>Tool bar clicks</para></listitem>
 52    <listitem><para>All search and replace operations, except incremental
 53    search</para></listitem>
 54  </itemizedlist>
 55
 56  <para>
 57   Mouse clicks in the text area are <emphasis>not</emphasis> recorded;
 58   use text selection commands or arrow keys instead.
 59  </para>
 60
 61  <para>
 62   <guimenu>Macros</guimenu>&gt;<guimenuitem>Stop Recording</guimenuitem>
 63   (shortcut: <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 64   <keycombo><keycap>Control</keycap><keycap>S</keycap></keycombo>) stops
 65   recording. It also switches to the buffer containing the recorded macro,
 66   giving you a chance to check over the recorded commands and make any
 67   necessary changes. When you are happy with the macro, save the buffer and it
 68   will appear in the <guimenu>Macros</guimenu> menu. To discard the macro,
 69   close the buffer without saving it.
 70  </para>
 71  <para>
 72   The file name extension <filename>.bsh</filename> is
 73   automatically appended to the macro name, and all spaces are converted
 74   to underscore characters, in order to make the macro name a valid file
 75   name. These two operations are reversed when macros are displayed in the
 76   <guimenu>Macros</guimenu> menu; see <xref linkend="organizing-macros"/>
 77   for details.
 78  </para>
 79  <para>
 80   If a complicated operation only needs to be repeated a few
 81   times, using the temporary macro feature is quicker than saving a new
 82   macro file.
 83  </para>
 84  <para>
 85   <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Temporary
 86   Macro</guimenuitem> (shortcut:
 87   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 88   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>) begins
 89   recording to a buffer named <filename>Temporary_Macro.bsh</filename>.
 90   Once recording of a temporary macro is complete, jEdit does not display
 91   the buffer containing the recorded commands, but the name
 92   <filename>Temporary_Macro.bsh</filename> will be visible on any list of
 93   open buffers. By switching to that buffer, you can view the commands,
 94   edit them, and save them if you wish to
 95   a permanent macro file. Whether or not you look at or save the temporary
 96   macro contents, it is immediately available for playback.
 97  </para>
 98
 99  <para>
100   <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Temporary
101   Macro</guimenuitem> (shortcut:
102   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
103   <keycombo><keycap>Control</keycap><keycap>P</keycap></keycombo>) plays
104   the macro recorded to the <filename>Temporary_Macro.bsh</filename> buffer.
105  </para>
106
107  <para>
108    Only one temporary macro is available at a time. If you begin recording
109    a second temporary macro, the first is erased and cannot be recovered
110    unless you have saved the contents to a file with a name other than
111    <filename>Temporary_Macro.bsh</filename>.
112    If you do not save the temporary macro, you must keep the buffer
113    containing the macro script open during your jEdit session. To have the
114    macro available for your next jEdit session, save the buffer
115    <filename>Temporary_Macro.bsh</filename> as an ordinary macro with a
116    descriptive name of your choice. The new name will then be displayed in
117    the <guimenu>Macros</guimenu> menu.
118  </para>
119</sect1>
120
121<sect1 id="running-macros"><title>Running Macros</title>
122
123  <para>
124    Macros supplied with jEdit, as well as macros that you record or write,
125    are displayed under the <guimenu>Macros</guimenu> menu in a
126    hierarchical structure. The jEdit installation includes about 30 macros
127    divided into several major categories. Each category corresponds to a
128    nested submenu under the <guimenu>Macros</guimenu> menu. An index of
129    these macros containing short descriptions and usage notes is found in
130    <xref linkend="macro-index"/>.
131  </para>
132
133  <para>
134    To run a macro, choose the <guimenu>Macros</guimenu> menu,
135    navigate through the hierarchy of submenus, and select the name
136    of the macro to execute.  You can also assign execution of a
137    particular macro to a keyboard shortcut, toolbar button or
138    context menu using the
139    <guimenuitem>Macro Shortcuts</guimenuitem>,
140    <guimenuitem>Tool Bar</guimenuitem> or
141    <guimenuitem>Context Menu</guimenuitem> panes of the
142    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
143    Options</guimenuitem> dialog; see
144    <xref linkend="global-opts"/>.
145  </para>
146
147  <para>
148    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Last Macro</guimenuitem>
149    (shortcut:
150    <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
151    <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>)
152    runs the last macro run by jEdit again.
153  </para>
154
155</sect1>
156
157<sect1 id="organizing-macros"><title>How jEdit Organizes Macros</title>
158  <para>
159   Every macro, whether or not you originally recorded it, is stored on
160   disk and can be edited as a text file. The file name of a macro
161   must have a <filename>.bsh</filename> extension in order for jEdit
162   to be aware of it.
163   By default, jEdit associates a
164   <filename>.bsh</filename> file with the BeanShell edit
165   mode for purposes of syntax highlighting, indentation and other
166   formatting. However, BeanShell syntax does not impose any indentation or
167   line break requirements.
168  </para>
169
170  <para>
171   The <guimenu>Macros</guimenu> menu
172   lists all macros stored in two places: the <filename>macros</filename>
173   subdirectory of the jEdit home directory, and the
174   <filename>macros</filename> subdirectory of the user-specific
175   settings directory (see <xref linkend="settings-directory"/> for
176   information about the settings directory). Any macros you record will be
177   stored in the user-specific directory.
178  </para>
179
180  <para>
181    Macros stored elsewhere can be run using the
182    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other Macro</guimenuitem>
183    command, which
184    displays a file chooser dialog box, and runs the specified file.
185  </para>
186
187  <para>
188   The listing of individual macros in the <guimenu>Macros</guimenu> menu
189   can be organized in a hierarchy using subdirectories in the general
190   or user-specific macro directories; each subdirectory
191   appears as a submenu. You will find such a hierarchy in the
192   default macro set included with jEdit.
193  </para>
194
195  <para>
196   When jEdit first loads, it scans the designated macro directories and
197   assembles a listing of individual macros in the <guimenu>Macros</guimenu>
198   menu. When scanning the names, jEdit will delete underscore characters
199   and the <filename>.bsh</filename> extension for menu labels, so that
200   <filename>List_Useful_Information.bsh</filename>, for example, will be
201   displayed in the <guimenu>Macros</guimenu> menu as <guimenuitem>List
202   Useful Information</guimenuitem>.
203  </para>
204
205  <para>
206   You can browse the user and system macro directories by opening the
207   <filename>macros</filename> directory from the
208   <guimenu>Utilities</guimenu>&gt;<guimenuitem>jEdit Home Directory</guimenuitem>
209   and <guimenu>Utilities</guimenu>&gt;<guimenuitem>Settings Directory</guimenuitem>
210   menus.
211  </para>
212
213  <para>
214    Macros can be opened and edited much like ordinary files from the
215    file system browser. Editing macros from within jEdit will
216    automatically update the macros menu; however, if you modify macros
217    from another program or add macro files to the macro directories, you
218    should run the
219    <guimenu>Macros</guimenu>&gt;<guimenuitem>Rescan Macros</guimenuitem>
220    command to update the macro list.
221  </para>
222 </sect1>
223
224</chapter>
225