PageRenderTime 57ms CodeModel.GetById 52ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
XML | 127 lines | 109 code | 14 blank | 4 comment | 0 complexity | 4fcf65c0ba27f68cba0814315c392e2e MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<section id="macros">
  3    <title>Macros</title>
  4    <!-- jEdit buffer-local properties:                      -->
  5    <!-- :indentSize=4:noTabs=false:maxLineLen=72:tabSize=4: -->
  6    <!-- :xml.root=faq.xml:                                  -->
  7    <!-- jEdit FAQ                                           -->
  8    <para>This section deals with questions on writing and running
  9    macros.</para>
 10
 11    <qandaset defaultlabel="qanda">
 12        <qandadiv id="macro-using">
 13            <title>Using macros</title>
 14
 15            <qandaentry>
 16                <question id="macro-getting">
 17                    <para>Where can I get macro's from?</para>
 18                </question>
 19
 20                <answer>
 21                    <para>There is a plugin available called MacroManager that
 22                    will provide a similar interface to jEdit's plugin manager
 23                    for installing new macros. The plugin downloads the macros
 24                    from the jEdit Community site, so an internet connection is
 25                    necessary.</para>
 26                </answer>
 27            </qandaentry>
 28
 29            <qandaentry>
 30                <question id="macro-new-store">
 31                    <para>I just wrote a new macro for myself. Where should I
 32                    save the file?</para>
 33                </question>
 34
 35                <answer>
 36                    <para>There is a <filename>macros</filename> directory in
 37                    your user settings directory. If you store your macro there
 38                    it will appear in jEdit's <guimenu>Macros</guimenu> menu
 39                    under the name you have given to the macro's source code
 40                    file. The <filename>.bsh</filename> will be deleted in the
 41                    macro entry, and underscore characters will be converted to
 42                    whitespace, so that the file
 43                    <filename>My_New_Macro.bsh</filename> will be displayed as
 44                    <guimenuitem>My New Macro</guimenuitem>.</para>
 45
 46                    <para>You can create additional subdirectories in the
 47                    <filename>macros</filename>to organize your personal macros
 48                    by category. Each subdirectory will correspond to a submenu
 49                    under the application's <guimenu>Macros</guimenu> menu. This
 50                    is helpful to reduce the screen space used to display the
 51                    macros menu at any one time.</para>
 52                </answer>
 53            </qandaentry>
 54
 55            <qandaentry>
 56                <question id="macro-new-ext">
 57                    <para>Do I have to use the <filename>.bsh</filename> file
 58                    extension when I save one of my own macro scripts?</para>
 59                </question>
 60
 61                <answer>
 62                    <para>You need the <filename>.bsh</filename> extension in
 63                    order for jEdit to detect and display the name of the macro
 64                    in its <guimenu>Macros</guimenu> menu. The macro must also
 65                    be in the <filename>macros</filename> directory of either
 66                    the jEdit installation directory or the user settings
 67                    directory.</para>
 68
 69                    <para>You do not need the extension to run a macro, however.
 70                    By selecting <guimenu>Macros</guimenu>&gt;<guimenuitem>Run
 71                    Other Macro...</guimenuitem>, you can choose any file to be
 72                    run as a macro. While in a macro, you can call
 73                    <userinput>source("full_path")</userinput> to do the same
 74                    thing.</para>
 75                </answer>
 76            </qandaentry>
 77
 78            <qandaentry>
 79                <question id="macro-temp">
 80                    <para>How can I store the result of a macro so that the next
 81                    time I run it the macro can retrieve the value?</para>
 82                </question>
 83
 84                <answer>
 85                    <para>You can use either
 86                    <userinput>jEdit.setProperty(String, String)</userinput> or
 87                    <userinput>jEdit.setTemporaryProperty(String,
 88                    String)</userinput>. Both methods take
 89                    <classname>String</classname> values for the name of the
 90                    property and its value. If you use
 91                    <userinput>setProperty()</userinput>, the property will
 92                    remain in jEdit's property store permanently, so if you only
 93                    need the value during the course of a single editing
 94                    session, use
 95                    <userinput>setTemporaryProperty()</userinput>.</para>
 96
 97                    <para>To ensure that your value can be stored regardless of
 98                    its type, use the following syntax:<programlisting>jEdit.setTemporaryProperty("myValueName", myValue.toString());</programlisting>
 99                    and remember to convert the <quote>myValueName</quote>
100                    property back to its intended type when you retrieve
101                    it.</para>
102                </answer>
103            </qandaentry>
104
105            <qandaentry>
106                <question id="macro-exec">
107                    <para>In a macro I'd like to exec an external program (e.g.
108                    jmk, javac) and capture its output to a buffer. I'd also
109                    like to see this output as the external program runs or be
110                    able to interact with the program. So when I exec, what
111                    happens to System.in/out/err of the exec'd program?</para>
112                </question>
113
114                <answer>
115                    <para>Use the <filename>runInSystemShell()</filename> or the
116                    <filename>runCommandToBuffer()</filename> script methods
117                    that come bundled with the Console plugin. The help
118                    documentation for Console provides details on these methods.
119                    Currently the Console's System shell is not interactive
120                    during execution of a command, but it does receive and
121                    display the standard output and error streams of the
122                    external process.</para>
123                </answer>
124            </qandaentry>
125        </qandadiv>
126    </qandaset>
127</section>