Useful UI Methods

jEdit provides several methods and classes that make writing user interfaces easier. They provide default message and error popups, geometry save/restore, and dialog boxes that automatically respond to the Enter and Escape keys.

Canned Dialog Boxes

GUIUtilities.message() method

import java.awt.Frame;

public static void message(Frame frame, String name, Object[] args);

This method displays a message dialog box with title obtained from the property name.title and message from the property name.message. Elements of the args array are substituted into the message; see the section called Plugin Properties for details.

GUIUtilities.error() method

import java.awt.Frame;

public static void error(Frame frame, String name, Object[] args);

This method displays an error dialog box. The only difference between a message and error dialog box is the icon displayed. Otherwise it is exactly the same as a message.

GUIUtilities.input() method

import java.awt.Frame;

public static String input(Frame frame, String name, String defaultValue);

This method displays an input dialog box with title obtained from the property name.title and message from the property name.message. An input dialog box is similar to a message, except that a text field is added where the user can type a one-line string. The defaultValue parameter is the initial contents of the text field. When the user enters a value and clicks OK, the currently entered value is returned. If they click Cancel, the method returns null.

GUIUtilities.inputProperty() method

import java.awt.Frame;

public static String inputProperty(Frame frame, String name, String property);

This method is exactly the same as input() except that the value entered by the user is automatically stored in the property named property.

GUIUtilities.showFileDialog() method

import org.gjt.sp.jedit.View;

public static String showFileDialog(View view, String file, int type);

This method is a wrapper around the JFileChooser class. It displays a file chooser dialog, with the file named file selected. The type parameter is either JFileChooser.OPEN_DIALOG or JFileChooser.SAVE_DIALOG. This method returns null if the user clicks Cancel, otherwise the selected pathname is returned.

Examples

The following example displays the I/O error dialog box, which is already defined in jEdit's properties:

String[] args = { "just joking" };
 GUIUtilities.error(view,"ioerror",args);

The following example displays a custom dialog box, assuming that the properties example.title and example.message are defined:

GUIUtilities.message(view,"example",null);

Saving Window Geometry

Users expect non-modal dialog boxes and frames to open up where they last put them. jEdit's geometry methods provide an easy way to do this.

GUIUtilities.loadGeometry() method

import java.awt.Window;

public static void loadGeometry(Window window, String name);

This method loads a set of geometry properties prefixed with name. This should be called just before the window is shown to the user. Here is an example of its usage:

pack();
GUIUtilities.loadGeometry(this,"hypersearch");
show();

GUIUtilities.saveGeometry() method

import java.awt.Window;

public static void saveGeometry(Window window, String name);

This method saves the geometry of the window to a set of properties prefixed with name. This should be called before the window is closed. Here is an example of its usage:

GUIUtilities.saveGeometry(this,"hypersearch");
dispose();

Improved Dialog Box Key Handling

The org.gjt.sp.jedit.gui.EnhancedDialog and org.gjt.sp.jedit.gui.EnhancedFrame classes automatically handle presses of the Enter and Escape keys, which is something the standard AWT and Swing classes do not do.

EnhancedDialog class

public class EnhancedDialog
{
        public EnhancedDialog(Frame frame, String title, boolean modal);
        public abstract void ok();
        public abstract void cancel();
}

The constructor accepts the same parameters as the JDialog constructor. The ok() method is called when the Enter key is pressed inside one of the dialog's components; cancel() is called when Escape is called. Note that you still have to create your own OK and Cancel buttons; this class only handles the keystrokes for you.

EnhancedFrame class

public class EnhancedFrame
{
        public EnhancedFrame(String title);
        public abstract void ok();
        public abstract void cancel();
}

This class provides the same functionality for frames.