<-- 

 Set TOPICTITLE = Common utilities in HIPE
 
-->

Did you spot something wrong or missing on this page? If you have an account on this TWiki, you can fix it yourself by editing the page. If you don't have an account, you can send a message to the Editorial Board to tell us about it. Thank you in advance!

• ia.gui.kernel.util.IconLibrary provides some static icons already loaded. If the icon you want to use is there, you are done.
• ia.gui.kernel.util.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.

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

• ia.gui.kernel.util.IconLibrary provides some static icons already loaded. If the icon you want to use is there, you are done.
• ia.gui.kernel.util.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.

Common utilities in HIPE

<-- 

 Set ALLOWTOPICCHANGE = RegisteredUsersGroup, TWikiAdminGroup
 
-->

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

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.

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 = ...;
InterpreterFactory.getInterpreter().set("yourVariable", variable);
SiteUtil.trigger(new VariablesCreatedEvent(this, Collections.singletonMap("yourVariable", variable)));

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

Dialogs with Java-like icons

PopupDialog belongs to ia_gui_kernel, so it can be used from any module in the project.

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.

Common Utilities In Hipe

• 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

SiteUtil class

Executing Jython statements

Sending execution events

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

• 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).

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.

Dialogs with Hipe-like icons

Dialogs with Java-like icons

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, title, option);
if (res == PopupDialog.YES) {
    saveFile();
}
if (res != PopupDialog.CANCEL && res != PopupDialog.CLOSED) {
    closeEditor();
}

• Set UTIL = SiteUtil

Triggering Events and Executing Statements In Hipe

SiteEventHandler interface

SiteUtil class

Executing Jython statements via the Event system

A Jython Example

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

Triggering Events and Executing Statement In Hipe

<-- summary -->

This section explains how you can send events to Hipe.

<--
   Some short-cuts 

 Set VIEWPART    = ViewPart
 
 Set EVENTHADLER = SiteEventHandler
 
 Set VIEWABLE    = Viewable
 
 Set UTIL        = SiteUtil
 
 Set COMMAND     = Command
 
 Set EXECUTION   = CommandExecutionRequestEvent
 
 Set EXECUTED   = CommandExecutedEvent
 
 Set CONSOLE   = ConsoleView
 
 Set HISTORY   = HistoryView
 
-->

<--
-->

SiteEventHandler interface

The standard way to trigger events is to get a reference to the %EVENTHADLER% interface which contains all related methods to the Hipe event system. This is typically achieved via the 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 it 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 lest one javax.swing.Component visible in Hipe).

Just assume that you are developing a Modifier for a task dialog and you want inform Hipe about executing a required statement: the Modifier interface gives you no reference to a VIEWPART so that you cannot trigger events. 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 via the Event system.

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 (you don't need to know about these views and their api). http://java.sun.com/docs/books/tutorial/uiswing/concurrency/ Every time an CommandExecutionRequestEvent event is served Hipe generates an equivalent CommandExecutedEvent event traces the original CommandExecutionRequestEvent event so that you can easily synchronize on the completion of execution. However this is not needed neither as 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 Jtyhon Example

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

• the reference used is _jconsole which is 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 thread).

from herschel.ia.gui.kernel 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()

-- NicolaDeCandussio - 05 Jun 2008