org.graffiti.plugin.view.interactive
Class Trigger

java.lang.Object
  extended by org.graffiti.plugin.view.interactive.Trigger

public abstract class Trigger
extends Object

Base class of all triggers, which help to interpret user gestures. As the kind of generated UserGestures is closely related to the originating InteractiveView and may include data from new kinds of input devices that were unknown at the time the tool system was created, each view class provides its own hierarchy of triggers. Every trigger (besides the root trigger, which matches all user gestures) has a an associated parent trigger and matches a subset of the user gestures matched by its parent. The child-parent association is used instead of inheritance in order to avoid the Call-super antipattern. When a trigger or one of its children is used in the currently active tool and matches a user gesture, it fills its Slots with related data.

Overview of the trigger/action paradigm

To define a new kind of trigger, create a direct subclass of Trigger and override matches(InSlotMap, InSlotMap, UserGesture). If the trigger should extract information form the user gestures not covered by its ancestors, also override apply(InSlotMap, InSlotMap, OutSlotMap, UserGesture) and add new output Slots by addOutSlot(Slot) in the constructor.

The functionality of both matches and apply is implemented employing the template method pattern. The methods that the UserGesture is passed to as first parameter have the rôle of template methods and traverse the trigger hierarchy, while the primitive operation is realized by the methods that get the UserGesture as last parameter.


Diagram 1: Template method pattern in Trigger class.

Each trigger returned by the providing view class can be addressed from script code by an unique id. The id of the root trigger is the empty string. The id of a non-root trigger is the concatenation of the id of its parent, a dot and its relative id.

Example

The following example demonstrates the trigger concept with a hypothetical view supporting some triggers for the handling of usergestures regarding the mouse. Diagram 2 shows the involved trigger classes.


Diagram 2: Class diagram of the example scenario.

Diagram 3 shows the trigger hierarchy as returned by ViewFamily.getRootTrigger(). The hierarchy returned by real views will be rather a tree of triggers than a linear list, which is used here for simplicity.


Diagram 3: Object diagram of the example scenario.

Diagram 4 shows the course of actions when one tries to match a mouse click user gesture on a node against a MousePressOnNodeTrigger. Note the signature of the methods corresponding to their rôle in the template method pattern.


Diagram 4: Sequence diagram of matching a mouse click user gesture on a node against a MousePressOnNodeTrigger.

Diagram 5 shows what happens when one tries to match a key press user gesture against a MousePressOnNodeTrigger.


Diagram 5: Sequence diagram of matching a key press user gesture on a node against a MousePressOnNodeTrigger.

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

Constructor Summary
protected Trigger(String name, String description)
          Constructs a root Trigger with the specified name and description.
protected Trigger(Trigger parent, String relativeId, String name, String description)
          Constructs a Trigger.
 
Method Summary
protected  void addOutSlot(Slot<?> slot)
          Adds an output slot to this trigger.
protected  void addParameter(Slot<?> slot)
          Adds a parameter slot to this trigger.
protected  void apply(InSlotMap parameters, InSlotMap in, OutSlotMap out, UserGesture userGesture)
          Extracts information from the specified user gesture and stores it in the output slots.
 void apply(UserGesture userGesture, SlotMap parameters, SlotMap in, SlotMap out)
          Extracts information from the specified user gesture and stores it in the output slots.
 Map<String,Slot<?>> createParameters()
          Creates a new Map containing all parameter slots of this trigger and its ancestors.
 Trigger getById(String id)
          Returns the trigger with the specified id from the same trigger hierarchy as this.
 Collection<Trigger> getChildren()
          Returns all children of this trigger.
 String getDescription()
          Returns the description of this trigger as seen by the user when graphically editing the tools.
 String getId()
          Returns the id of this trigger.
 String getName()
          Returns the name of this trigger as seen by the user when graphically editing the tools.
 Map<String,Slot<?>> getOutSlots()
          Returns the output slots of this trigger.
 Trigger getParent()
          Returns the parent of this trigger.
protected abstract  boolean matches(InSlotMap parameters, InSlotMap in, UserGesture userGesture)
          Tests if this trigger matches the specified user gesture.
 boolean matches(UserGesture userGesture, SlotMap parameters, SlotMap in)
          Tests if this trigger matches the specified user gesture.
 String toString()
           This implementation returns the name of this trigger.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Trigger

protected Trigger(String name,
                  String description)
Constructs a root Trigger with the specified name and description. Its parent will be null and its relativeId will be RELATIVE_ROOT_ID.

Parameters:
name - the name of the new Trigger as seen by the user when graphically editing the tools.
description - the description of the new Trigger as seen by the user when graphically editing the tools.

Trigger

protected Trigger(Trigger parent,
                  String relativeId,
                  String name,
                  String description)
Constructs a Trigger.

Parameters:
parent - the parent of the Trigger to create.
relativeId - the relativeId of the Trigger to create.
name - the name of the new Trigger as seen by the user when graphically editing the tools.
description - the description of the new Trigger as seen by the user when graphically editing the tools.
Method Detail

