org.graffiti.plugin.tool
Class ToolRegistry

java.lang.Object
  extended by org.graffiti.plugin.tool.ToolRegistry
All Implemented Interfaces:
UserGestureListener, ViewListener, SessionListener

public final class ToolRegistry
extends Object
implements SessionListener, ViewListener, UserGestureListener

Manager of all tools.

Adding Tools

New Tools can simply be constructed and then registered by calling registerTool(Tool) or registerTool(Tool, GenericPlugin). Tools that are created by ToolFactorys and are stored in the preferences tree will automatically be instantiated and registered when the respective factory is registered by registerToolFactory(ToolFactory).

Visiblity

The availability of tools, that is, whether the tool button for a tool is currently visible or not, is controlled by the default mode and tool filters.

Default mode

When the default mode is active, at most those tools are visible, whose Tool.isDefaultMode() method returns true. If the default mode is inactive, all tools are generally visible (some may still be filtered out by tool filters). To disable the default mode, add a veto against it by passing an arbitrary object to addDefaultModeVeto(Object). The veto can be withdrawn by removing that object by removeDefaultModeVeto(Object). The default mode is considered active exactly if there currently is no veto against it.

Tool filters

Tool filters decide for each tool whether it shall be visible or not. The filters are added and removed to a list by addToolFilter(ToolFilter) and removeToolFilter(ToolFilter). A tool is available exactly if all tool filters in that list vote in favor of its visibility (the default mode is actually realized by a hidden member of that list).

Use cases

The previously described mechanism is exemplified by the following use cases.

Task: Supplement the default tools.
Solution: Create and register a new tool that returns true on Tool.isDefaultMode().

Task: Hide a specific tool.
Solution: Add a tool filter that lets pass all tools except the tool to hide.

Task: Limit the visibility to the default tools.
Solution: Add a tool filter that lets pass only the default tools.

Task: Replace the default tools by a new mode of interaction.
Solution: Create and register the new tools, which return false on Tool.isDefaultMode(), so that they are hidden by default. In order to switch to the alternative mode, add a veto against the default mode, and add a tool filter that lets pass only the new tools. To switch back to normal mode, remove the veto and the tool filters.

Version:
$Revision$ $Date$
Author:
Andreas Gleißner

Method Summary
 void addCommonAction(ToolAction<InteractiveView<?>> commonAction)
          Adds the specified common action.
 void addDefaultModeVeto(Object veto)
          Adds a veto against the default mode.
 void addListener(ToolRegistryListener listener)
          Adds the specified listener interested in the changes to the list of tools.
 void addPopupMenuProvider(ToolPopupMenuProvider provider)
          Adds the specified popup menu provider.
 void addToolFilter(ToolFilter filter)
          Adds the specified tool filter.
 void addUserGestureListener(UserGestureListener listener)
          Adds the specified UserGestureListener, which will be notified when a user gesture is performed.
 void canceled(InteractiveView<?> source)
          Is called when the user canceled a sequence of user gestures.
<T extends InteractiveView<T>>
Tool<T>
createTool(ViewFamily<T> viewFamily, String factoryId)
          Creates a new tool, which supports the specified view family, using the factory with the specified id.
 void executeChanges(VoidCallback<ToolRegistry> callback)
          Calls the specified callback.
 void gesturePerformed(InteractiveView<?> source, UserGesture gesture)
          Is called when a user gesture occurs in a view.
static ToolRegistry get()
          Returns the ToolRegistry singleton.
 ToolAction<InteractiveView<?>> getCommonAction(String id)
          Returns the common action with the specified id.
 List<ToolPopupMenuProvider> getPopupMenuProviders()
          Returns a list of all popup menu providers.
 ToolToolbar getToolbar()
          Returns the tool bar.
 Collection<ToolFactory> getToolFactories()
          Returns the tool factories.
<T extends InteractiveView<T>>
SortedSet<Tool<T>>
getTools(ViewFamily<T> viewFamily)
          Returns all tools supporting the specified view family.
(package private)  boolean isVisible(Tool<?> tool)
          Returns if the specified tool should be visible according to the tool filters.
protected
<T extends InteractiveView<T>>
void
moveDown(Tool<T> tool)
          Moves the specified tool one position downwards.
protected
<T extends InteractiveView<T>>
void
moveUp(Tool<T> tool)
          Moves the specified tool one position upwards.
<T extends InteractiveView<T>>
void
registerTool(Tool<T> tool)
          Registers the specified tool.
<T extends InteractiveView<T>>
void
registerTool(Tool<T> tool, GenericPlugin plugin)
          Registers the specified tool.
 void registerToolFactory(ToolFactory toolFactory)
          Registers the specified tool factory.
