/jEdit/tags/jedit-4-5-pre1/doc/FAQ/faq-macros.xml

<?xml version="1.0" encoding="UTF-8"?>
<section id="macros">
    <title>Macros</title>
    <!-- jEdit buffer-local properties:                      -->
    <!-- :indentSize=4:noTabs=false:maxLineLen=72:tabSize=4: -->
    <!-- :xml.root=faq.xml:                                  -->
    <!-- jEdit FAQ                                           -->
    <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("full_path")</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>
</section>