PageRenderTime 63ms CodeModel.GetById 58ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
XML | 242 lines | 212 code | 27 blank | 3 comment | 0 complexity | 7b1786265a4371ba6f152f610b8cd4c8 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 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. 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 it.
 71  </para>
 72
 73  <para>
 74   If a complicated operation only needs to be repeated a few
 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 of a temporary macro is complete, jEdit does not display
 85   the buffer containing the recorded commands, but the name
 86   <filename>Temporary_Macro.bsh</filename> will be visible on any list of
 87   open buffers. By switching to that buffer, you can view the commands,
 88   edit them, and save them if you wish to
 89   a permanent macro file. Whether or not you look at or save the temporary
 90   macro contents, it is immediately available for playback.
 91  </para>
 92
 93  <para>
 94   <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Temporary
 95   Macro</guimenuitem> (shortcut:
 96   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
 97   <keycombo><keycap>Control</keycap><keycap>P</keycap></keycombo>) plays
 98   the macro recorded to the <filename>Temporary_Macro.bsh</filename> buffer.
 99  </para>
100
101  <para>
102    Only one temporary macro is available at a time. If you begin recording
103    a second temporary macro, the first is erased and cannot be recovered
104    unless you have saved the contents to a file with a name other than
105    <filename>Temporary_Macro.bsh</filename>.
106    If you do not save the temporary macro, you must keep the buffer
107    containing the macro script open during your jEdit session. To have the
108    macro available for your next jEdit session, save the buffer
109    <filename>Temporary_Macro.bsh</filename> as an ordinary macro with a
110    descriptive name of your choice. The new name will then be displayed in
111    the <guimenu>Macros</guimenu> menu.
112  </para>
113</sect1>
114
115<sect1 id="running-macros"><title>Running Macros</title>
116
117  <para>
118    Macros supplied with jEdit, as well as macros that you record or write,
119    are displayed under the <guimenu>Macros</guimenu> menu in a
120    hierarchical structure. The jEdit installation includes about 30 macros
121    divided into several major categories. Each category corresponds to a
122    nested submenu under the <guimenu>Macros</guimenu> menu. An index of
123    these macros containing short descriptions and usage notes is found in
124    <xref linkend="macro-index"/>.
125  </para>
126
127  <para>
128    There is a very large collection of additional macros available at the
129    <ulink url="http://community.jedit.org">jEdit
130    community</ulink> web site in the <quote>Downloads</quote> section.  The
131    collection includes macros distributed with earlier versions of jEdit
132    as well as many macros contributed by members of the jEdit
133    development team and other users. There are detailed descriptions for
134    each entry as well as a search facility.
135  </para>
136
137  <para>
138    To run a macro, choose the <guimenu>Macros</guimenu> menu,
139    navigate through the hierarchy of submenus, and select the name
140    of the macro to execute.  You can also assign execution of a
141    particular macro to a keyboard shortcut, toolbar button or
142    context menu using the
143    <guimenuitem>Macro Shortcuts</guimenuitem>,
144    <guimenuitem>Tool Bar</guimenuitem> or
145    <guimenuitem>Context Menu</guimenuitem> panes of the
146    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
147    Options</guimenuitem> dialog; see
148    <xref linkend="global-opts"/>.
149  </para>
150
151  <para>
152    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Last Macro</guimenuitem>
153    (shortcut:
154    <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>
155    <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>)
156    runs the last macro run by jEdit again.
157  </para>
158
159  <sidebar><title>XInsert plugin</title>
160   <para>
161    The <application>XInsert</application> plugin has a feature that
162    lists the title of macros, organized by subdirectories, as part of
163    its tree list display.  Clicking on the leaf of the tree
164    corresponding to a macro name causes jEdit to execute the macro
165    immediately.  The plugin allows you to keep a list of macros and
166    cut-and-paste text fragments available while editing
167    without opening menus. For information about installing plugins, see
168    <xref linkend="using-plugins"/>.
169   </para>
170  </sidebar>
171
172</sect1>
173
174<sect1 id="organizing-macros"><title>How jEdit Organizes Macros</title>
175  <para>
176   Every macro, whether or not you originally recorded it, is stored on
177   disk and can be edited as a text file. The file name of a macro
178   must have a <filename>.bsh</filename> extension in order for jEdit
179   to be aware of it.
180   By default, jEdit associates a
181   <filename>.bsh</filename> file with the BeanShell edit
182   mode for purposes of syntax highlighting, indentation and other
183   formatting. However, BeanShell syntax does not impose any indentation or
184   line break requirements.
185  </para>
186
187  <para>
188   The <guimenu>Macros</guimenu> menu
189   lists all macros stored in two places: the <filename>macros</filename>
190   subdirectory of the jEdit home directory, and the
191   <filename>macros</filename> subdirectory of the user-specific
192   settings directory (see <xref linkend="settings-directory"/> for
193   information about the settings directory). Any macros you record will be
194   stored in the user-specific directory.
195  </para>
196
197  <para>
198    Macros stored elsewhere can be run using the
199    <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other Macro</guimenuitem>
200    command, which
201    displays a file chooser dialog box, and runs the specified file.
202  </para>
203
204  <para>
205   The listing of individual macros in the <guimenu>Macros</guimenu> menu
206   can be organized in a hierarchy using subdirectories in the general
207   or user-specific macro directories; each subdirectory
208   appears as a submenu. You will find such a hierarchy in the
209   default macro set included with jEdit.
210  </para>
211
212  <para>
213   When jEdit first loads, it scans the designated macro directories and
214   assembles a listing of individual macros in the <guimenu>Macros</guimenu>
215   menu. When scanning the names, jEdit will delete underscore characters
216   and the <filename>.bsh</filename> extension for menu labels, so that
217   <filename>List_Useful_Information.bsh</filename>, for example, will be
218   displayed in the <guimenu>Macros</guimenu> menu as <guimenuitem>List
219   Useful Information</guimenuitem>.
220  </para>
221
222  <para>
223   You can browse the user and system macro directories by opening the
224   <filename>macros</filename> directory from the
225   <guimenu>Utilities</guimenu>&gt;<guimenuitem>jEdit Home Directory</guimenuitem>
226   and <guimenu>Utilities</guimenu>&gt;<guimenuitem>Settings Directory</guimenuitem>
227   menus.
228  </para>
229
230  <para>
231    Macros can be opened and edited much like ordinary files from the
232    file system browser. Editing macros from within jEdit will
233    automatically update the macros menu; however, if you modify macros
234    from another program or add macro files to the macro directories, you
235    should run the
236    <guimenu>Macros</guimenu>&gt;<guimenuitem>Rescan Macros</guimenuitem>
237    command to update the macro list.
238  </para>
239 </sect1>
240
241</chapter>
242