<T extends InteractiveView<T>>
void
registerTools(Collection<Tool<T>> tools)
          Registers the specified tools.
 void removeDefaultModeVeto(Object veto)
          Removes the specified veto against the default mode.
 void removeListener(ToolRegistryListener listener)
          Removes one instance of the specified listener from the list.
 void removePopupMenuProvider(ToolPopupMenuProvider provider)
          Removes the specified pop
 void removeToolFilter(ToolFilter filter)
          Removes the specified tool filter.
 void removeUserGestureListener(UserGestureListener listener)
          Removes the first occurrence of the specified listener.
protected
<T extends InteractiveView<T>>
void
resetTool(Tool<T> tool)
          Resets the specified tool.
 void sessionChanged(Session s)
          This method is called when the session changes.
 void sessionDataChanged(Session s)
          This method is called when the data (except the graph data) are changed.
protected
<T extends InteractiveView<T>>
void
setActiveTool(Tool<T> tool)
          Activates the specified tool.
protected
<T extends InteractiveView<T>>
void
toolRegistered(Tool<T> tool, ToolEntry<T> entry)
          Is called when the specified tool has been registered.
 void viewChanged(View newView)
          This method is called when the view changes.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

get

public static ToolRegistry get()
Returns the ToolRegistry singleton.

Returns:
the ToolRegistry singleton.

addListener

public void addListener(ToolRegistryListener listener)
Adds the specified listener interested in the changes to the list of tools. A listener may be added multiple times. It will be notified accordingly often.

Parameters:
listener - the listener to add, which is interested in the changes to the list of tools.

removeListener

public void removeListener(ToolRegistryListener listener)
Removes one instance of the specified listener from the list.

Parameters:
listener - the listener to remove.
See Also:
addListener(ToolRegistryListener)

registerToolFactory

public void registerToolFactory(ToolFactory toolFactory)
Registers the specified tool factory. All tools that are registered in the Preferences for automatic creation by this factory are created. There must not be multiple tool factories with the same id.

Parameters:
toolFactory - the tool factory to register.

registerTool

public <T extends InteractiveView<T>> void registerTool(Tool<T> tool)
Registers the specified tool. There must not be multiple tools with the same id.

Parameters:
tool - the tool to register.

registerTool

public <T extends InteractiveView<T>> void registerTool(Tool<T> tool,
                                                        GenericPlugin plugin)
Registers the specified tool. There must not be multiple tools with the same id.

Parameters:
tool - the tool to register.

toolRegistered

protected <T extends InteractiveView<T>> void toolRegistered(Tool<T> tool,
                                                             ToolEntry<T> entry)
Is called when the specified tool has been registered. It adds its button to the tool bar and notifies the ToolRegistryListeners.

Type Parameters:
T -
Parameters:
tool -
entry -
See Also:
ToolToolbar

registerTools

public <T extends InteractiveView<T>> void registerTools(Collection<Tool<T>> tools)
Registers the specified tools. There must not be multiple tools with the same id.

Parameters:
tools - the tools to register.

setActiveTool

protected <T extends InteractiveView<T>> void setActiveTool(Tool<T> tool)
Activates the specified tool. This method may only be called from Tool. To activate a tool, call Tool.activate() instead.

Parameters:
tool - the tool that calls this method to be activated.
Throws:
IllegalStateException - if there is no active view or if the view family of the calling tool does not equal the current view family.

moveUp

protected <T extends InteractiveView<T>> void moveUp(Tool<T> tool)
Moves the specified tool one position upwards.

Type Parameters:
T -
Parameters:
tool - the tool to move one position upwards.

moveDown

protected <T extends InteractiveView<T>> void moveDown(Tool<T> tool)
Moves the specified tool one position downwards.

Type Parameters:
T -
Parameters:
tool - the tool to move one position downwards.

resetTool

protected <T extends InteractiveView<T>> void resetTool(Tool<T> tool)
Resets the specified tool.

Type Parameters:
T -
Parameters:
tool - the tool to reset.

getToolbar

public ToolToolbar getToolbar()
Returns the tool bar.

Returns:
the tool bar.

sessionChanged

public void sessionChanged(Session s)
This method is called when the session changes.

Specified by:
sessionChanged in interface SessionListener
Parameters:
s - the new Session.

sessionDataChanged

public void sessionDataChanged(Session s)
This method is called when the data (except the graph data) are changed. This implementation does nothing.

Specified by:
sessionDataChanged in interface SessionListener

viewChanged

public void viewChanged(View newView)
This method is called when the view changes. This method is not called when another session is activated. Implement SessionListener if you are interested in session changed events.

Specified by:
viewChanged in interface ViewListener
Parameters:
newView - the new View.

isVisible

boolean isVisible(Tool<?> tool)
Returns if the specified tool should be visible according to the tool filters.

