com.levigo.jadice.swing.tool
Class Tool

java.lang.Object
  com.levigo.jadice.swing.tool.Tool

All Implemented Interfaces:

MenuContributor

Direct Known Subclasses:

com.levigo.jadice.swing.internal.tool.AbstractBaseTool, CrossHairTool, DecorationTool, GalleryNavigationTool, HoverLensTool, KeyBindingsTool, KeyboardNavigationTool, LensView.LensInputEventTool, LightboxThumbnailTool, com.levigo.jadice.swing.internal.tool.ls.MarkedContentFinderTool, com.levigo.jadice.swing.internal.tool.ls.MarkedContentHighlighterTool, MouseGestureTool, MouseWheelTool, MouseWheelZoomTool, PanTool, PDFPasswordProviderTool, PopupMenuTool, TextCursorTool, ThumbnailNavigationTool, VisibleBoundsTool

public abstract class Tool
extends Object
implements MenuContributor

This abstract class must be sub-classed in order to contribute additional functionality to page-visualization components like the PageView, or the ThumbnailView. Note: this class is a successor to and supersedes the EditPane interface.

Since:

5.0

Nested Class Summary

static class

Tool.ActivationRequest This class describes an auto-activation request issued by a tool in response to an event.

Field Summary

static int	DEFAULT_PRIORITY The default priority used with respect to dispatching or rendering.
static int	MAX_PRIORITY The maximum priority a tool is supposed to use with respect to dispatching or rendering.
static int	MIN_PRIORITY The minimum priority a tool is supposed to use with respect to dispatching or rendering.

Constructor Summary

Tool()

Method Summary

void	contribute(ContributionContext context, MenuBuilder contextMenu) This method is called in order to give the menu contributor a chance to contribute context menu entries via the supplied MenuBuilder.
protected Tool.ActivationRequest	getActivationFeedback(MouseEditEvent e) Provide feedback for the user about what would happen, if the mouse were pressed at the current location.
protected Tool.ActivationRequest	getActivationRequest(EditEvent e) Return the auto-activation request for this this tool in response to the given event.
protected Tool.ActivationRequest	getActivationRequestForKeyPressed(KeyEditEvent e) Return the auto-activation request for this this tool in response to the given key press.
protected Tool.ActivationRequest	getActivationRequestForMouseDragged(MouseEditEvent e) Return the auto-activation request for this this tool in response to the given mouse drag event.
protected Tool.ActivationRequest	getActivationRequestForMousePressed(MouseEditEvent e) Return the auto-activation request for this this tool in response to the given mouse press.
protected Cursor	getCursor() Return the current cursor in use on the associated view component.
protected int	getDispatchPriority() Return the dispatch priority for this tool.
protected ToolManager	getManager() Return the current tool manager.
protected int	getRenderPriority() Return the render priority for this tool.
protected void	handleEditEvent(boolean isActive, EditEvent e) Handle the given EditEvent.
protected void	handleKeyPressed(KeyEditEvent e, boolean isActive) Invoked when a key has been pressed.
protected void	handleKeyReleased(KeyEditEvent e, boolean isActive) Invoked when a key has been released.
protected void	handleKeyTyped(KeyEditEvent e, boolean isActive) Invoked when a key has been typed.
protected void	handleMouseClicked(MouseEditEvent e, boolean isActive) Invoked when the mouse button has been clicked (pressed and released) on a component.
protected void	handleMouseDragged(MouseEditEvent e, boolean isActive) Invoked when a mouse button is pressed on a component and then dragged.
protected void	handleMouseEntered(MouseEditEvent e, boolean isActive) Invoked when the mouse cursor enters the unobscured part of component's geometry.
protected void	handleMouseExited(MouseEditEvent e, boolean isActive) Invoked when the mouse cursor exits the unobscured part of component's geometry.
protected void	handleMouseMoved(MouseEditEvent e, boolean isActive) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
protected void	handleMousePressed(MouseEditEvent e, boolean isActive) Invoked when a mouse button has been pressed on a component.
protected void	handleMouseReleased(MouseEditEvent e, boolean isActive) Invoked when a mouse button has been released on a component.
protected void	handleMouseWheelMoved(MouseWheelEditEvent e, boolean isActive) Invoked when the mouse wheel is rotated.
protected void	propagatePropertyChange(String name, Object oldValue, Object newValue)
protected void	render(RenderParameters parameters, boolean isActive) Renders the Tool's UI onto the given Graphics2D context using the given RenderControls.
protected void	setActive(boolean active) Receive notification from the tool manager about the tool's active state.
protected void	setCursor(Cursor cursor) Set the cursor on the associated view component.
protected void	setEnabled(boolean enabled) Receive notification from the tool manager about the tool's enabled state.
protected void	setManager(ToolManager manager) Receives the ToolManager instance, which the Tool implementation has been registered for.
protected void	setStatusFeedback(String feedback) Set the status feedback message published by the tool manager using ToolManager.getStatusFeedback().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIN_PRIORITY

public static final int MIN_PRIORITY

The minimum priority a tool is supposed to use with respect to dispatching or rendering.

