Difference: DpHipeTools (23 vs. 24)

Revision 242008-08-12 - JaimeSaiz

Line: 1 to 1
 
META TOPICPARENT name="DpHipe"

Adding Tools to HIPE

Added:
>
>
<--
   Some short-cuts  
-->
 Task, tools and variables

<-- summary -->
Changed:
<
<
Tools are processing units that operate on specific data elements. The well-known Tasks are examples of tools within HIPE. If a data element is selected, a list of tools that can operate on that data should appear. Double clicking on the tool will open a dialog for settings parameters.
>
>
Tools are processing units that operate on specific data elements.
From the Java point of view, a tool is an implementation of the Tool interface.
The well-known Tasks are examples of tools within HIPE. In this case, TaskTool is used under the hoods.

If a data element is selected, a list of tools that can operate on that data should appear. Double clicking on the tool will open an associated view (for non-task tools) or a dialog for settings parameters (for task tools).

  This section explains:
Added:
>
>
  • how you can create a Tool and register it for being available for dedicated data
 
  • how you can make HIPE aware of an existing Task,
  • how your task can react better on an active data element,
Changed:
<
<
  • the default task dialog and how you implement and contribute a dedicated the input dialog for your task,
>
>
  • the default task dialog and how you implement and contribute a dedicated input dialog for your task,
 
  • how you can implement and contribute a specific parameter editor
Line: 17 to 30
 
Deleted:
<
<
 
Changed:
<
<
<--
   Some short-cuts  
-->
>
>

Adding a Task as a Tool

 
Changed:
<
<

Task Registry

>
>

Task Registry

 
Up to now you have made you task globally available to the system by specifying an instance of that task within the __init__.py file of your sub-system, e.g.:

Line: 69 to 77
 
Changed:
<
<

Prime input validation

>
>

Prime input validation

 
The mechanism above makes you task to become a tool within the system and it appears whenever a variable of type SpecificProduct (i.e. the type of the value of the Parameter) is selected.
Line: 93 to 101
 
  • make your task appear as a tool within HIPE that can be ran against specific data.
Changed:
<
<

Tools dialog

>
>

Task Dialogs

Default Task Dialog

 

The system generates a default input dialog for all registered tasks within the software. As the system does not know the intent of your task, it can only provide a dry-listing of all requested parameters; such a dialog may not be suitable for your purposes.

Line: 113 to 124
 
Changed:
<
<

Parameter Modifiers

>
>

Parameter Modifiers

 
The system provides a default dialog displaying an input area for setting the values of the parameter based on a composition of Modifiers
Line: 132 to 143
 
  • Register it to the system.
Changed:
<
<

Implement a Modifier

>
>
Implement a Modifier
 
The Modifier interface consists of two explicit contracts
  • Support the drag and drop features (the set/getVariableSelection)
Line: 142 to 153
 
  • Have an empty constructor
Changed:
<
<

Register a Modifier

>
>
Register a Modifier
 
The registration of the Modifier is done again in the __init__.py via theExtensionRegistry with the usual syntax (please note the name of the factory: factory.modifier).
Line: 167 to 178
 
Changed:
<
<

Signature Components

>
>

Signature Components

 
In case the default input area based on Modifiers doesn't fit your needs you can just replace it by your own implementation.
Line: 179 to 190
 
  • Implement a Task Signature Component
  • Register it to the system.
Changed:
<
<

Implement a Task Signature Component

>
>
Implement a Task Signature Component
 
The TaskSignatureComponent interface consists of four explicit contracts
Line: 192 to 203
 
  • Have an empty constructor
Changed:
<
<

Register a Task Signature Component

>
>
Register a Task Signature Component
 

Line: 211 to 222
 
Changed:
<
<

Task Dialogs

>
>

Custom Task Dialogs

 Eventually, if the above options still do not accommodate you needs you can replace the the default Task Panel with your own implementation

If this is the case you need to:

  • Implement a Task Panel
  • Register it to the system.
Changed:
<
<

Implement a Task Panel

>
>
Implement a Task Panel
 
The TaskPanel interface consists of three explicit contracts
Line: 236 to 247
  rotate_panel.jpg
Changed:
<
<

Register a Task Panel

>
>
Register a Task Panel
 

Line: 254 to 265
 
Changed:
<
<

Triggering Events

For a full detailed section about triggering events have alook at DpHipeEventExecution

Task compliance

>
>

Task compliance

 
  • write user documentation (jtags)! That will be automatically picked up whenever a user asks the system for help on your task.
  • the name of the task should be a legal variable name in the global name-space. For example your instance of MyTask should report itself as e.g.: "myTask" and not "This is my task".
Line: 265 to 273
 
  • write a parameter validator for your prime parameter if your task should be listed not only on prime data type but on prime data contents as well.
Changed:
<
<
<-- Author: JorgoBakker - 21 Dec 2007 -->
>
>

Adding a Tool that is not a Task

If you have an existing task and want to make it available in HIPE, you just need to follow the steps described in the above section.

Now, a task has its limitations. It is somewhat an atomic operation for which you provide some inputs and expect some result.
Therefore, it is not expected for acting interactively with a user, and it is not meant for holding internal status either, that a user can modify during its execution.

If you need more flexibility, you can write your own implementation of the Tool interface.
Besides, you would most probably need a viewer associated to your tool, for letting the user interact with it.

