de.jreality.scene.tool
Interface Tool

All Known Implementing Classes:
AbstractTool, ActionTool, AirplaneTool, AnimatedRotateTool, AnimatorTool, AxisTranslationTool, BeanShellTool, ClickWheelCameraZoomTool, CoordinateSystemBeautifier, DampedDraggingTool, DragEventTool, DraggingTool, DuplicateTriplyPeriodicTool, EncompassTool, FlyTool, FlyToPickTool, HeadTransformationTool, LookAtTool, PickShowTool, PointerDisplayTool, RotateTool, ScaleTool, SelectionTool, ShipNavigationTool, ShipRotateTool, ShipScaleTool, ShowPropertiesTool, SliceBoxFactory.SimpleDragTool, TranslateTool

public interface Tool

Tools are attatched to a SceneGraphComponent and are intended to to perform interactive changes to the scene - usually driven by user input. The corresponding methods are activate(ToolContext), perform(ToolContext) and deactivate(ToolContext).

User input is passed to the Tool either as an AxisState, which represents a double value (i.e. a mouse button position) or a DoubleArray of length 16, which represents a 4 by 4 matrix. This matrix typically represents a euclidean isometry that represents the original user input converted into a suitable coordinate system. (Tool writers for non-euclidean settings need to be careful to convert these matrices if necessary.)

These inputs are called virtual devices, since they are usually hardware independent and "live in the scene". These virtual devices are mapped to InputSlots, which should represent them under a meaningful name. Some examples (which are available in the default configuration file toolconfig.xml):

Tools may be always active or activated by some virtual device. A Tool which is not always active (getActivationSlot() returns not null) will be activated as soon as one of its activation slots reaches the state AxisState.PRESSED. Warning: If the activation slot does not represent an AxisState, the tool will never become active.

A single Tool instance can be attached to different scene graph components. A tool attached to a scene graph component that appears at multiple positions in the scene graph will also, implicitly, be instanced multiple times; each instance will have its own local state not shared with other instances. [steffen: is this right?] The current path is always available via the ToolContext: de.jreality.scene.tool.ToolContext.getRootToLocal() and de.jreality.scene.tool.ToolContext.getRootToToolComponent() return the paths for the current activate(ToolContext)/perform(ToolContext)/ deactivate(ToolContext) call.

Author:
Steffen Weissmann

Method Summary
 void activate(ToolContext tc)
          This method is called when the tool gets activated.
 void deactivate(ToolContext tc)
          this method is called when the tool was activate and the AxisState of the activation slot changes to AxisState.RELEASED - to zero.
 List<InputSlot> getActivationSlots()
          If the result is empty, then the tool is always active.
 List<InputSlot> getCurrentSlots()
          This method will only be called for active tools.
 String getDescription()
          Gives an overall description of this Tool.
 String getDescription(InputSlot slot)
          Gives a description of the meaning of the given InputSlot.
 void perform(ToolContext tc)
          This method is called when the tool is activated and any AxisState or TransformationMatrix of the current slots changes.
 

Method Detail

getActivationSlots

List<InputSlot> getActivationSlots()
If the result is empty, then the tool is always active. If the result is not empty, then the tool becomes active as soon as the axis of one activation slot is pressed. This implies that the InputSlots must be associated to AxisStates, otherwise the Tool will never become active.
The tool gets deactivated, as soon as the InputSlot that caused activation changes its state to AxisState.RELEASED.
When the tool is active, other activation axes are ignored and passed to other Tools down the path. The result must remain constant.

Returns:
List of InputSlots for activating the tool

getCurrentSlots

List<InputSlot> getCurrentSlots()
This method will only be called for active tools. The currentSlots may change after each call of activate(..) or perform(..).

Returns:
list of currently relevant input slots

activate

void activate(ToolContext tc)
This method is called when the tool gets activated. Note that it will never be called if the tool is always active.

Parameters:
tc - The current tool context

perform

void perform(ToolContext tc)
This method is called when the tool is activated and any AxisState or TransformationMatrix of the current slots changes.

Parameters:
tc - The current tool context

deactivate

void deactivate(ToolContext tc)
this method is called when the tool was activate and the AxisState of the activation slot changes to AxisState.RELEASED - to zero. Note that it will never be called for always active tools.

Parameters:
tc - The current tool context

getDescription

String getDescription(InputSlot slot)
Gives a description of the meaning of the given InputSlot. This may depend on the current state of the Tool.

Parameters:
slot - to describe
Returns:
A description of the current meaning of the given InputSlot.

getDescription

String getDescription()
Gives an overall description of this Tool.

Returns:
A description of the Tool including information about activation and overall behaviour.