Package diva.canvas

Class 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 Description
      CanvasPane()  

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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

      • 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