See Also:

getRenderPriority(), getDispatchPriority(), Constant Field Values

MAX_PRIORITY

public static final int MAX_PRIORITY

The maximum priority a tool is supposed to use with respect to dispatching or rendering.

See Also:

getRenderPriority(), getDispatchPriority(), Constant Field Values

DEFAULT_PRIORITY

public static final int DEFAULT_PRIORITY

The default priority used with respect to dispatching or rendering.

See Also:

getRenderPriority(), getDispatchPriority(), Constant Field Values

Constructor Detail

Tool

@CallOnEDT
public Tool()

Method Detail

render

@CallOnEDT
protected void render(RenderParameters parameters,
                                boolean isActive)

Renders the Tool's UI onto the given Graphics2D context using the given RenderControls.

This render method is called within the context and during the rendering of a single page. The page being rendered is passed to implementors of this method in order to be able to control and influence the page rendering.

Parameters:

parameters - the view component which is currently being rendered

isActive - whether the called tool is currently active

handleEditEvent

@CallOnEDT
protected void handleEditEvent(boolean isActive,
                                         EditEvent e)

Handle the given EditEvent. This method dispatches the edit event to the individual handleXYZ()-Methods. However, implementors may want and are allowed to override this method in order to perform standard handling tasks common to all types of events.

Parameters:

isActive - whether this tool is currently active

e - the event

handleMouseClicked

@CallOnEDT
protected void handleMouseClicked(MouseEditEvent e,
                                            boolean isActive)

Invoked when the mouse button has been clicked (pressed and released) on a component.

Parameters:

isActive - whether this tool is currently active

handleMousePressed

@CallOnEDT
protected void handleMousePressed(MouseEditEvent e,
                                            boolean isActive)

Invoked when a mouse button has been pressed on a component.

Parameters:

isActive - whether this tool is currently active

handleMouseReleased

@CallOnEDT
protected void handleMouseReleased(MouseEditEvent e,
                                             boolean isActive)

Invoked when a mouse button has been released on a component.

Parameters:

isActive - whether this tool is currently active

handleMouseDragged

@CallOnEDT
protected void handleMouseDragged(MouseEditEvent e,
                                            boolean isActive)

Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Parameters:

isActive - whether this tool is currently active

handleMouseMoved

@CallOnEDT
protected void handleMouseMoved(MouseEditEvent e,
                                          boolean isActive)

Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Parameters:

isActive - whether this tool is currently active

handleMouseEntered

@CallOnEDT
protected void handleMouseEntered(MouseEditEvent e,
                                            boolean isActive)

Invoked when the mouse cursor enters the unobscured part of component's geometry.

Parameters:

isActive - whether this tool is currently active

handleMouseExited

@CallOnEDT
protected void handleMouseExited(MouseEditEvent e,
                                           boolean isActive)

Invoked when the mouse cursor exits the unobscured part of component's geometry.

Parameters:

isActive - whether this tool is currently active

handleMouseWheelMoved

@CallOnEDT
protected void handleMouseWheelMoved(MouseWheelEditEvent e,
                                               boolean isActive)

Invoked when the mouse wheel is rotated.

Parameters:

isActive - whether this tool is currently active

See Also:

MouseWheelEvent

handleKeyTyped

@CallOnEDT
protected void handleKeyTyped(KeyEditEvent e,
                                        boolean isActive)

Invoked when a key has been typed. See the class description for KeyEvent for a definition of a key typed event.

Parameters:

isActive - whether this tool is currently active

handleKeyPressed

@CallOnEDT
protected void handleKeyPressed(KeyEditEvent e,
                                          boolean isActive)

Invoked when a key has been pressed. See the class description for KeyEvent for a definition of a key pressed event.

Parameters:

isActive - whether this tool is currently active

handleKeyReleased

@CallOnEDT
protected void handleKeyReleased(KeyEditEvent e,
                                           boolean isActive)

Invoked when a key has been released. See the class description for KeyEvent for a definition of a key released event.

Parameters:

isActive - whether this tool is currently active

getActivationRequest

@CallOnEDT
protected Tool.ActivationRequest getActivationRequest(EditEvent e)

Return the auto-activation request for this this tool in response to the given event. This method is only called for events of the following type:

• MouseEvent.MOUSE_PRESSED
• MouseEvent.MOUSE_DRAGGED
• KeyEvent.KEY_PRESSED

If the tool returns an Tool.ActivationRequest, it becomes eligible for auto-activation. However, the final decision about which tool will actually be activated is up to the ToolActivationPolicy used be the tool manager.

Parameters:

e - the event

Returns:

an Tool.ActivationRequest or null if the tool does not seek to be auto-activated at this time.

getActivationRequestForMousePressed

@CallOnEDT
protected Tool.ActivationRequest getActivationRequestForMousePressed(MouseEditEvent e)

Return the auto-activation request for this this tool in response to the given mouse press. If the tool returns an Tool.ActivationRequest, it becomes eligible for auto-activation. However, the final decision about which tool will actually be activated is up to the ToolActivationPolicy used be the tool manager.

Parameters:

e - the KeyEditEvent

