diva.canvas

Class CanvasPane

java.lang.Object

diva.canvas.CanvasPane

All Implemented Interfaces:

CanvasComponent, EventAcceptor

Direct Known Subclasses:

BasicCanvasPane, GraphicsPane

public abstract class CanvasPane
extends java.lang.Object
implements EventAcceptor, CanvasComponent

A canvas pane groups canvas layers. The layers all share the same logical-to-screen transform as the canvas pane. This is an abstract superclass of all canvas panes, and provides the implementation of everything related to panes but the storage of the layers. Subclasses must provide methods to add and (possibly) reorder and remove layers. Particular applications may choose to create their own special-purpose sub-classes.

Version:

$Id$

Author:

John Reekie

Pt.AcceptedRating:

Yellow

Constructor Summary

Constructors

Constructor and Description
CanvasPane()

Method Summary

Modifier and Type	Method and Description
protected void	_initNewLayer(CanvasLayer l) Helper method to initialize a layer when it is added to this pane.
protected void	_nullifyLayer(CanvasLayer l) Helper method to tell a layer when it is been removed from this pane.
void	dispatchEvent(java.awt.AWTEvent event) Dispatch an AWT event on this pane.
JCanvas	getCanvas() Get the containing canvas, or null if there isn't one.
CanvasComponent	getParent() Get the parent component, or null if there isn't one.
java.awt.geom.Point2D	getSize() Get the size of this pane, in logical coordinates.
protected java.lang.String	getToolTipText(LayerEvent event) Get the toolTipText for the point in the given LayerEvent.
TransformContext	getTransformContext() Return the transform context of this pane.
boolean	isAntialiasing() Return whether or not this pane is antialiased.
boolean	isEnabled() Test the enabled flag of this pane.
java.util.Iterator	layers() Return an iteration of the layers, in undefined order.
abstract java.util.Iterator	layersFromBack() Return an iteration of the layers from back to front -- that is, in redraw order.
abstract java.util.Iterator	layersFromFront() Return an iteration of the layers from front to back -- that is, in event-processing order.
void	paint(java.awt.Graphics2D g) Paint this pane onto a 2D graphics context.
void	paint(java.awt.Graphics2D g, java.awt.geom.Rectangle2D region) Paint this pane onto a 2D graphics object, within the given region.
protected void	processLayerEvent(LayerEvent event) Process a layer event that has occurred on this pane.
void	repaint() Schedule a repaint of this pane.
void	repaint(DamageRegion d) Accept notification that a repaint has occurred somewhere in this pane.
void	scale(double xcenter, double ycenter, double xscale, double yscale) Scale this pane the given amount.
void	setAntialiasing(boolean val) Set whether or not to use antialiasing when drawing this pane.
void	setCanvas(JCanvas canvas) Set the containing canvas of this pane.
void	setEnabled(boolean flag) Set the enabled flag of this pane.
void	setParent(CanvasComponent parent) Set the parent component of this pane.
void	setSize(double width, double height) Set the size of this pane, in logical coordinates.
void	setSize(java.awt.geom.Point2D size) Set the size of this pane, in logical coordinates.
void	setTransform(java.awt.geom.AffineTransform at) Set the transform that maps logical coordinates into the parent's coordinates.
void	translate(double x, double y) Translate this pane the given distance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CanvasPane

public CanvasPane()

Method Detail

dispatchEvent

public void dispatchEvent(java.awt.AWTEvent event)

Dispatch an AWT event on this pane. Currently only layer events are handled.

Specified by:

dispatchEvent in interface EventAcceptor

Parameters:

event - The event

getParent

public final CanvasComponent getParent()

Get the parent component, or null if there isn't one. Only one of the canvas or the display parent can be non-null.

Specified by:

getParent in interface CanvasComponent

Returns:

the parent component or null.

getCanvas

public final JCanvas getCanvas()

Get the containing canvas, or null if there isn't one. Only one of the canvas or the display parent can be non-null.

Returns:

the containing canvas or null.

isAntialiasing

public final boolean isAntialiasing()

Return whether or not this pane is antialiased.

Returns:

true if the pane is antialiased.

getToolTipText

protected java.lang.String getToolTipText(LayerEvent event)

Get the toolTipText for the point in the given LayerEvent. Pass the event to all the layers in this canvas pane in order from front to back. The returned value will be the first non-null tooltip string returned by one of the layers. If all the layers return a null tooltip, then return null indicating that no tooltip should be displayed.

Parameters:

event - The event

Returns:

The tool tip or null

getTransformContext

public final TransformContext getTransformContext()

Return the transform context of this pane.

Specified by:

getTransformContext in interface CanvasComponent

Returns:

the transform context.

getSize

public java.awt.geom.Point2D getSize()

Get the size of this pane, in logical coordinates. If the pane is contained directly in a JCanvas, the size is obtained from the JCanvas. Otherwise, it returns the size previously set with setSize().

Returns:

the size

isEnabled

public final boolean isEnabled()

