/jEdit/tags/jedit-4-3-pre5/doc/FAQ/faq-macros.xml

<!-- jEdit buffer-local properties:                      -->
<!-- :indentSize=4:noTabs=false:maxLineLen=72:tabSize=4: -->
<!-- :xml.root=faq.xml:                                  -->

<!-- jEdit FAQ                                           -->
<!-- Copyright (C) 2003 John Gellene, Kris Kopicki       -->

<sect1 id="macros"><title>Macros</title>
<para>
  This section deals with questions on writing and running macros.
</para>

<qandaset defaultlabel="qanda">

<qandadiv id="macro-using"><title>Using macros</title>

<qandaentry>
	<question id="macro-getting">
		<para>
			Where can I get macro's from?
		</para>
	</question>
	<answer>
		<para>
			There is a plugin available called MacroManager that will provide a
			similar interface to jEdit's plugin manager for installing new macros.
			The plugin downloads the macros from the jEdit Community site, so an
			internet connection is necessary.
		</para>
	</answer>
</qandaentry>

<qandaentry>
  <question id="macro-new-store">
    <para>
      I just wrote a new macro for myself.  Where should I save the
      file?
    </para>
  </question>
  <answer>
    <para>
      There is a <filename>macros</filename> directory in your user
      settings directory. If you store your macro there it will appear in
      jEdit's <guimenu>Macros</guimenu> menu under the name you have
      given to the macro's source code file.  The
      <filename>.bsh</filename> will be deleted in the macro entry, and
      underscore characters will be converted to whitespace, so that the
      file <filename>My_New_Macro.bsh</filename> will be displayed as
      <guimenuitem>My New Macro</guimenuitem>.
    </para>
    <para>
      You can create additional subdirectories in the
      <filename>macros</filename>to organize your personal macros by
      category. Each subdirectory will correspond to a submenu
      under the application's <guimenu>Macros</guimenu> menu.  This is
      helpful to reduce the screen space used to display the macros menu
      at any one time.
    </para>
    </answer>
</qandaentry>

<qandaentry>
  <question id="macro-new-ext">
    <para>
      Do I have to use the <filename>.bsh</filename> file extension when
      I save one of my own macro scripts?
    </para>
  </question>
  <answer>
    <para>
      You need the <filename>.bsh</filename> extension in order for
      jEdit to detect and display the name of the macro in its
      <guimenu>Macros</guimenu> menu.  The macro must also be in the
      <filename>macros</filename> directory of either the jEdit
      installation directory or the user settings directory.
    </para>
    <para>
      You do not need the extension to run a macro, however.  By
      selecting <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other
      Macro...</guimenuitem>, you can choose any file to be run as a
      macro. While in a macro, you can
      call <userinput>source(&quot;full_path&quot;)</userinput>
      to do the same thing.
    </para>
  </answer>
</qandaentry>

<qandaentry>
  <question id="macro-temp">
    <para>
      How can I store the result of a macro so that the next time I run it
      the macro can retrieve the value?
    </para>
  </question>
  <answer>
    <para>
      You can use either <userinput>jEdit.setProperty(String,
      String)</userinput> or <userinput>jEdit.setTemporaryProperty(String,
      String)</userinput>. Both methods
      take <classname>String</classname> values for the name of the
      property and its value.  If you use
      <userinput>setProperty()</userinput>, the property will remain in
      jEdit's property store permanently, so if you only need the value
      during the course of a single editing session, use
      <userinput>setTemporaryProperty()</userinput>.
    </para>
    <para>
      To ensure that your value can be stored regardless of its type,
      use the following
      syntax:<programlisting>jEdit.setTemporaryProperty("myValueName", myValue.toString());</programlisting>
      and remember to convert the <quote>myValueName</quote> property
      back to its intended type when you retrieve it.
    </para>
  </answer>
</qandaentry>

<qandaentry>
	<question id="macro-exec">
		<para>
			In a macro I'd like to exec an external program (e.g. jmk, javac) and capture
			its output to a buffer. I'd also like to see this output as the
			external program runs or be able to interact with the program. So when I exec,
			what happens to System.in/out/err of the exec'd program?
		</para>
	</question>
	<answer>
		<para>
			Use the <filename>runInSystemShell()</filename> or the
			<filename>runCommandToBuffer()</filename> script methods that come
			bundled with the Console plugin. The help documentation for Console provides
			details on these methods. Currently the Console's System shell is not
			interactive during execution of a command, but it does receive and display the
			standard output and error streams of the external process.
		</para>
	</answer>
</qandaentry>

</qandadiv>

</qandaset>

</sect1>