Returns:

an Tool.ActivationRequest or null if the tool does not seek to be auto-activated at this time.

getActivationRequestForMouseDragged

@CallOnEDT
protected Tool.ActivationRequest getActivationRequestForMouseDragged(MouseEditEvent e)

Return the auto-activation request for this this tool in response to the given mouse drag event. If the tool returns an Tool.ActivationRequest, it becomes eligible for auto-activation. However, the final decision about which tool will actually be activated is up to the ToolActivationPolicy used be the tool manager. Caveat: some tools may only be able to decide about their activation once the mouse starts dragging. However, this means that they may take the back seat with respect to tools requesting their auto-activation during the mouse-press already.

Parameters:

e - the KeyEditEvent

Returns:

an Tool.ActivationRequest or null if the tool does not seek to be auto-activated at this time.

getActivationRequestForKeyPressed

@CallOnEDT
protected Tool.ActivationRequest getActivationRequestForKeyPressed(KeyEditEvent e)

Return the auto-activation request for this this tool in response to the given key press. If the tool returns an Tool.ActivationRequest, it becomes eligible for auto-activation. However, the final decision about which tool will actually be activated is up to the ToolActivationPolicy used be the tool manager.

Parameters:

e - the KeyEditEvent

Returns:

an Tool.ActivationRequest or null if the tool does not seek to be auto-activated at this time.

getActivationFeedback

@CallOnEDT
protected Tool.ActivationRequest getActivationFeedback(MouseEditEvent e)

Provide feedback for the user about what would happen, if the mouse were pressed at the current location. This method is called while handling MouseEvent.MOUSE_MOVED events. If this method returns null no feedback is provided at all. The activation request returned from this method is the same object that is used during getActivationRequestForKeyPressed(KeyEditEvent) to signal the auto-activation candidacy. This method should only return an activation request if it will actually candidate for auto-activation later on using getActivationRequestForMousePressed(MouseEditEvent) or getActivationRequestForMouseDragged(MouseEditEvent).

getRenderPriority

@CallOnEDT
protected int getRenderPriority()

Return the render priority for this tool. Tools with higher dispatch priorities are rendered earlier than tools with lower priorities. The priority should be in the range MIN_PRIORITY...MAX_PRIORITY. The default priority is equal to DEFAULT_PRIORITY.

Returns:

the dispatch priority

getDispatchPriority

@CallOnEDT
protected int getDispatchPriority()

Return the dispatch priority for this tool. Tools with higher dispatch priorities receive events earlier than tools with lower priorities. The priority should be in the range MIN_PRIORITY...MAX_PRIORITY. The default priority is equal to MAX_PRIORITY minus the render priority.

Returns:

the dispatch priority

setManager

@CallOnEDT
protected void setManager(ToolManager manager)

Receives the ToolManager instance, which the Tool implementation has been registered for. If the Tool is deregistered this method will be called with null.

Parameters:

manager -

propagatePropertyChange

@CallOnEDT
protected void propagatePropertyChange(String name,
                                                 Object oldValue,
                                                 Object newValue)

setEnabled

@CallOnEDT
protected void setEnabled(boolean enabled)

Receive notification from the tool manager about the tool's enabled state. In general, tools need not and should not try to implement different behaviour depending on the enabled state, as this is already covered by the ToolManager calling the handleEditEvent(boolean, EditEvent) and render(RenderParameters, boolean) in the appropriate state only. However, some tools may need to perform extended actions (for example, for resource management purposes) upon a change of the enabled state.

Parameters:

enabled -

setActive

@CallOnEDT
protected void setActive(boolean active)

Receive notification from the tool manager about the tool's active state.

Parameters:

active -

contribute

@CallOnEDT
public void contribute(ContributionContext context,
                                 MenuBuilder contextMenu)

Description copied from interface: MenuContributor

This method is called in order to give the menu contributor a chance to contribute context menu entries via the supplied MenuBuilder.

Specified by:

contribute in interface MenuContributor

Parameters:

context - the ContributionContext which provides contribution context informations

contextMenu - the MenuBuilder to which the tool may contribute entries.

setCursor

@CallOnEDT
protected void setCursor(Cursor cursor)

Set the cursor on the associated view component. Tools should not generally try to change the cursor unless they are currently the exclusive tool. Cursor-feedback while not being the exclusive tool should be provided using getActivationFeedback(MouseEditEvent).

Parameters:

cursor - the Cursor to be set

getCursor

@CallOnEDT
protected Cursor getCursor()

Return the current cursor in use on the associated view component.

Returns:

the Cursor

setStatusFeedback

@CallOnEDT
protected void setStatusFeedback(String feedback)

Set the status feedback message published by the tool manager using ToolManager.getStatusFeedback(). Tools should not generally try to change the status message unless they are currently the exclusive tool. Status-feedback while not being the exclusive tool should be provided using getActivationFeedback(MouseEditEvent).

Parameters:

feedback - the feedback message to set

getManager

@CallOnEDT
protected ToolManager getManager()

Return the current tool manager.

Returns:

the ToolManager or null if this tool is not currently associated with a tool manager.