/www/tags/NOV_07_2009/htdocs/users-guide/helpful-methods.html
HTML | 92 lines | 89 code | 3 blank | 0 comment | 0 complexity | e5aff898fdaed16a0ff1ca180443684a 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<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Helpful Methods in the Macros Class</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="jEdit 4.3 User's Guide"><link rel="up" href="macro-basics.html" title="Chapter 13. Macro Basics"><link rel="prev" href="predefined-variables.html" title="Predefined Variables in BeanShell"><link rel="next" href="dynamic-typing.html" title="BeanShell Dynamic Typing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Helpful Methods in the Macros Class</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="predefined-variables.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Macro Basics</th><td width="20%" align="right"> <a accesskey="n" href="dynamic-typing.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="helpful-methods"></a>Helpful Methods in the Macros Class</h2></div></div></div><p>Including <code class="function">message()</code>, there are five static
2 methods in the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class that
3 allow you to converse easily with your macros. They all encapsulate
4 calls to methods of the Java platform's
5 <code class="classname">JOptionPane</code> class.</p><div class="itemizedlist"><ul type="disc"><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static void
6 <b class="fsfunc">message</b>(</code></td><td>Component
7 </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
8 </td><td><var class="pdparam">message</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static void
9 <b class="fsfunc">error</b>(</code></td><td>Component
10 </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
11 </td><td><var class="pdparam">message</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static String
12 <b class="fsfunc">input</b>(</code></td><td>Component
13 </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
14 </td><td><var class="pdparam">prompt</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static String
15 <b class="fsfunc">input</b>(</code></td><td>Component
16 </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
17 </td><td><var class="pdparam">prompt</var>, </td></tr><tr><td> </td><td>String
18 </td><td><var class="pdparam">defaultValue</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static int
19 <b class="fsfunc">confirm</b>(</code></td><td>Component
20 </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
21 </td><td><var class="pdparam">prompt</var>, </td></tr><tr><td> </td><td>int </td><td><var class="pdparam">buttons</var><code>)</code>;</td></tr></table></div></li></ul></div><p>The format of these four <em class="glossterm">declarations</em>
22 provides a concise reference to the way in which the methods may be
23 used. The keyword <code class="function">public</code> means that the method can
24 be used outside the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class. The
25 alternatives are <code class="function">private</code> and
26 <code class="function">protected</code>. For purposes of BeanShell, you just have
27 to know that BeanShell can only use public methods of other Java
28 classes. The keyword <code class="function">static</code> we have already
29 discussed. It means that the method does not operate on a particular
30 object. You call a static function using the name of the class (like
31 <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a>) rather
32 than the name of a particular object (like <code class="varname">view</code>). The
33 third word is the type of the value returned by the method. The keyword
34 <code class="function">void</code> is Java's way of saying the the method does
35 not have a return value.</p><p>The <code class="function">error()</code> method works just like
36 <code class="function">message()</code> but displays an error icon in the message
37 box. The <code class="function">input()</code> method furnishes a text field for
38 input, an <span class="guilabel"><strong>OK</strong></span> button and a
39 <span class="guilabel"><strong>Cancel</strong></span> button. If <span class="guilabel"><strong>Cancel</strong></span> is
40 pressed, the method returns <code class="constant">null</code>. If
41 <span class="guilabel"><strong>OK</strong></span> is pressed, a <code class="classname">String</code>
42 containing the contents of the text field is returned. Note that there
43 are two forms of the <code class="function">input()</code> method; the first form
44 with two parameters displays an empty input field, the other forms lets
45 you specify an initial, default input value.</p><p>For those without Java experience, it is important to know that
46 <code class="constant">null</code> is <span class="emphasis"><em>not</em></span> the same as an
47 empty, “<span class="quote">zero-length</span>” <code class="classname">String</code>. It is
48 Java's way of saying that there is no object associated with this
49 variable. Whenever you seek to use a return value from
50 <code class="function">input()</code> in your macro, you should test it to see if
51 it is <code class="constant">null</code>. In most cases, you will want to exit
52 gracefully from the script with a <code class="function">return</code> statement,
53 because the presence of a null value for an input variable usually means
54 that the user intended to cancel macro execution. BeanShell will
55 complain if you call any methods on a <code class="constant">null</code>
56 object.</p><p>The <code class="function">confirm()</code> method in the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class is a
57 little more complex. The <code class="varname">buttons</code> parameter has an
58 <code class="classname">int</code> type, and the usual way to supply a value is
59 to use one of the predefined values taken from Java's
60 <code class="classname">JOptionPane</code> class. You can choose among
61 <code class="constant">JOptionPane.YES_NO_OPTION</code>,
62 <code class="constant">JOptionPane.YES_NO_CANCEL_OPTION</code>, or
63 <code class="constant">JOptionPane.OK_CANCEL_OPTION</code>. The return value of
64 the method is also an <code class="classname">int</code>, and should be tested
65 against the value of other predefined constants:
66 <code class="constant">JOptionPane.YES_OPTION</code>,
67 <code class="constant">JOptionPane.NO_OPTION</code>,
68 <code class="constant">JOptionPane.OK_OPTION</code> or
69 <code class="constant">JOptionPane.CANCEL_OPTION</code>.</p><p>We've looked at using <code class="function">Macros.message()</code>. To
70 use the other methods, you would write something like the
71 following:</p><div class="informalexample"><pre class="programlisting">Macros.error(view, "Goodbye, cruel world!");
72
73String result = Macros.input(view, "Type something here.");
74
75String result = Macros.input(view, "When were you born?",
76 "I don't remember, I was very young at the time");
77
78int result = Macros.confirm(view, "Do you really want to learn"
79 + " about BeanShell?",JOptionPane.YES_NO_OPTION);
80 </pre></div><p>In the last three examples, placing the word
81 <code class="classname">String</code> or <code class="classname">int</code> before the
82 variable name <code class="varname">result</code> tells BeanShell that the
83 variable refers to an integer or a <code class="classname">String</code> object,
84 even before a particular value is assigned to the variable. In
85 BeanShell, this <em class="glossterm">declaration</em> of the
86 <em class="glossterm">type</em> of <code class="varname">result</code> is not
87 necessary; BeanShell can figure it out when the macro runs. This can be
88 helpful if you are not comfortable with specifying types and classes;
89 just use your variables and let BeanShell worry about it.</p><p>Note that macros are not limited to using these methods for
90 presenting a user interface. In fact, full-blown user interfaces using
91 the Java Swing APIs are also possible, and will be covered later on in
92 <a class="xref" href="dialog-macro.html" title="Chapter 14. A Dialog-Based Macro">Chapter 14, <i>A Dialog-Based Macro</i></a>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="predefined-variables.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="macro-basics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dynamic-typing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Predefined Variables in BeanShell </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> BeanShell Dynamic Typing</td></tr></table></div></body></html>