Common Utilities In Hipe

This section explains some common and recurrent tasks in Hipe, like:

• Communicating Views or Components with other Views or Components, by triggering events.
• Send Jython statements for being executed by the Console.
• The common way of showing errors and messages.
• How to load icons.

Triggering events

SiteEventHandler interface

The standard way of triggering events is to get a reference to the %EVENTHADLER% interface, which contains all related methods to the Hipe event system. This is typically done via the ViewPart interface that is passed on through the init method of the Viewable.

    private void someMethod() {
        :
        getPart().getEventHandler().trigger(aSiteEvent);
        :
    }

However there are cases where you do not have access to a Viewable and you still want to trigger events for informing the rest of the system about something. In order to achieve this you can use a utility method available in a dedicated utility class.

SiteUtil class

The SiteUtil class provides a set of convenience methods to get access to the Hipe architecture. In order to get its access one condition must be met:

you know at least a reference to a Component that is part of Hipe (i.e. you know at least one java.awt.Component visible in Hipe).

Just assume that you are developing a Modifier for a task dialog and you want to inform Hipe about executing a required statement: the Modifier interface gives you no reference to a ViewPart so that you cannot trigger events in the previous way. However you know that the Modifier is visible in Hipe and therefore you accomplish the SiteUtil constraint:

    private void someMethod() {
        :
        // this is the reference to the modifier
        SiteUtil.trigger(this, aSiteEvent);
        :
    }

Executing Jython statements

Sending execution events

Hipe has a dedicated Event for asking the execution of Jython statement: CommandExecutionRequestEvent. The event is served by the ConsoleView and the result of its execution is visible both in the screen of the ConsoleView and in the list of the HistoryView (but you don't need to know about these views and their api).

Every time a CommandExecutionRequestEvent event is served, Hipe generates an equivalent CommandExecutedEvent tracing the original CommandExecutionRequestEvent, so you can easily synchronize on the completion of the execution. However, this is not needed either, since SiteUtil class provides a convenient method for doing it: execAndWait.

    private void someMethod() {
        :
        // this is the reference to the modifier
        Command c = SiteUtil.execAndWait(this, "print 'something'");
        :
    }

The execAndWait method returns a Command tracing all the information about its execution including the statement result (isSuccesful()).

Last but not least, SiteUtil contains other utility methods that allow for more options including a un-synchronized execution method. See SiteUtil for the full detail.

A Jython Example

This example provides a short script for testing the SiteUtil execution functionality directly from the console. Please note:

• the reference used is _jconsole, which is a name available in jython and pointing to the jconsole (indeed visible).
• the call is synchronous and therefore it stops the gui thread for the time of the execution (see http://java.sun.com/docs/books/tutorial/uiswing/concurrency/ for a general discussion about gui and threads).

from herschel.ia.gui.kernel.util import SiteUtil
from javax.swing import *

frame = JFrame("Hello Jython")

def perform(event):
   SiteUtil.execAndWait(_jconsole, "2*2", "A")
   
button = JButton("Press me", actionPerformed = perform)

frame.add(button)
frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE)
frame.setSize(300, 300)
frame.show()

Creating variables

During the processing of a particular view, it may be wanted to create a variable, so that it is shown in the Variables view and the user can do a further work with it.

Creating a variable can be done either with or without echo to the console.

With echo to the console

Just use one of the methods provided by SiteUtil:

• Synchronous call: Command result = SiteUtil.execAndWait("yourVariable", "Something()");  // result will inform about the executed command

• Asynchronous call: SiteUtil.execLater("yourVariable", "Something()");  // request execution to the interpreter but return immediately

Prefer this way when you want the variable creation be recorded in the history, so it can be reproduced later.

Example: For the PolygonHistogramPanel we need to construct a Double1d with the corners of the polygon (which are listed in Double1d edges) and add it to the variables map of the task panel :

        Command c = SiteUtil.execAndWait("Double1d(" + edges.toString() + ")", "pyedges");
	String name = c.getOutputName();
	Object value = c.getOutputValue();
	VariableSelection edgesPixel = new VariableSelection(name, value);
	getMap().put(getTask().getSignature().getTaskParameter("edgesPixel"), edgesPixel);

Without echo to the console

In this case, you can create the variable with any Java code (not to be executed by the interpreter), and then publish it like this:

Object variable = ...;
VariablesUtil.setVariable("yourVariable", variable);

Prefer this way when the creation of the variable is so complex that doing it with Jython commands would be too difficult.

Showing popup dialogs

The PopupDialog class

The Java Swing library provides a class for showing popup dialogs: JOptionPane.
This class is used in different modules along the project.

Now, in order to unify the look and feel of dialogs, and to simplify the API as well (the calls to JOptionPane are normally too long), there is a wrapper class which should be used for showing popup dialogs in Hipe: PopupDialog.

Using this class we ensure that we use Hipe-like icons instead of Java-like icons:

Dialogs with Hipe-like icons

Dialogs with Java-like icons

PopupDialog belongs to ia_gui_kernel, so it can be used from virtually any module in the project (see jake.depend for exceptions).

You can use PopupDialog as well if your component is used by both HIPE and JIDE. It internally checks whether to show the HIPE style icons or the Java standard ones.

Sample Java code

The API is easy and self-explanatory, just consult PopupDialog.

For example, the first dialog above could be generated with the following code:

int option = PopupDialog.YES_NO_CANCEL_OPTION;
String title = "Unsaved changes";
String message = fileName + " has unsaved changes.\nSave before closing?";
int res =  PopupDialog.showConfirm(this, message, option, title);
if (res == PopupDialog.YES) {
    saveFile();
}
if (res != PopupDialog.CANCEL && res != PopupDialog.CLOSED) {
    closeEditor();
}

How to load icons

Icons are widely used in Hipe.

Instead of needing to work with the Java API directly, when you want to load icons, Hipe provides some utilities for making the job easier:

• IconLibrary provides some static icons already loaded. If the icon you want to use is there, you are done.
• IconLoader provides static methods for loading an icon: getIcon accepts a full path to an icon image, while getKernelIcon gets the provided icon image from the ia_gui_kernel location for icons.

If you want to add a new icon to the system in your own module, just use IconLoader.getIcon with the full path.