org.graffiti.plugin.tool
Class Tool<T extends InteractiveView<T>>

java.lang.Object
  extended by org.graffiti.plugin.tool.Tool<T>
Type Parameters:
T - The superclass of all views belonging to the view family supported by this tool.
All Implemented Interfaces:
Comparable<Tool<?>>
Direct Known Subclasses:
ToolDummy

public class Tool<T extends InteractiveView<T>>
extends Object
implements Comparable<Tool<?>>

Tools define a mode of interaction by relating triggers to actions. To provide a specific behavior for the user, create a subclass of Tool and register an instance of it at the ToolRegistry, which automatically creates and assigns a ToolButton. Each tool must be identifiable by an unique id matchable by ID_PATTERN. The set of currently available tools, that is, the set of visible tool buttons, is controlled by ToolFilters. Each tool supports exactly one ViewFamily.

Version:
$Revision: 5768 $ $Date: 2009-01-14 21:12:38 +0100 (Mi, 14 Jan 2009) $
Author:
Andreas Gleißner
See Also:
Trigger, ToolAction

Field Summary
protected  String id
          The id of this tool.
static Pattern ID_PATTERN
          The pattern of admissible ids.
(package private)  boolean isDefaultMode
          Denotes if this tool should be visible by default.
(package private)  boolean isReadOnly
          Denotes if this tool is editable by the user.
(package private)  Tool<T> nextActiveTool
          The tool that was activated when this tool was deactivated the last time.
protected  ToolPreferences preferences
          The preferences of this tool.
(package private)  Tool<T> prevActiveTool
          The tool that was deactivated when this tool was activated the last time.
(package private)  ToolButton toolButton
          The tool button representing this tool.
protected  ViewFamily<T> viewFamily
          The view family supported by this tool.
 
Constructor Summary
protected Tool(ViewFamily<T> viewFamily, String id)
          Constructs a Tool with the specified id and for the specified view family.
 
Method Summary
 void activate()
          Activates this tool.
protected  void activated()
          Is called when this tool is activated.
 int compareTo(Tool<?> other)
           This implementation compares the tools by their position.
protected  void deactivated()
          Is called when this tool is deactivated.
 void delete()
          Marks this tool for deletion.
protected  void gesturePerformed(ToolEnvironment<T> env)
          Is called when an UserGesture is performed by the user if this tool is active.
 String getDescription()
          Returns the description of this tool as seen by the user.
 ImageIcon getIcon()
          Returns the icon.
 String getIconPath()
          Returns the file path of the icon of this tool.
 String getId()
          Returns the unique id of this tool.
 String getName()
          Returns the name of this tool as seen by the user.
 int getPosition()
          Returns the position of the related tool button in the tool bar.
 String getProvidingPlugin()
          Returns a string representing the plugin providing this tool.
 ToolButton getToolButton()
          Returns the related tool button.
 ViewFamily<T> getViewFamily()
          Returns the view family supported by this tool.
(package private) static Preferences getViewFamilyPreferences(ViewFamily<?> viewFamily)
          Returns the preferences root node for the tools supporting the specified view family.
 boolean isActive()
          Returns if this tool is currently active.
protected  boolean isDefaultMode()
          Returns if this tool should be visible by default.
 boolean isDeleted()
          Returns if this tool is marked for deletion.
 boolean isDummy()
          Returns if this tool is a tool dummy.
(package private)  boolean isDummy(int i)
          Returns if this tool is a tool dummy.
 boolean isHidden()
          Returns if this tool is hidden.
 boolean isReadOnly()
          Returns if this tool may be modified by the user.
 void moveDown()
          Moves the related tool button one position down in the tool bar.
 void moveUp()
          Moves the related tool button one position up in the tool bar.
 void reset()
          Resets this tool.
protected  void reseted(ToolEnvironment<T> env)
          Is called when this tool is reseted.
(package private)  void setActive(boolean active)
          Sets if this tool is currently active.
 void setDescription(String description)
          Sets the description of this tool as seen by the user.
 void setHidden(boolean isHidden)
          Sets if this tool shall be hidden.
 void setIcon(ImageIcon icon)
          Sets the icon for the related tool button.
 void setIconPath(String iconPath)
          Sets the file path of the icon for the related tool button and loads the icon.
 void setName(String name)
          Sets the name of this tool as seen by the user.
(package private)  void setPosition(int position)
          Sets the position of the related tool button in the tool bar.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID_PATTERN

public static final Pattern ID_PATTERN
The pattern of admissible ids.


preferences

protected final ToolPreferences preferences
The preferences of this tool.


viewFamily

protected final ViewFamily<T extends InteractiveView<T>> viewFamily
The view family supported by this tool.


id

protected final String id
The id of this tool. Different instances of Tool must have different ids.


isDefaultMode

boolean isDefaultMode
Denotes if this tool should be visible by default.


isReadOnly

boolean isReadOnly
Denotes if this tool is editable by the user.


toolButton

ToolButton toolButton
The tool button representing this tool.


nextActiveTool

Tool<T extends InteractiveView<T>> nextActiveTool
The tool that was activated when this tool was deactivated the last time. May be null.


prevActiveTool

Tool<T extends InteractiveView<T>> prevActiveTool
The tool that was deactivated when this tool was activated the last time. May be null.

Constructor Detail

Tool

protected Tool(ViewFamily<T> viewFamily,
               String id)
Constructs a Tool with the specified id and for the specified view family.

Parameters:
viewFamily - the view family supported by the new tool.
id - the id of the new tool.
Method Detail

getViewFamilyPreferences

static Preferences getViewFamilyPreferences(ViewFamily<?> viewFamily)
Returns the preferences root node for the tools supporting the specified view family.

