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

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.