PageRenderTime 8ms CodeModel.GetById 1ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-0-pre3/doc/users-guide/using-macros.xml

#
XML | 223 lines | 195 code | 25 blank | 3 comment | 0 complexity | c379942ed7de9900ca68b15a096f16b0 MD5 | raw file
  1<!-- jEdit buffer-local properties:                              -->
  2<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2:           -->
  3<!-- :collapseFolds=0:                                           -->
  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 wasy 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. In this section we
 14    describe how to record and run macros. A detailed guide on
 15    writing macros appears later in a separate part of the user's
 16    guide; see <xref linkend="writing-macros-part"/>.
 17  </para>
 18
 19<sect1 id="recording-macros"><title>Recording Macros</title>
 20
 21  <para>
 22     The simplest use of macros is to record a series of key strokes and
 23     menu commands as a BeanShell script, and play them back at a later
 24     time. While this doesn't let you take advantage of the full power of
 25     BeanShell, it is still a great time saver and can even be used to
 26     <quote>prototype</quote> more complicated macros.
 27  </para>
 28
 29  <para>
 30    <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Macro</guimenuitem>
 31    (shortcut:
 32    <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 33    <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>) prompts
 34    for a macro name and begins recording.
 35  </para>
 36
 37  <para>
 38    While recording is in progress, the string <quote>Macro
 39    recording</quote> is displayed in the status bar. jEdit records the
 40    following:
 41  </para>
 42
 43  <itemizedlist>
 44    <listitem><para>Key strokes</para></listitem>
 45    <listitem><para>Menu item commands</para></listitem>
 46    <listitem><para>Tool bar clicks</para></listitem>
 47    <listitem><para>All search and replace operations except incremental
 48    search</para></listitem>
 49  </itemizedlist>
 50
 51  <para>
 52   Mouse clicks in the text area are <emphasis>not</emphasis> recorded; to
 53   record the equivalent of mouse operations, use the text selection commands
 54   or arrow keys.
 55  </para>
 56
 57  <para>
 58   <guimenu>Macros</guimenu>&gt;<guimenuitem>Stop Recording</guimenuitem>
 59   (shortcut: <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 60   <keycombo><keycap>Control</keycap><keycap>S</keycap></keycombo>) stops
 61   recording. It also switches to the buffer containing the recorded macro,
 62   giving you a chance to check over the recorded commands and make any
 63   necessary changes. The file name extension <filename>.bsh</filename> is
 64   automatically appended to the macro name, and all spaces are converted
 65   to underscore characters, in order to make the macro name a valid file
 66   name. These two operations are reversed when macros are displayed in the
 67   <guimenu>Macros</guimenu> menu. See <xref linkend="organizing-macros"/>
 68   for details. When you are happy with the macro, save the buffer and it
 69   will appear in the <guimenu>Macros</guimenu> menu. To discard the macro,
 70   close the buffer without saving.
 71  </para>
 72
 73  <para>
 74   If a complicated operation only needs to be repeated a few of
 75   times, using the temporary macro feature is quicker than saving a new
 76   macro file.
 77  </para>
 78  <para>
 79   <guimenu>Macros</guimenu>&gt;<guimenuitem>Record Temporary
 80   Macro</guimenuitem> (shortcut:
 81   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 82   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>) begins
 83   recording to a buffer named <filename>Temporary_Macro.bsh</filename>.
 84   Once recording is complete, you don't need to save the
 85   <filename>Temporary_Macro.bsh</filename>buffer before playing it back.
 86  </para>
 87  <para>
 88   <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Temporary
 89   Macro</guimenuitem> (shortcut:
 90   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 91   <keycombo><keycap>Control</keycap><keycap>P</keycap></keycombo>) plays
 92   the macro recorded to the <filename>Temporary_Macro.bsh</filename> buffer.
 93  </para>
 94
 95  <para>
 96   If you do not save the temporary macro, you must keep the buffer
 97   containing the macro script open during your jEdit session. To have the
 98   macro available for your next jEdit session, save the buffer
 99   <filename>Temporary_Macro.bsh</filename> as an ordinary macro with a
