root/trunk/ObjectPainter.java

/**
 * ObjectPainter.java
 *
 * This class represents ways in which objects, such as PhysicalNodes and
 * PhysicalEdges, can be drawn on the screen.  Instances of it will actually
 * perform this drawing, as well as participate in the mouseclick resolution
 * process.  Subclasses will specialize in painting objects of certain types,
 * and may throw exceptions when asked to paint other types of objects.  This
 * class is not abstract, but it performs no specific action, thus, objects
 * can be made invisible by causing them to be painted by instances of this
 * class.
 *
 * This is somewhat inefficient because each object drawn requires three virtual
 * method calls and several casts, but as a result, there is no need for code
 * duplication in any of the subclasses.
 *
 * Also, it's possible to set the AffineTransform in a Graphics2D object before
 * using the ObjectPainter, in which case ObjectPainter would no longer need to
 * use AffineTransforms.  However, this scales everything, including line
 * thickness and circle radius, so the implementation would actually be a
 * little more complex to compensate for that.  I don't think that affects
 * efficiency much, but more research is needed.
 *
 * Other possible optimizations, all of which are somewhat dirty, include: using
 * protected members instead of passing things on the stack, removing
 * needToPaint(), and instead giving computeLocation a Graphics2D (precluding
 * its use in visualDistanceTo()) and letting it return null if !needToPaint().
 * Performance benchmarks are needed - though most of the problems come from
 * antialiasing, I think.
 */

import java.awt.*;
import java.awt.geom.*;
import java.util.*;

public class ObjectPainter {

        /// An instance can paint every type, but won't actually do anything.
        public ObjectPainter() {}

        /**
         * Draws object, translated according to realToScreen, on g.
         */
        public final void paintObject(Object object, AffineTransform realToScreen, BackgroundMap map, Graphics2D g) {
                if(!visible) return;
                // compute, using the transform, the location of the object onscreen
                // in our subclasses, the location will probably be a point or line
                Object location = computeLocation(object, realToScreen);
                // quit if we don't need to paint the object
                if(!needToPaint(object, location, map, g)) return;
                // set the color, etc...
                setupPainting(g);
                // paint the object...
                paintSingleObject(object, location, g);
        }

        /**
         * Draws all given objects, translated according to realToScreen, on g
         */
        public final void paintObjects(Collection objects, AffineTransform realToScreen, BackgroundMap map,
                                       Graphics2D g) {
                if(!visible) return;

                // set the color, etc...
                setupPainting(g);

                // for all the objects we're given...
                Iterator iterator = objects.iterator();
                while(iterator.hasNext()) {
                        Object object = iterator.next();
                        // figure out where on the screen it should be painted
                        Object location = computeLocation(object, realToScreen);
                        // if we don't need to draw this node, go on to the next
                        if(!needToPaint(object, location, map, g)) continue;
                        // paint it
                        paintSingleObject(object, location, g);
                }
        }

        /*
         * The following private methods should be overridden in subclasses
         * to implement the drawing of their specific types of objects.  They
         * can throw ClassCastExceptions if they are asked to act upon objects
         * they don't know how to paint.
         */

        /**
         * Returns how far (in pixels) from the onscreen visual representation
         * of the object the given point is.  If the point is on the object, the
         * distance should be less than or equal to zero.  This is used to allow
         * smart detection of mouseclicks on or near an object.
         */

        public double visualDistanceTo(Object object, Point2D.Double real, BackgroundMap map, AffineTransform realToScreen) {
                return Double.POSITIVE_INFINITY;
        }

        /**
         * Whether the object should actually be drawn.
         */
        public void setVisible(boolean v) {     visible = v; }
        public boolean getVisible() { return visible; }

        private boolean visible = true;

        /**
         * This sets up the Graphics2D context to draw any number of points in
         * the style this ObjectPainter represents.  In the future, this could
         * become non-trivial, so we allow for multiple objects to be painted
         * in the same style while only doing this once.  This is where you set
         * the color, for example.
         */
        protected void setupPainting(Graphics2D g) {}

        /**
         * This computes the location the object will be drawn on screen, which
         * should be the object's location transformed by realToScreen.  The
         * location will usually be a Point or Line in subclasses, it is Object
         * here because that is their common ancestor.  The returned location
         * will be passed to needToPaint() and paintSingleObject().
         */
        protected Object computeLocation(Object object, AffineTransform realToScreen) { return null; }

        /**
         * This must return true if the object, when painted, would be visible
         * (i.e. would be inside g's clipping region).  It can return true
         * otherwise also, which will cause unnecessary but harmless painting.
         */
        protected boolean needToPaint(Object object, Object location, BackgroundMap map, Graphics2D g) {
                return false;
        }

        /**
         * This paints object on g at the given location.
         */
        protected void paintSingleObject(Object object, Object location, Graphics2D g) {}

}