Including message()
, there are five static methods
in the Macros class that allow you to converse
easily with your macros. They all encapsulate calls to methods of the
Java platform's JOptionPane
class.
public static void message( | comp, | |
comp, | ||
message) ; |
public static void error( | comp, | |
comp, | ||
message) ; |
public static String input( | comp, | |
comp, | ||
prompt) ; |
public static String input( | comp, | |
comp, | ||
prompt, | ||
defaultValue) ; |
public static int confirm( | comp, | |
comp, | ||
prompt, | ||
buttons) ; |
The format of these four declarations provides a
concise reference to the way in which the methods may be used. The
keyword public
means that the method can be used
outside the Macros class. The alternatives are
private
and protected
. For
purposes of BeanShell, you just have to know that BeanShell can only use
public methods of other Java classes. The keyword
static
we have already discussed. It means that the
method does not operate on a particular object. You call a static
function using the name of the class (like
Macros) rather than the name of a particular
object (like view
). The third word is the type of the
value returned by the method. The keyword void
is
Java's way of saying the the method does not have a return value.
The error()
method works just like
message()
but displays an error icon in the message
box. The input()
method furnishes a text field for
input, an OK button and a
Cancel button. If Cancel is pressed,
the method returns null
. If OK
is pressed, a String
containing the contents of
the text field is returned. Note that there are two forms of the
input()
method; the first form with two parameters
displays an empty input field, the other forms lets you specify an initial,
default input value.
For those without Java experience, it is important to know that
null
is not the same as an
empty, “zero-length” String
. It is
Java's way of saying that there is no object associated with this
variable. Whenever you seek to use a return value from
input()
in your macro, you should test it to see if
it is null
. In most cases, you will
want to exit gracefully from the script with a
return
statement, because the presence of a null
value for an input variable usually means that the user intended to
cancel macro execution. BeanShell will complain if you call any
methods on a null
object.
The confirm()
method in the
Macros class is a little more complex. The
buttons
parameter has an int
type, and the usual way to supply a value is to use one of
the predefined values taken from Java's
JOptionPane
class. You can choose among
JOptionPane.YES_NO_OPTION
,
JOptionPane.YES_NO_CANCEL_OPTION
, or
JOptionPane.OK_CANCEL_OPTION
. The return
value of the method is also an int
, and should be tested
against the value of other predefined constants:
JOptionPane.YES_OPTION
,
JOptionPane.NO_OPTION
,
JOptionPane.OK_OPTION
or
JOptionPane.CANCEL_OPTION
.
We've looked at using Macros.message()
. To
use the other methods, you would write something like the
following:
Macros.error(view, "Goodbye, cruel world!"); String result = Macros.input(view, "Type something here."); String result = Macros.input(view, "When were you born?", "I don't remember, I was very young at the time"); int result = Macros.confirm(view, "Do you really want to learn" + " about BeanShell?",JOptionPane.YES_NO_OPTION);
In the last three examples, placing the word String
or int
before the variable name result
tells BeanShell that
the variable refers to an integer or a String
object, even
before a particular value is assigned to the variable.
In BeanShell, this declaration of the
type of result
is not
necessary; BeanShell can figure it out when the macro runs. This can be
helpful if you are not comfortable with specifying types and classes;
just use your variables and let BeanShell worry about it.
Note that macros are not limited to using these methods for presenting a user interface. In fact, full-blown user interfaces using the Java Swing APIs are also possible, and will be covered later on in Chapter 14, A Dialog-Based Macro.