Test the enabled flag of this pane. Note that this flag does not indicate whether the pane is actually enabled, as its canvas or one if its ancestors may not be enabled.

Specified by:

isEnabled in interface EventAcceptor

Returns:

True if the pane is enabled.

layers

public java.util.Iterator layers()

Return an iteration of the layers, in undefined order. The default implementation simply calls layersFromFront().

Returns:

The iterator.

layersFromBack

public abstract java.util.Iterator layersFromBack()

Return an iteration of the layers from back to front -- that is, in redraw order.

Returns:

The iterator.

layersFromFront

public abstract java.util.Iterator layersFromFront()

Return an iteration of the layers from front to back -- that is, in event-processing order.

Returns:

The iterator.

paint

public void paint(java.awt.Graphics2D g)

Paint this pane onto a 2D graphics context. This implementation paints all layers that implement VisibleComponent, from back to front. The transform of this pane is written into the graphics context, so any layer that changes the transform is obliged to return it to its prior state after finishing.

Parameters:

g - The graphics context on which to paint.

paint

public void paint(java.awt.Graphics2D g,
                  java.awt.geom.Rectangle2D region)

Paint this pane onto a 2D graphics object, within the given region. This implementation paints all layers that implement VisibleComponent, from highest index to lowest index. The transform of this pane is written into the graphics context, so any layer that changes the transform is obliged to return it to its prior state after finishing.

Parameters:

g - The graphics context on which to paint.

region - The object to be painted.

processLayerEvent

protected void processLayerEvent(LayerEvent event)

Process a layer event that has occurred on this pane. If the pane is not enabled, return without doing anything. Otherwise, pass the event to each layer that implements the EventAcceptor interface, from front to back. After each layer, check whether the event has been consumed, and return if so.

Parameters:

event - The layer event

repaint

public void repaint()

Schedule a repaint of this pane. The pane passes the repaint request to its parent, if it has one.

Specified by:

repaint in interface CanvasComponent

repaint

public void repaint(DamageRegion d)

Accept notification that a repaint has occurred somewhere in this pane. Notify the damage region that it is passing through a transform context, and then forward the notification up to the parent.

Specified by:

repaint in interface CanvasComponent

Parameters:

d - The damage region.

setAntialiasing

public void setAntialiasing(boolean val)

Set whether or not to use antialiasing when drawing this pane.

Parameters:

val - True if antialiasing is used when drawing.

setCanvas

public final void setCanvas(JCanvas canvas)

Set the containing canvas of this pane. If the canvas is not null and the parent is not null, throw an exception. This method is not intended for general use, only by JCanvas and subclasses.

Parameters:

canvas - The containing canvas.

setEnabled

public final void setEnabled(boolean flag)

Set the enabled flag of this pane.

Specified by:

setEnabled in interface EventAcceptor

Parameters:

flag - If false, then the pane will not respond to user input events.

setParent

public final void setParent(CanvasComponent parent)

Set the parent component of this pane. If the parent is not null and the canvas is not null, throw an exception.

Parameters:

parent - The parent of the pane.

setSize

public void setSize(double width,
                    double height)

Set the size of this pane, in logical coordinates. If the pane is directly contained by a JCanvas, subsequent calls to the getSize() and getPreferredSize() methods of the JCanvas will return the size set here.

Parameters:

width - The width

height - The height

setSize

public void setSize(java.awt.geom.Point2D size)

Set the size of this pane, in logical coordinates. If the pane is directly contained by a JCanvas, subsequent calls to the getSize() and getPreferredSize() methods of the JCanvas will return the size set here.

Parameters:

size - The size of the pane.

setTransform

public final void setTransform(java.awt.geom.AffineTransform at)

Set the transform that maps logical coordinates into the parent's coordinates. If there is no parent, the "parent" is taken to be the screen. An exception will be thrown if the transform is null. Note that the transform will be remembered by this pane, so any further changes to the transform will affect the pane. This version has a flag that can be used to avoid calling the 'updateRangeModel' method

Parameters:

at - The transform.

translate

public void translate(double x,
                      double y)

Translate this pane the given distance. The translation is done such that it works "correctly" in the presence of scaling.

Parameters:

x - The x amount by which to translate.

y - The y amount by which to translate.

scale

public void scale(double xcenter,
                  double ycenter,
                  double xscale,
                  double yscale)

Scale this pane the given amount.

Parameters:

xcenter - The x value of the point to scale about.

ycenter - The y value of the point to scale about.

xscale - The x amount of which to scale by.

yscale - The y amount of which to scale by.

_initNewLayer

protected void _initNewLayer(CanvasLayer l)

Helper method to initialize a layer when it is added to this pane. Any subclass must be sure to call this whenever it creates a new layer or accepts one to add to itself.

Parameters:

l - The canvas layer

_nullifyLayer

protected void _nullifyLayer(CanvasLayer l)

Helper method to tell a layer when it is been removed from this pane. Any subclass must be sure to call this whenever it removes a layer.

Parameters:

l - The canvas layer