Canvas events
Package:
diva.canvas.event
Status:
Unpublished. Preliminary.
Imported packages and classes:
java.util.EventObject
java.awt.event.InputEvent
java.awt.event.MouseEvent
java.awt.event.EventListener
java.awt.event.ComponentListener
See also:
The Diva canvas
Copyright
Contents
Layer events
The event model of figures is en extension to the AWT event
model. A new event type, LayerEvent, is used to represent mouse events
in layers, including events on figures. (LayerEvent is a subclass of
the AWT InputEvent. We needed a new event type to handle
floating-point coordinates for layers and to contain the reference to
the moused-on layer or figure.)
Two new listener types are created for listening for layer
events. One listens for mouse enter, motion, and leave events, and one
listens for mouse press, drag, and release events. Event listeners
cannot be attached directly to figures, but instead to an
EventDispatcher object, which handle dispatch of events detected for
figures. This extra indirection keeps figures lightweight and actually
improves performance. It also enables creation of "classes" of
figures, all of which respond to events in exactly the same way (which
is often what you need in a graphical editor.) Event listeners can,
however, be attached directly to layers.
Events occuring on a figure are given to the front-most figure.
If a figure has no attached event dispatcher, the event percolates up
the tree of figures until it can be dispatched.
- interface LayerEventSource
-
This interface is used to tag classes that can be a "source"
for layer events. This is intended to be implemented by CanvasLayer
and Figure.
- class LayerEvent extends InputEvent
-
The class representing mouse events in layers. This class is
similar to its sibling class MouseEvent, except that it represents
coordinates in the layer's logical coordinate system. Each LayerEvent
keeps a reference to the mouse event that originated the event,
and which can be accessed through the getMouseEvent() method.
- LayerEvent ( MouseEvent e, CanvasLayer l )
- Create a new layer event fropm the given mouse event, and set the
layer event source to the passed canvas layer. The
floating-point coordinates returned are derived from the coordinates
of the mouse event by using the current transform of the layer.
- LayerEvent ( MouseEvent e, CanvasLayer l, Figure f)
- Create a new layer event fropm the given mouse event, and set the
layer event source to the passed figure. The floating-point
coordinates returned are derived from the coordinates of the mouse
event by using the current transform of the passed canvas layer.
- void consume ( )
- Consume this event. This event is marked consumed,
and so is the mouse event that originated it.
- LayerEventSource getLayerSource ( )
- Get the layer or figure that the event occurred on.
- MouseEvent getMouseEvent ( )
- Get the mouse event that originated this layer event.
- boolean isConsumed ( )
- Test if this event has been consumed. This will return true if
this event has been consumed or the original mouse event has been
consumed.
- Point2D getPoint ( )
- Get the point where the event occured. The point is in layer
coordinates, and should be assumed to be a floating-point coordinate.
- double getX ( )
- Get the horizontal component of the point where the event
occured. The value is in layer coordinates, and should be assumed to
be a floating-point coordinate.
- double getY ( )
- Get the vertical component of the point where the event
occured. The value is in layer coordinates, and should be assumed to
be a floating-point coordinate.
- protected void setLayerSource ( LayerEventSource )
- Set the layer or figure that the event occurred on. This is used
by figures layers when they percolates events up the tree of figures.
- interface LayerListener extends EventListener
-
The interface for listeners that respond to mouse clicks and
drags. Unlike the AWT MouseListener interface, this interface does not
include the enter and leave events, but does include the
drag event, for performance reasons.
- void mousePressed ( LayerEvent )
- Invoked when the mouse is clicked on a layer or figure.
- void mouseDragged ( LayerEvent )
- Invoked when the mouse moves while the button is still held down.
- void mouseReleased ( LayerEvent )
- Invoked when the mouse is released.
- interface LayerMotionListener extends EventListener
-
The interface for listeners that respond to motion
of the mouse over a figure.
- void mouseEntered ( LayerEvent )
- Invoked when the mouse enters a layer or figure.
- void mouseExited ( LayerEvent )
- Invoked when the mouse exits a layer or figure.
- void mouseMoved ( LayerEvent )
- Invoked when the mouse moves while over a layer or figure.
Mouse filters
A mouse filter is simply an object that filters mouse events
according to the button and modifiers contained within them. Any
object that handles events can use them to decide whether or not to
process an event. Mouse filters work with both LayerEvents
and MouseEvents.
- class MouseFilter
-
The class of mouse filters.
- MouseFilter ( int button )
- Construct a mouse filter that responds to the given mouse buttons
and modifier keys. The arguments must be constructed using the button
masks defined by java.awt.event.MouseEvent. More than one button can
be specified, in which case the filter will accept events from any of
them. In any case, modified keys are ignored.
- MouseFilter ( int button, int modifiers )
- Construct a mouse filter that responds to the given mouse buttons
and modifier keys. The two arguments must be constructed using the
button and modifier masks defined by java.awt.event.MouseEvent. More
than one button can be specified, in which case the filter will acceot
events from any of them. The filter will accept modifier sets that
exactly match modifiers.
- MouseFilter ( int button, int mask, int modifiers )
- Construct a mouse filter that responds to the given mouse buttons
and modifier keys. The three arguments must be constructed using the
button and modifier masks defined by java.awt.event.MouseEvent. More
than one button can be specified, in which case the filter will accept
events triggerd by any of them. The mask argument filters out
modifiers that will be ignored; the filter will accept modifier sets
that, after masking, exactly match modifiers.
- boolean accept ( MouseEvent )
boolean accept ( LayerEvent )
- Test if the filter accepts an event. If the event satisfies the
button and modifier conditions, this method returns true, otherwise it
returns false.
- static MouseFilter defaultFilter ( )
- Return a filter that accepts button 1 with any modifiers.
- static MouseFilter defaultSelectFilter ( )
- Return a filter that accepts the default events for
item selection. This is button 1 no modifiers.
- static MouseFilter defaultDeselectFilter ( )
- Return a filter that accepts the default events
for item deselection. This is button 1 with the shift modifier.
- static MouseFilter defaultToggleFilter ( )
- Return a filter that accepts the default events
for item selection toggling. This is button 1 with the
control modifier.
Event dispatchers
An event dispatcher is attached to one or more layers or figures
in order to make them respond to events. When a mouse event occurs on
the figure canvas, the event dispatch code in the figure canvas
searches for the top-most figure underneath the mouse, and then
searches up the tree of figures looking for an event dispatcher that
is prepared to handle that event.
Often, one event dispatcher will be attached to many figures,
enabling their behavior to be modified as a class. For example, an
interactive editor may have a single event dispatcher
for all vertices of a graph -- this makes it easier to set up
and change the behavior of mouse clicks on all vertices.
- interface EventDispatcher
- This is the basic layer event dispatcher interface. Currently, this
interface does not have the hooks to enable different event-dispatch
policies. These will be added in future to support policies other than
the default pointer-grab policy.
- void addComponentListener ( ComponentListener )
- Add a component listener to this figure. This listener will
be notified whenever the figure moves, changes shape, or
changes visibility.
- void addLayerListener ( LayerListener )
- Add a mouse drag listener to this figure.
- void addLayerMotionListener ( LayerMotionListener )
- Add a motion listener to this figure.
- void setEnabled ( boolean )
- Enable or disable event dispatch.
- boolean isEnabled ( )
- Test if this event dispatcher is enabled.
- void removeComponentListener ( ComponentListener )
-
Remove the component listener from this figure.
- void removeLayerListener ( LayerListener )
- Remove the drag listener from this figure.
- void removeLayerMotionListener ( LayerMotionListener )
-
Remove the motion listener from this figure.
Value events
Often, we are interested in changing values. For example, a mouse
movement on the canvas might change a value that is displayed in a
numeric text widget elsewhere on the screen. These changes are
triggered by the same kind of init-step-done sequence as the mouse
events (press-drag-release). To capture these kinds of operations, we
have defined a new event and listener.
- class ValueEvent extends EventObject
-
The class representing a series of change in a
numeric value.
- static int VALUE_INIT
- The flag saying that the sequence of changes is being initialized.
- static int VALUE_CHANGED
- The flag saying that the value has changed.
- static int VALUE_DONE
- The flag saying that the sequence of changes is over.
- static int INT_VALUE
- The flag saying that the value is an integer.
- static int DOUBLE_VALUE
- The flag saying that the value is an integer.
- ValueEvent ( Object source, int id, int value )
- Create a new event with the given source, flag, and value.
The flag must be one of VALUE_INIT, VALUE_CHANGED, or VALUE_DONE.
- ValueEvent ( Object source, int id, double value )
- Create a new event with the given source, flag, and value.
The flag must be one of VALUE_INIT, VALUE_CHANGED, or VALUE_DONE.
- int getIntValue ( )
- Get the integer value of the event.
- double getValue ( )
- Get the double value of the event.
- interface ValueListener extends EventListener
-
The interface for listeners that respond to a sequence
of value changes.
- void valueInit ( ValueEvent )
- Invoked when the value is first initialized.
- void valueChanged ( ValueEvent )
- Invoked when the value is changed.
- void valueDone ( ValueEvent )
- Invoked when the value is not going to change anymore.
Issues
-