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