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.

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.