100   descriptive name of your choice. The new name will then be displayed in
101   the <guimenu>Macros</guimenu> menu.
102  </para>
103</sect1>
104
105<sect1 id="running-macros"><title>Running Macros</title>
106
107  <para>
108    Macros supplied with jEdit, as well as macros that you record or write,
109    are displayed under the <guimenu>Macros</guimenu> menu in a
110    hierarchical structure. The jEdit installation includes about 50 macros
111    divided into several major categories. Each category corresponds to a
112    nested submenu under the <guimenu>Macros</guimenu> menu. An index of
113    these macros containing short descriptions and usage notes is found in
114    <xref linkend="macro-index"/>.
115  </para>
116
117  <para>
118    To run a macro, choose the <guimenu>Macros</guimenu> menu,
119    navigate through the hierarchy of submenus, and select the name
120    of the macro to execute.  You can also assign execution of a
121    particular macro to a keyboard shortcut, toolbar button or
122    context menu using the
123    <guimenuitem>Macro Shortcuts</guimenuitem>,
124    <guimenuitem>Tool Bar</guimenuitem> or
125    <guimenuitem>Context Menu</guimenuitem> panes of the
126    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
127    Options</guimenuitem> dialog; see
128    <xref linkend="global-opts"/>.
129  </para>
130
131  <para>
132    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Last Macro</guimenuitem>
133    (shortcut:
134    <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
135    <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>)
136    runs the last macro run by jEdit again.
137  </para>
138
139  <sidebar><title>XInsert plugin</title>
140   <para>
141    The <application>XInsert</application> plugin has a feature that
142    lists the title of macros, organized by subdirectories, as part of
143    its tree list display.  Clicking on the leaf of the tree
144    corresponding to a macro name causes jEdit to execute the macro
145    immediately.  The plugin allows you to keep a list of macros and
146    cut-and-paste text fragments available while editing
147    without opening menus. For information about installing plugins, see
148    <xref linkend="using-plugins"/>.
149   </para>
150  </sidebar>
151
152</sect1>
153
154<sect1 id="organizing-macros"><title>How jEdit Organizes Macros</title>
155  <para>
156   Every macro, whether or not you originally recorded it, is stored on
157   disk and can be edited as a text file. The file names of macros
158   must have a <filename>.bsh</filename> extension.
159   By default, jEdit associates a
160   <filename>.bsh</filename> file with the BeanShell edit
161   mode for purposes of syntax highlighting, indentation and other
162   formatting. However, BeanShell syntax does not impose any indentation or
163   line break requirements.
164  </para>
165
166  <para>
167   The <guimenu>Macros</guimenu> menu
168   lists all macros stored in two places: the <filename>macros</filename>
169   subdirectory of the jEdit install directory, and the
170   <filename>macros</filename> subdirectory of the user-specific
171   settings directory (see <xref linkend="settings-directory"/> for
172   information about the settings directory). Any macros you record will be
173   stored in the user-specific directory.
174  </para>
175
176  <para>
177    Macros stored elsewhere can be run using the
178    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other Macro</guimenuitem>
179    command, which
180    displays a file chooser dialog box, and runs the specified file.
181  </para>
182
183  <para>
184   The listing of individual macros in the <guimenu>Macros</guimenu> menu
185   can be organized in a hierarchy using subdirectories in the general
186   or user-specific macro directories; each subdirectory
187   appears as a submenu. You will find such a hierarchy in the
188   default macro set included with jEdit.
189  </para>
190
191  <para>
192   When jEdit first loads, it scans the designated macro directories and
193   assembles a listing of individual macros in the <guimenu>Macros</guimenu>
194   menu. When scanning the names, jEdit will delete underscore characters
195   and the <filename>.bsh</filename> extension for menu labels, so that
196   <filename>List_Useful_Information.bsh</filename>, for example, will be
197   displayed in the <guimenu>Macros</guimenu> menu as <guimenuitem>List
198   Useful Information</guimenuitem>.
199  </para>
200
201  <para>
202    <guimenu>Macros</guimenu>&gt;<guimenuitem>Browse System Macros</guimenuitem>
203    displays the <filename>macros</filename> subdirectory of the
204    directory in which jEdit is installed in the file system browser.
205  </para>
206
207  <para>
208    <guimenu>Macros</guimenu>&gt;<guimenuitem>Browse User Macros</guimenuitem>
209    displays the <filename>macros</filename> subdirectory of the
210    user settings directory in the file system browser.
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, the
218    <guimenu>Macros</guimenu>&gt;<guimenuitem>Rescan Macros</guimenuitem>
219    will need to be invoked to update the macro list.
220  </para>
221 </sect1>
222
223</chapter>