Tools must extend the net.refractions.udig.project.ui.tool extension point. The reference section provides a list of the extension points and technical documentation for the extension points.

All Tools are provided with a ToolContext object by the framework. The tools can use the context to access the model and to create and send commands which modify the model. Contexts have a large number of methods to simplify the job of tool authors. Please let us know of methods that would be useful or should be part of the context objects.

IMPORTANT: It is critical that the tools do not make a new reference to the context object because it is set each time the editor is activated and may change without notification.

There are three classes of tools:

  1. Action Tool - A single fire tool that has a run command that is executed when the tool is activated. An action tool does not change the mouse cursor because it is not modal. If a tool is needed that fires when clicked within the editor, a modal tool would be a better choice.
    Active Tool Example
  2. Modal Tool - A tool that has on and off modes. Within UDIG there can only be one active modal tool. A modal tool does not have a run method, instead is expected to listen for mouse. The event methods that are currently available are provided in the AbstractTool class with empty implementations. When active, the cursor defined in extension definition is used as the mouse cursor.
    Modal Tool Example
  3. Background Tool - A tool that is always active in the background. A typical background tool would be limited to providing user feedback.
    Background Tool Example
    Tools are always placed in the Toolbar and in the menu. The ToolManager is responsible for managing tools. To add tool buttons to custom views. the ToolManager.createToolAction(ToolID, CategoryID) will create an action that can be added to the view.

Examples that are part of uDig:

  • Active Tools
    • Zoom to Extent: A tools that makes the map editor adjust its zoom so that the entire map is framed in the editor.
  • Modal Tools
    • Zoom: A tool that allows the zoom towards a location in the map so that the features appear larger.
    • Pan: A tool that allows the user to adjust which part of the map they are viewing; the zoom stays the same.
  • Background Tools
    • Cursor position: Shows the current position of the mouse cursor transformed into world coordinates.
    • Quick Zoom (Wheel Zoom): Zooms in and out of the map when the mouse wheel is turned or when

Tools are grouped in Categories:

  • Category - A collection of tools that are always available but are logically similar and are as a result grouped together. Each category can have a key assigned to it which has two functions:
    • Active the current tool in the category, if not already active.
    • If the category is active then the next tool in the category will become active.

Tool extenders can also register a list of commands with the framework via the extension point definition. If this is done the Tool extender must also create a IHandler object, which is part of the eclipse command framework. An instance of the handler will be created for each command and each time a command occurs it will be passed to the handler to be handled.

Tool Interfaces and Abstract Classes

Future API Considerations

Currently all tools are active but in the future would be desirable to have a tool configuration extension point where udig extenders can define which tools are activated for their application. A system like the eclipse command framework for Eclipse 3.1 is likely.


ToolsUML.png (image/png)
tools.png (image/png)
[view] [edit]
(c) Copyright (c) 2004,2005 Refractions Research Inc. and others.