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