This follows in some way the MVC pattern: your target data is the Model, your associated viewer is the View, and your tool is the Controller.

Tool Implementation

The Tool interface is simple:
public interface Tool {

    // Known categories to which a tool may belong to
    public enum Category { SPIRE, PACS, HIFI, GENERAL, IMAGE }
	
    // Get the tool name
    String getName();

    // Get the actual object that does the work
    Object getToolObject();

    // Set the actual object that does the work
    void setToolObject(Object o);

    // Get an array of categories to which this tool belongs to
    Category[] getCategories();

    // Return the prime input parameter
    Parameter getPrimeInput();
}
You provide the variable types you are interested in within the prime input: just return a ToolParameter initiated with the proper class of data you want to handle.
private ToolParameter _prime = new ToolParameter("data", MyTargetDataType.class);
public Parameter getPrimeInput() { return _prime; }

The actual job to be done can be delegated to a third object (the "tool object"), or just be executed by the tool class itself.
In this latter case, the method Object getToolObject() should return this.

Moreover, you may return the categories you think the tool is meaningful for, through the proper implementation of Category[] getCategories().

Tool Viewer

Every tool has an associated viewer, which must implement EditorComponent (by extending AbstractEditorComponent or one of its subclasses).

Tool Registry

Once you have your tool and the corresponding viewer, you need to register them like this:
# Associate the tool with the viewer
REGISTRY.register(COMPONENT,Extension(
                 "My Tool",
                 "herschel.path.to.MyToolComponent",
                 "factory.editor.tool",
                 "herschel.path.to.MyTool"))

# Register the tool so it is automatically available for the proper variables in HIPE
from herschel.ia.gui.kernel import ToolFactory
from herschel.path.to import MyTool
ToolFactory.register(MyTool())

Communicating Tool & Viewer

In the viewer, you can access the tool and the selected data within the makeEditorContent method provided by AbstractEditorComponent.
At this point, you can let the tool know about the viewer as well, if you want:
protected boolean makeEditorContent() {

    // Get the tool and the selected data
    ToolSelection selection = getSelection();
    Tool   tool = selection.getTool();
    Object data = selection.getSelection().getValue();

    // Optional - you would need to provide a setViewer method
    ((MyTool)tool).setViewer(this);

    // Build the editor contents ...
}
 
Added:
>
>

Simple sample

This simple reproducible example wraps up the just explained steps altogether.
It is just a button whose label is changed by the tool when the user clicks on it:

    1. The tool class

public class ButtonTool implements Tool {

    private Category[] _categories = { Category.GENERAL };
    private ToolParameter _prime = new ToolParameter("data", ArrayData.class);
    private ArrayData _data;
    private boolean _flag = true;

    public Category[] getCategories() {
	return _categories;
    }

    public String getName() {
	return "Button Tool";
    }

    public Parameter getPrimeInput() {
	return _prime;
    }

    public Object getToolObject() {
	return this;
    }

    public void setToolObject(Object o) {
	// do nothing
    }

    public void setData(ArrayData data) {
	_data = data;
    }

    void updateLabel(JButton button) {
	int size = _data.getSize();
	int rank = _data.getRank();
	button.setText("Data has " + (_flag? "size " + size : "rank " + rank));
	_flag = !_flag;
    }
}

    2. The viewer class

public class ButtonToolComponent extends AbstractEditorComponent<ToolSelection> {

    private static final long serialVersionUID = 1L;
    private static int _counter = 1;
    private ButtonTool _tool;

    public ButtonToolComponent() {
	super(new BorderLayout());
    }

    protected Class<ToolSelection> getSelectionType() {
	return ToolSelection.class;
    }

    protected boolean makeEditorContent() {
	final JButton button = new JButton();
	setName("Button Tool " + _counter++);
	_tool = (ButtonTool)getSelection().getTool();
	_tool.setData((ArrayData)getSelection().getSelection().getValue());
	_tool.updateLabel(button);
	button.addActionListener(new ActionListener() {
	    public void actionPerformed(ActionEvent e) {
	        _tool.updateLabel(button);
            }
	});
	add(button);
	return true;
    }

    public Icon getComponentIcon() {
	return IconLibrary.VARIABLE;
    }
}

    3. The registration

REGISTRY.register(COMPONENT,Extension(
                 "Button Tool",
                 "herschel.your.package.ButtonToolComponent",
                 "factory.editor.tool",
                 "herschel.your.package.ButtonTool"))

from herschel.ia.gui.kernel import ToolFactory
from herschel.your.package import ButtonTool
ToolFactory.register(ButtonTool())

    4. Executing the example

For executing this simple tool, just include it in a package owned by you, open the workbench in HIPE, and execute the following in the console:
x = Int1d.range(12)
y = Double2d([[1,2,3],[4,5,6]])
Then open the x and y variables with the Button Tool and click the button: its label is updated by the tool.

Triggering Events

For a full detailed section about triggering events have a look at DpHipeEventExecution

<-- Author: JorgoBakker - 21 Dec 2007 -->
 

META FILEATTACHMENT attr="h" autoattached="1" comment="Rotate Task Panel" date="1203583605" name="rotate_panel.jpg" path="rotate_panel.jpg" size="6678" user="Main.NicolaDeCandussio" version="1"
 
This site is powered by the TWiki collaboration platform Powered by Perl