com.levigo.jadice.swing.tool
Interface ToolActivationPolicy

All Known Implementing Classes:

DefaultToolActivationPolicy

public interface ToolActivationPolicy

The ToolActivationPolicy is tasked by ToolManager with the election of a Tool to be activated in a given situation. Many Tools perform their purpose only if they are the currently active Tool, i.e. if (and only if) the Tool is the one returned by ToolManager.getActiveTool(). The active Tool may either be determined by explicitly activating it (via ToolManager.activate(Class)) or automatically, based on the current state of the UI. Tool auto activation is performed by the ToolManager if the following holds:

• a ToolActivationPolicy has been set for the ToolManager
• there is currently no Tool in exclusive mode (i.e. the user is not modifying an annotation, etc.)
• a mouse pressed/released/dragged event or key pressed/released event is processed

Election and activation process

The sequence of events during auto activation is as follows:

1. The ToolManager queries all of its enabled Tools for Tool.ActivationRequests (via Tool.getActivationRequest(EditEvent).
2. The collected ActivationRequests are passed to the ToolActivationPolicy for election.
3. If the activation policy returns a non-null ActivationRequest, the corresponding Tool is automatically activated.
4. The event which triggered Tool activation is dispatched to the newly activated Tool.

Auto-activation vs. activation feedback

In order to provide the user with a hint of what will happen if he performs an action with the mouse or keyboard, Tool auto activation happens in two phases:

1. Upon mouse moved or key pressed/release events the election process is performed with the sole intent of providing activation feedback, i.e. letting the user know which Tool will be auto-activated in a given situation. However, the active Tool will not change.
2. Upon mouse pressed/dragged events the election process is performed and the elected Tool is made active.

Nested Class Summary

static class

ToolActivationPolicy.ActivationCandidate The ActivationCandidate is used to communicate possible candidates for Tool auto activation along with their Tool.ActivationRequests.

Method Summary

ToolActivationPolicy.ActivationCandidate	electActiveTool(List<ToolActivationPolicy.ActivationCandidate> candidates, EditEvent event, ToolManager manager) This method is queried by the given ToolManager instance with a list of candidate Tools to be activated (wrapped as ToolActivationPolicy.ActivationCandidates) in response to a given EditEvent.
ToolActivationPolicy.ActivationCandidate	electFeedback(List<ToolActivationPolicy.ActivationCandidate> candidates, EditEvent e, ToolManager toolManager) This method is queried by the given ToolManager instance with a list of candidate Tools to be activated (wrapped as ToolActivationPolicy.ActivationCandidates) in response to a given EditEvent.

Method Detail

electActiveTool

ToolActivationPolicy.ActivationCandidate electActiveTool(List<ToolActivationPolicy.ActivationCandidate> candidates,
                                                         EditEvent event,
                                                         ToolManager manager)

This method is queried by the given ToolManager instance with a list of candidate Tools to be activated (wrapped as ToolActivationPolicy.ActivationCandidates) in response to a given EditEvent. If the activation policy determines that one of the candidate Tools shall be auto-activated it must return the corresponding Tool.ActivationRequest. If no Tool shall be activated, it must return null.

electFeedback

ToolActivationPolicy.ActivationCandidate electFeedback(List<ToolActivationPolicy.ActivationCandidate> candidates,
                                                       EditEvent e,
                                                       ToolManager toolManager)

This method is queried by the given ToolManager instance with a list of candidate Tools to be activated (wrapped as ToolActivationPolicy.ActivationCandidates) in response to a given EditEvent. In contrast to electActiveTool(List, EditEvent, ToolManager) this method is called during the feedback phase. If the activation policy determines that one of the candidate tools may become activated upon a subsequent mouse pressed or dragged event, it must return the corresponding Tool.ActivationRequest. Otherwise it must return null.