<--
   Some short-cuts 

 Set REGISTRY   = Extension Registry
 
 Set TOOL         = Tool
 
 Set CATEGORY = Category
 
-->

TaskTool

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

• how you can create a Tool and register it for being available for dedicated data

• the default task dialog and how you implement and contribute a dedicated input dialog for your task,

Adding a Task as a Tool

Task Registry

Prime input validation

Task Dialogs

Default Task Dialog

Parameter Modifiers

Implement a Modifier

Register a Modifier

Signature Components

Implement a Task Signature Component

Register a Task Signature Component

Custom Task Dialogs

Implement a Task Panel

Register a Task Panel

Task compliance

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

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();
}

ToolParameter

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

EditorComponent

AbstractEditorComponent

Tool Registry

# 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

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 ...
}

Simple sample

    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

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