PageRenderTime 46ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

/jEdit/tags/jedit-4-2-pre4/doc/users-guide/using-macros.xml

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