Helpful Methods in the Macros Class
Prev | Chapter 13. Macro Basics | Next

## Helpful Methods in the Macros Class

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(` | Component | comp,
  | String | message`)`;

- `public static void error(` | Component | comp,
  | String | message`)`;

- `public static String input(` | Component | comp,
  | String | prompt`)`;

- `public static String input(` | Component | comp,
  | String | prompt,
  | String | defaultValue`)`;

- `public static int confirm(` | Component | comp,
  | String | prompt,
  | int | 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("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.

Prev | Up | Next
Predefined Variables in BeanShell | Home | BeanShell Dynamic Typing