The Interactors package
Package:
diva.canvas.interactors
Status:
0.1: Reasonably complete. Published to ptdesign. 05/05/98.
Last updated:
May 5th, 1998
See also:
The Diva canvas
Copyright
Contents
Overview
An interactor is an object that encapsulates a particular
kind of user interaction. Interactors are built on top of the
lower-level event model, and make it easy to reuse interaction
sequences and to dynamically alter user interaction.
Interactors were first proposed by Brad Myers and used in the
Garnet and Amulet toolkits. The interactors in this package handle
mouse tracking and dragging, selection, and text editing.
Constraints
A constraint is an object that constrains coordinates to
discrete values. Given a starting point, a constraint object then
accepts attempted changes on that point, and decides what the
point should be changed to.
- interface Constraint
-
The interface for all point constraints.
- void init ( Point2D )
- Initialize the constraint with a starting point.
- boolean accept ( Point2D )
- Ask the constraint to accept a new point. If the constraint
accepts the point unmodified, it should return true. Otherwise,
it should modify the point and return false.
- interface SnapConstraint extends Constraint
-
The interface for constraints that implement some kind of
semantic "snapping."
- void onSnap ( Observer )
- Set an observer that will be notified when a snap occurs.
The argument to the observer will be the feature or figure
to which the snap occurs.
- void onRelease ( Observer )
- Set an observer that will be notified when a snap
is released. The argument to the observer will be null.
- interface ConstraintFactory
-
The interface for objects that create constraints.
- Constraint create ( )
- Create and return a new constraint.
- class GridConstraint implements Constraint
- Constrain the point to lie on a grid. The nearest grid
line is chosen.
- GridConstraint ( float, float, float, float )
- Create a grid constraint. The first two arguments are
the origin of the grid, the second two the grid size.
- class RegionConstraint implements Constraint
- Constrain the point to within a rectangular region of the plane.
- RegionConstraint ( Rectangle2D )
- Create a region constraint. The point is contrained
to lie within the given rectangle.
- class LineConstraint implements Constraint
- Constrain the point to lie along a straight line.
- LineConstraint ( Line2D )
- Create a line constraint. The point is contrained
to lie on the given line.
- class SnapFeature implements SnapConstraint
- Constrain the point to one of a given set of features.
- SnapFeature ( FeatureSet, float halo )
- Create an alignment constraint on the given features. The point
is snapped to the nearest feature that is within halo pixels.
- SnapFeature ( FeaturePredicate, float halo, float limit )
- Create an alignment constraint on features that match the given
predicate. The point is snapped to the nearest feature that matches
the feature and is within halo pixels. Only figures within the
limit will be considered.
- class SnapAlign implements SnapConstraint
- Constrain the point to align with one of a given set of features.
- SnapAlign ( Feature[ ], float halo )
- Create a snap constraint on the given features. The point
is snapped in the horizontal or vertical direction by up to
halo pixels.
- SnapAlign ( FeatureSet, float halo )
- Create a snap constraint on features that match the feature
predicate. The point is snapped in the horizontal or vertical
direction by up to halo pixels.
Interactors
An interactor encapsulates a particular pattern of user interaction,
making it reusable and easy to change dynamically.
- interface Interactor extends EventListener
-
The interface for all interactor objects.
- void attach ( Object )
- Attach the interactor to something. The interactor will
create appropriate listeners for input events. The type of
the object depends on the class of interactor, and will not
be checked until runtime. Some interactors can be attached
to multiple objects; others cannot.
- void detach ( Object )
- Detach the interactor from an object. The interactor will
no longer receive events.
- class Dragger implements Interactor, DragListener
- A dragger is an interactor that responds to the "click-and-drag"
interaction sequence. Draggers need a manipulator plugged into them in
order to actually have any effect -- this can be an instance of
DragManipulator, for simple demos, or in real editors, it would be a
controller object that implements the Manipulator interface.
Draggers can be attached to Figures and FigureSets.
- Dragger ( MouseFilter )
- Construct a dragger interactor that responds to events
that are accepted by the given filter.
- void addConstraint ( Constraint )
- Add a location constraint. If more than one constraint
is added, they will be applied in series. If, after applying
all constraints, the current coordinate is the same as the
previous one, the interactor will do nothing.
- void removeConstraint ( Constraint )
- Remove a location constraint.
- void setInitializer ( Observer )
- Set an observer that will be notified when the interactor
first gets an event. This is intended for initialization of the
interactor. If, after the initializer has been notified, there
is no DragListener attached to this object, then it constructs
a DragManipulator on the clicked-on figure. This is provided
mainly for convenience for simple demos and examples.
- class Dropper extends Dragger implements MotionListener
- A dropper is an interactor that understands the notion of dragging
from one figure to another. It is like drag-and-drop, except that it
operates solely within a canvas. Droppers are very useful for doing
things like dragging lines between figures. The dropper "activates"
whenever the cursor moves over an object to which it is attached. Droppers
can be attached to Figures or EventRecasters.
- Dropper ( MouseFilter )
- Create a new dropper object, that the given predicate for
deciding whether an object that is within halo is a valid drop
source.
- void addSourceMotionListener ( MotionListener )
- Add a motion listener that is notified when a suitable source
object is entered or left.
- void addTargetMotionListener ( MotionListener )
- Add a motion listener that is notified when a suitable target
object is entered or left.
- void removeSourceMotionListener ( MotionListener )
- Remove a motion listener on the source.
- void removeTargetMotionListener ( MotionListener )
- Remove a motion listener on the target.
- void setSourceHalo ( int )
- Set the distance from a source item that activates the
dropper. The default is some small distance.
- void setSourceHighlighter ( Highlighter )
- Set the highlighter used when a source figure is entered.
The default is the default BasicHighlighter.
- void setTargetHalo ( int )
- Set the distance from a target item that activates
the dropper. The default is some small distance.
- void setTargetHighlighter ( Highlighter )
- Set the highlighter used when a target figure is entered.
The default is the default BasicHighlighter.
- class Selector implements Interactor, ItemListener, DragListener
- A selector is an interactor that manages a graphical selection. It
responds to mouse press events by adding figures to or removing them
from a Selection, and performing appropriate highlighting. It responds
to drag events by drawing a selection rectangle and, again, modifying
a Selection. It can be set up to delegate events to another
interactor -- this is used, for example, to drag selected items when
one of them is clicked-on. Selectors can be attached to the canvas or
to layers.
- Selector ( )
- Construct a selector that will select any figure within
the object to which this selector is attached.
- Selector ( FigurePredicate )
- Construct a selector that will select any figure within
the object to which this selector is attached, and that satisfies
the given predicate.
- static int ONE_NEWLY_SELECTED
- The flag that says that a single item has just been selected.
- static int ONE_STILL_SELECTED
- The flag that says that we clicked on an item that was
already selected, and it is still selected.
- static int MANY_SELECTED
- The flag that says that more than one item is selected.
- void clear ( )
- Clear the selection.
- void delegate ( Interactor, int condition )
- Delegate events from this interactor to another interactor. The
condition argument must be a combination of the flags
ONE_NEWLY_SELECTED, ONE_STILL_SELECTED, and MANY_SELECTED. Whenever a
new item is selected, or a button is pressed on an item that is
already selected, the list of interactors added with this method is
scanned. If the flags match the indicated conditions, then that
interactor is attached to the selected or clicked-on figure.
- void deselect ( Figure )
- Deselect the given figure.
- Highlighter getHighlighter ( )
- Get the highlighter used to highlight selected figures.
- Selection getSelection ( )
- Get the selection used by this selector.
- void select ( Figure )
- Select the given figure.
- void setSelectFilter ( int button, int mask,
int modifiers )
- Set the button and modifiers used to select figures. See the
constructor of Dragger for explanation of the arguments. The default
is button one, no modifiers.
- void setDeselectFilter ( MouseFilter )
- Set the filter used to deselect figures. The default
is MouseFilter.defaultSelectFilter.
- void setToggleFilter ( MouseFilter )
- Set the filter used to toggle figures into and out
of the selection.
- void setDragSelectFilter ( MouseFilter )
- Set the filter used to select figures during
drag-selection.
- void setDragDeselectFilter ( MouseFilter )
- Set the filter used to deselect figures
during drag-selection.
- void setDragToggleFilter ( Filter )
- Set the filter used to toggle figures into and out
of the selection during drag-selection.
- void setInclusiveSelect ( boolean )
- If inclusive selection is false, each start of a drag-select
clears the selection. The default is false.
- void setHighlighter ( Highlighter )
- Set the highlighter used to highlight selected figures.
- void setSelection ( Selection )
- Set the selection used by this selector. Selectors can
share selections. Care should be taken to call clear() before
calling this method, or false highlights might result.
- void toggle ( Figure )
- Toggle the given figure into or out of the selection.
Issues
- Naming
-
- We probably shouldn't use the name Constraint, as it's
likely to be wanted later on.
- Constraints with animation
-
In general, interactors need to support constraints and
animation. For example, suppose some kind of semantic snapping
constraint were implemented. When the point snaps, we want it to snap
"smoothly" -- i.e. we want animation to insert points along the
trajectory to increase realism. My current thinking is that the
animation is on the output side: the model says ok, animate to
this point, and the animation simply drives the displayed position,
and makes some callback to perform highlighting.
- Text editing
- We need an interactor that handles editing of 2D text glyphs.