Parameters:
viewFamily - the view family supported by the tools, whose preferences root node is to be returned.
Returns:
the preferences root node for the tools supporting the specified view family.

setActive

final void setActive(boolean active)
Sets if this tool is currently active. To activate this tool, rather call activate(). At each point of time, at most one tool is active. The active tool receives the UserGestures generated by the active view.

Parameters:
active - denotes if this tool is to be set to active or inactive.

isActive

public final boolean isActive()
Returns if this tool is currently active. At each point of time, at most one tool is active. The active tool receives the UserGestures generated by the active view.

Returns:
if this tool is currently active.

activated

protected void activated()
Is called when this tool is activated. Overwrite this method to define the specific tool behavior.


deactivated

protected void deactivated()
Is called when this tool is deactivated. Overwrite this method to define the specific tool behavior.


reseted

protected void reseted(ToolEnvironment<T> env)
Is called when this tool is reseted. Overwrite this method to define the specific tool behavior. A tool is reseted after it has been activated, when it is active and the currently active view changes or in response to a call to reset().

Parameters:
env - the tool environment.

reset

public final void reset()
Resets this tool.


activate

public final void activate()
Activates this tool.

Throws:
IllegalStateException - if there is no active view or if the view family of this tool does not equal the currently active view family.

moveUp

public final void moveUp()
Moves the related tool button one position up in the tool bar.


moveDown

public final void moveDown()
Moves the related tool button one position down in the tool bar.


getViewFamily

public final ViewFamily<T> getViewFamily()
Returns the view family supported by this tool.

Returns:
the view family supported by this tool.

gesturePerformed

protected void gesturePerformed(ToolEnvironment<T> env)
Is called when an UserGesture is performed by the user if this tool is active. The performed gesture can be obtained from the specified environment. Overwrite this method to define the specific tool behavior.

Parameters:
env - the tool environment.

setPosition

final void setPosition(int position)
Sets the position of the related tool button in the tool bar. To change the position, rather call moveDown() or moveUp().

Parameters:
position - the new position.

getPosition

public int getPosition()
Returns the position of the related tool button in the tool bar.

Returns:
the position of the related tool button in the tool bar.

getName

public final String getName()
Returns the name of this tool as seen by the user.

Returns:
the name of this tool as seen by the user.

setName

public final void setName(String name)
Sets the name of this tool as seen by the user.

Parameters:
name - the name to set.

getDescription

public final String getDescription()
Returns the description of this tool as seen by the user.

Returns:
the description of this tool.

setDescription

public final void setDescription(String description)
Sets the description of this tool as seen by the user.

Parameters:
description - the description to set.

getId

public final String getId()
Returns the unique id of this tool.

Returns:
the unique id of this tool.

compareTo

public final int compareTo(Tool<?> other)
This implementation compares the tools by their position. If different tools share the same position, they are compared by their id.

Specified by:
compareTo in interface Comparable<Tool<?>>

getIcon

public final ImageIcon getIcon()
Returns the icon.

Returns:
the icon.

getIconPath

public final String getIconPath()
Returns the file path of the icon of this tool.

Returns:
the file path of the icon of this tool. May return null if the icon was set by setIcon(ImageIcon).

setIcon

public final void setIcon(ImageIcon icon)
Sets the icon for the related tool button. It may alternatively specified by setting the path to an image file by setIconPath(String).

Parameters:
icon - the icon to set.

setIconPath

public final void setIconPath(String iconPath)
Sets the file path of the icon for the related tool button and loads the icon. The icon may alternatively set by setIcon(ImageIcon).

Parameters:
iconPath - the path to the image file containing the icon to set.

getToolButton

public final ToolButton getToolButton()
Returns the related tool button.

Returns:
the related tool button, which is used to activate this tool by the user.

isHidden

public final boolean isHidden()
Returns if this tool is hidden. Note that isHidden directly only controls the behavior of HiddenToolFilter. Even if isHidden is false, the tool may still be actually invisible because of other reasons. To get the effective visibility, check the visibility of the related tool button.

Returns:
if this tool is hidden.
See Also:
getToolButton()

setHidden

public final void setHidden(boolean isHidden)
Sets if this tool shall be hidden.

Parameters:
isHidden - denotes if this tool shall be hidden.
See Also:
isHidden()

isDefaultMode

protected boolean isDefaultMode()
Returns if this tool should be visible by default.

Returns:
if this tool should be visible by default.
See Also:
DefaultModeFilter

isReadOnly

public final boolean isReadOnly()
Returns if this tool may be modified by the user.

Returns:
if this tool may be modified by the user.

isDeleted

public final boolean isDeleted()
Returns if this tool is marked for deletion.

Returns:
if this tool is marked for deletion.
See Also:
delete()

delete

public final void delete()
Marks this tool for deletion. The tool becomes inactive and invisible and is removed from the preferences tree. It ceases to exist on the next start of the program if it is not added again by a plugin.


isDummy

public final boolean isDummy()
Returns if this tool is a tool dummy. Tool dummies represent tools that are present in the preferences tree but have not yet been added by their providing plugins so they are currently unavailable. When the respective tool is added, this dummy will be removed.

Returns:
if this tool is a tool dummy.
See Also:
ToolDummy

isDummy

boolean isDummy(int i)
Returns if this tool is a tool dummy. Tool dummies represent tools that are present in the preferences tree but have not yet been added by their providing plugins so they are currently unavailable. When the respective tool is added, this dummy will be removed.

Returns:
if this tool is a tool dummy.
See Also:
ToolDummy

getProvidingPlugin

public final String getProvidingPlugin()
Returns a string representing the plugin providing this tool.

Returns:
a string representing the plugin providing this tool. May be null.


Generated at 2012-05-30 11:00:36 PM CEST