Parameters:
tool - the tool whose visibility is in questions.
Returns:
if the specified tool should be visible according to the tool filters.

addToolFilter

public void addToolFilter(ToolFilter filter)
Adds the specified tool filter.

Parameters:
filter - the tool filter to add.
See Also:
removeToolFilter(ToolFilter)

removeToolFilter

public void removeToolFilter(ToolFilter filter)
Removes the specified tool filter.

Parameters:
filter - the tool filter to remove.
See Also:
addToolFilter(ToolFilter)

addDefaultModeVeto

public void addDefaultModeVeto(Object veto)
Adds a veto against the default mode.

Parameters:
veto - the veto to add against the default mode.
See Also:
removeDefaultModeVeto(Object)

removeDefaultModeVeto

public void removeDefaultModeVeto(Object veto)
Removes the specified veto against the default mode.

Parameters:
veto - the veto to remove.
See Also:
addDefaultModeVeto(Object)

executeChanges

public void executeChanges(VoidCallback<ToolRegistry> callback)
Calls the specified callback. The visibility of the tools is only be updated when the execution has finished. It is recommended to pack a sequence of calls to this registry in a callback in order to eliminate superfluous visibility updates. It is save to nest calls to executeChanges(VoidCallback).

Parameters:
callback - the callback to call.

addPopupMenuProvider

public void addPopupMenuProvider(ToolPopupMenuProvider provider)
Adds the specified popup menu provider. When the user right-clicks on a ToolButton, a popup menu is shown, which contains the actions provided by ToolPopupMenuProviders.

Parameters:
provider - the popup menu provider to add.
See Also:
removePopupMenuProvider(ToolPopupMenuProvider), getPopupMenuProviders()

removePopupMenuProvider

public void removePopupMenuProvider(ToolPopupMenuProvider provider)
Removes the specified pop

Parameters:
provider -
See Also:
addPopupMenuProvider(ToolPopupMenuProvider)

getPopupMenuProviders

public List<ToolPopupMenuProvider> getPopupMenuProviders()
Returns a list of all popup menu providers.

Returns:
a list of all popup menu providers.
See Also:
addPopupMenuProvider(ToolPopupMenuProvider)

getTools

public <T extends InteractiveView<T>> SortedSet<Tool<T>> getTools(ViewFamily<T> viewFamily)
Returns all tools supporting the specified view family.

Type Parameters:
T - Common superclass of all views belonging to the specified view family.
Parameters:
viewFamily - the view family, the supporting tools of which are to be returned.
Returns:
all tools supporting the specified view family.

getToolFactories

public Collection<ToolFactory> getToolFactories()
Returns the tool factories.

Returns:
the tool factories.
See Also:
registerToolFactory(ToolFactory)

createTool

public <T extends InteractiveView<T>> Tool<T> createTool(ViewFamily<T> viewFamily,
                                                         String factoryId)
Creates a new tool, which supports the specified view family, using the factory with the specified id.

Type Parameters:
T - Common superclass of all views belonging to the specified view family.
Parameters:
viewFamily - the view family to support by the new tool.
factoryId - the id of the factory used to create the new tool.
Returns:
a new tool, which supports the specified view family, using the factory with the specified id.

gesturePerformed

public void gesturePerformed(InteractiveView<?> source,
                             UserGesture gesture)
Is called when a user gesture occurs in a view. This implementation broadcasts the gesture to the current tool and all listeners added by addUserGestureListener(UserGestureListener).

Specified by:
gesturePerformed in interface UserGestureListener
Parameters:
source - the view the user gesture occurred in.
gesture - the user gesture that was performed.

canceled

public void canceled(InteractiveView<?> source)
Is called when the user canceled a sequence of user gestures. This implementation broadcasts the message to the current tool and all listeners added by addUserGestureListener(UserGestureListener).

Specified by:
canceled in interface UserGestureListener
Parameters:
source - the currently active view.

addUserGestureListener

public void addUserGestureListener(UserGestureListener listener)
Adds the specified UserGestureListener, which will be notified when a user gesture is performed. If a listener is added multiple times, it will be notified accordingly multiple times in response to each single user gesture.

Parameters:
listener - the listener to add.

removeUserGestureListener

public void removeUserGestureListener(UserGestureListener listener)
Removes the first occurrence of the specified listener.

Parameters:
listener - the listener to remove.

addCommonAction

public void addCommonAction(ToolAction<InteractiveView<?>> commonAction)
Adds the specified common action. Common actions are those actions that are compatible with every view family.

Parameters:
commonAction - the common action to add.

getCommonAction

public ToolAction<InteractiveView<?>> getCommonAction(String id)
Returns the common action with the specified id.

Parameters:
id - the id of the common action to return.
Returns:
the common action with the specified id or null if no such action exists.


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