getById

public final Trigger getById(String id)
Returns the trigger with the specified id from the same trigger hierarchy as this.

Parameters:
id - the id specifying the trigger to be returned.
Returns:
the trigger with the specified id from the same trigger hierarchy as this or null if no such trigger exists.
See Also:
getId()

getId

public final String getId()
Returns the id of this trigger. The id of the root trigger is the empty string. The id of a non-root trigger is the concatenation of the id of its parent, a dot and its relativeId. The id is used to address a trigger from script code.

Returns:
the id of this trigger.
See Also:
getById(String), relativeId

getName

public final String getName()
Returns the name of this trigger as seen by the user when graphically editing the tools.

Returns:
the name of this trigger as seen by the user when graphically editing the tools.

toString

public final String toString()
This implementation returns the name of this trigger.

Overrides:
toString in class Object
See Also:
getName()

getChildren

public final Collection<Trigger> getChildren()
Returns all children of this trigger. The returned collection must not be modified.

Returns:
all children of this trigger.

getParent

public Trigger getParent()
Returns the parent of this trigger.

Returns:
the parent of this trigger.

getDescription

public String getDescription()
Returns the description of this trigger as seen by the user when graphically editing the tools.

Returns:
the description of this trigger as seen by the user when graphically editing the tools.

addParameter

protected void addParameter(Slot<?> slot)
Adds a parameter slot to this trigger. Parameter slots are used to constrain the set of matched user gestures. Must only be called by constructors of classes derived from Trigger.

Parameters:
slot - the parameter slot to add.

addOutSlot

protected void addOutSlot(Slot<?> slot)
Adds an output slot to this trigger. Output slots are filled by a call to apply(UserGesture, SlotMap, SlotMap, SlotMap). Must only be called by constructors of classes derived from Trigger.

Parameters:
slot - the output slot to add.

createParameters

public Map<String,Slot<?>> createParameters()
Creates a new Map containing all parameter slots of this trigger and its ancestors. Parameter slots are used to constrain the set of matched user gestures. The slots are obtained from the returned map by their id.

Returns:
a new Map containing all parameter slots of this trigger and its ancestors.
See Also:
parameters

getOutSlots

public Map<String,Slot<?>> getOutSlots()
Returns the output slots of this trigger. They can be filled by a call to apply(UserGesture, SlotMap, SlotMap, SlotMap). The slots are obtained from the returned map by their id.

Returns:
the output slots of this trigger.
See Also:
outSlots

matches

public final boolean matches(UserGesture userGesture,
                             SlotMap parameters,
                             SlotMap in)
Tests if this trigger matches the specified user gesture. In the employed template method pattern, this method plays the rôle of the template method, which automatically asks all ancestors of this trigger first. To define the specific behavior of a derived trigger class, override matches(InSlotMap, InSlotMap, UserGesture).

Parameters:
userGesture - the user gesture to match.
parameters - the values of the parameter slots.
in - the values of the input slots.
Returns:
true if this trigger matches the specified user gesture.
See Also:
parameters

apply

public final void apply(UserGesture userGesture,
                        SlotMap parameters,
                        SlotMap in,
                        SlotMap out)
Extracts information from the specified user gesture and stores it in the output slots. In the employed template method pattern, this method plays the rôle of the template method, which automatically calls all ancestors of this trigger first. To define the specific behavior of a derived trigger class, override apply(InSlotMap, InSlotMap, OutSlotMap, UserGesture). Before calling this method, matches(UserGesture, SlotMap, SlotMap) has to be called and to return true in order to assure that this trigger actually matches the specified user gesture.

Parameters:
userGesture - the user gesture to extract information from.
parameters - the values of the parameter slots.
in - the values of the input slots.
out - the container to hold the values of the output slots.
See Also:
parameters

matches

protected abstract boolean matches(InSlotMap parameters,
                                   InSlotMap in,
                                   UserGesture userGesture)
Tests if this trigger matches the specified user gesture. In the employed template method pattern, this method plays the rôle of the primitive operation. As this method is automatically called for all ancestors of a trigger, the overridden method has only to check the additional constraints of this trigger and can safely assume that the constraints of its parent are already satisfied.

Parameters:
parameters - the values of the parameter slots.
in - the values of the input slots.
userGesture - the user gesture to match.
Returns:
true if this trigger matches the specified user gesture.
See Also:
parameters

apply

protected void apply(InSlotMap parameters,
                     InSlotMap in,
                     OutSlotMap out,
                     UserGesture userGesture)
Extracts information from the specified user gesture and stores it in the output slots. In the employed template method pattern, this method plays the rôle of the primitive operation. As this method is automatically called for all ancestors of a trigger, the overridden method has only to fill the output slots created by this trigger itself. It can safely assume that this trigger matches the specified user gesture. The default implementation does nothing.

Parameters:
parameters - the values of the parameter slots.
in - the values of the input slots.
out - the container to hold the values of the output slots.
userGesture - the user gesture to extract information from.
See Also:
parameters


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