/*
 * @(#)Paintable.java    1.0  20 October 2003
 *
 * Copyright 2004
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.gui;

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

/**
 * <P><CODE>Paintable</CODE> describes an object that can paint onto a
 * graphics context.</P>
 *
 * @author  Richard Rasala
 * @version 2.3
 * @since   2.3
 */
public interface Paintable {

    /**
     * <P>Paints onto a <CODE>Graphics</CODE> context g using information
     * from this object provided that the visibility property of the
     * object is set to <CODE>true</CODE>.</P>
     *
     * <P>After this method call is complete, the internal state of g
     * should be unchanged.  In addition, this method should not paint
     * outside of the region returned by <CODE>getBounds2D</CODE>.</P>
     *
     * <P><I>Implementation recommendation:</I></P>
     *
     * <P>To achieve the above goals, it is recommended that the graphics
     * context g be copied to a new graphics context h and that the clip
     * region of h be intersected with the Bounds2D rectangle.  This may
     * be done directly or may be achieved in one step by using the
     * method <CODE>getPreparedGraphics2D</CODE> which also takes care of
     * other issues.</P>
     *
     * @param g the graphics context on which to paint
     */
    void paint(Graphics g);
    
    
    /**
     * Returns a copy of the 2-dimensional bounds of the paint region
     * affected by the <CODE>paint</CODE> method.
     *
     * @return a copy of the 2-dimensional bounds of the paint region
     */
    Rectangle2D getBounds2D();
    
    
    /**
     * <P>Returns a copy of the center of the paint region affected
     * by the <CODE>paint</CODE> method.</P>
     *
     * <P>By default, this method may be implemented to return the
     * center of the rectangle returned by getBounds2D().  However,
     * a different result is permitted if the object geometry so
     * dictates.</P>
     *
     * @return a copy of the center of the paint region
     */
    Point2D getCenter();
    
    
    /**
     * <P>Tests if a point specified by coordinates is inside the paintable.</P>
     *
     * <P>This method must return <CODE>false</CODE> if one or more of the
     * following conditions occurs:</P>
     *
     * <UL>
     *   <LI>The point is not in the rectangle <CODE>getBounds2D</CODE>.</LI>
     *   <LI>The method <CODE>isVisible</CODE> returns <CODE>false</CODE>.</LI>
     * </UL>
     *
     * @param  x the x-coordinate of the point
     * @param  y the y-coordinate of the point
     * @return whether or not a specified point is inside the paintable
     */
    boolean contains(double x, double y);
    
    
    /**
     * <P>Tests if a specified point is inside the paintable.</P>
     *
     * <P>This method must return <CODE>false</CODE> if one or more of the
     * following conditions occurs:</P>
     *
     * <UL>
     *   <LI>The point is <CODE>null</CODE>.</LI>
     *   <LI>The point is not in the rectangle <CODE>getBounds2D</CODE>.</LI>
     *   <LI>The method <CODE>isVisible</CODE> returns <CODE>false</CODE>.</LI>
     * </UL>
     *
     * @param  p a specified <CODE>Point2D</CODE>
     * @return whether or not a specified point is inside the paintable
     */
    boolean contains(Point2D p);
    
    
    /**
     * <P>Sets the visibility property of this paintable.</P>
     *
     * <P>The default for the visibility property should be <CODE>true</CODE></P>.
     *
     * @param visible the visibility setting
     * @see #isVisible()
     */
    void setVisible(boolean visible);
    
    
    /**
     * Returns the current visibility property of this paintable.
     *
     * @see #setVisible(boolean)
     */
    boolean isVisible();
    
    
    /**
     * Sets the opacity value of this paintable between 0 and 1.
     *
     * @param opacity the opacity value of this paintable between 0 and 1
     * @see #getOpacity()
     */
    void setOpacity(float opacity);
    
    
    /**
     * Returns the opacity value of this paintable between 0 and 1.
     *
     * @return the opacity value of this paintable between 0 and 1
     * @see #setOpacity(float)
     */
    float getOpacity();
    
    
    /**
     * <P>Returns a copy of the given graphics context after modifying the copy
     * to set anti-aliasing on, to clip to within the bounds region, and to
     * apply the opacity of the paintable if needed.</P>
     *
     * <P>For convenience, return the graphics context as a
     * <CODE>Graphics2D</CODE> object.</P>
     *
     * @param  g the given graphics context to copy
     * @return a suitably prepared copy of the given graphics context
     */
    Graphics2D getPreparedGraphics2D(Graphics g);
    
}