/**************************************************************************************************
 **
 ** $Id: Canvas.java 831 2006-05-01 00:27:23Z Desruisseaux $
 **
 ** $URL: http://svn.code.sf.net/p/geoapi/code/branches/2.0.x/geoapi/src/main/java/org/opengis/go/display/canvas/Canvas.java $
 **
 ** Copyright (C) 2003-2005 Open GIS Consortium, Inc.
 ** All Rights Reserved. http://www.opengis.org/legal/
 **
 *************************************************************************************************/

package org.opengis.go.display.canvas;

import org.opengis.go.display.DisplayFactory;
import org.opengis.go.display.event.EventManager;
import org.opengis.go.display.primitive.Graphic;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.operation.IncompatibleOperationException;
import org.opengis.referencing.operation.MathTransform;
import org.opengis.spatialschema.geometry.DirectPosition;
import org.opengis.spatialschema.geometry.Envelope;

/**
 * Canvas defines a common abstraction for implementations that
 * manage the display and user manipulation of Graphic instances.
 * A Canvas with an XY (Cartesian) display field should support
 * the following properties:
 * 
 *
 * @author Open GIS Consortium, Inc.
 * @version $Revision: 658 $, $Date: 2006-02-23 12:09:34 +1100 (jeu., 23 févr. 2006) $
 */
public interface Canvas {

    //**  deconstructor  **

    /**
     * Method that may be called when a Canvas is no longer
     * needed.  Implementations may use this method to release resources or to
     * return the object to an object pool.  It is an error to reference a
     * Canvas after its dispose method has been called.
     */
    void dispose();

    /**
     * Method that may be called when the EventManagers of a 
     * Canvas are no longer needed. Implementations may use this
     * method to release resources or to return the object to an object pool. It
     * is an error to reference any EventManager s of a
     * Canvas after this method has been called.
     */
    void disposeEventManagers();

    //**  accessors/mutators  **

    /**
     * Returns the unique identifier of this Canvas, which is
     * assigned by the implementation. The UID is immutable and may be used to
     * retrieve a particular Canvas from the
     * GraphicFactory.
     * 
     * @return the UID of this Canvas.
     */
    String getUID();

    /**
     * Sets the title of this Canvas.  The title of a
     * Canvas may or may not be displayed on the titlebar of an
     * application's window.
     * 
     * @param title the new title for this Canvas.
     */
    void setTitle(String title);

    /**
     * Returns the title assigned to this Canvas.
     * 
     * @return the title of this Canvas.
     */
    String getTitle();

    /**
     * Returns the DisplayFactory associated with this
     * Canvas.
     * 
     * @return the DisplayFactory.
     */
    DisplayFactory getFactory();

    /**
     * Returns a copy of the current state of this Canvas. The
     * object returned will implement CanvasState or one of its
     * subinterfaces, depending on the type of Canvas.
     */
    CanvasState getState();

    /**
     * Returns true if the given coordinate is visible on this 
     * Canvas.
     */
    boolean isVisible(DirectPosition coordinate);

    //**  Graphic methods  **

    /**
     * Adds the given Graphic to this Canvas.
     * Implementations should respect the zOrder retrieved by calling
     * Graphic.getGraphicStyle().getZOrderHint().  When two added
     * Graphics have the same zOrder, the most recently added
     * one should be on top.
     * 
     * @param graphic the Graphic to add.
     */
    Graphic add(Graphic graphic);

    /**
     * Adds the given Graphic to this Canvas,
     * immediately placing the Graphic in an editing/drawing
     * mode, as defined by the Canvas implementation.  A
     * Graphic added as editable may or may not be visible when
     * it is added, as it may wait for user input to define the 
     * Graphic's values through mouse gestures or key input.
     * 
     * @param graphic the Graphic to add as editable.
     */
    Graphic addAsEditable(Graphic graphic);

    /**
     * Removes the given Graphic from this Canvas.
     * 
     * @param graphic the Graphic to remove.
     */
    void remove(Graphic graphic);

    /**
     * Returns the EventManager subinterface, based on the class type.
     * 

* Note: While the class implementing Canvas may additionally * implement EventManager subinterface(s). While this design * is simple, it limits the Canvas object to the input * mechanisms supported by to those particular EventManager * subinterface(s), and thus is discouraged. *

* If the class implementing Canvas does not implement the * particular EventManager subinterface, then this method can * look up the EventManager via an implementation-specific * mechanism. Otherwise, if the class implementing Canvas does * implement the particular EventManager subinterface, this * method can return the this reference. * * @param eventManagerClass the class type of the EventManager subinterface. * @return a class that implements the requested EventManager subinterface, * or null if there is no implementing class. */ EventManager findEventManager(Class eventManagerClass); /** * Adds the EventManager subinterface if it not currently in * the Canvas's collection of EventManagers. * * @param eventManager the EventManager type to be added to * the Canvas's collection. */ void addEventManager(EventManager eventManager); /** * Returns the top-most Graphic that occupies given * DirectPosition. The top-most Graphic will * have the highest zOrder. * * @param directPosition the DirectPosition at which to look * for Graphics. * @return the top-most Graphic at the given * DirectPosition. */ Graphic getTopGraphicAt(DirectPosition directPosition); /** * Returns the Graphics that occupy the given * DirectPosition. The order is implementation-specific. * * @param directPosition the DirectPosition at which to look * for Graphics. * @return the array of Graphics at the given * DirectPosition. */ Graphic[] getGraphicsAt(DirectPosition directPosition); /** * Returns the Graphics that occupy the given * Envelope. The order is implementation-specific. * * @param bounds the Envelope in which to look for * Graphics. * @return the array of Graphics in the given * Envelope. */ Graphic[] getGraphicsIn(Envelope bounds); //** canvas listener methods ** /** * Adds the given listener that will be notified when the state of this * Canvas has changed. */ void addCanvasListener(CanvasListener listener); /** * Removes the given listener. */ void removeCanvasListener(CanvasListener listener); //** CanvasManager methods ** /** * Enables the given CanvasHandler, removing the current * handler (if any). The new handler's * handlerEnabled(CanvasController) method is called, passing * in a new, active CanvasController that will allow the * programmer to modify the Canvas's properties.

* Implementation suggestion: * *


     * 
     * public void enableCanvasHandler(CanvasHandler handler) {
     *      if (handler != activeHandler) {
     *          if (activeHandler != null) {
     *              removeCanvasHandler(activeHandler);
     *          }
     *          activeHandler = handler;
     *          activeController = new CanvasController(this);
     *          activeHandler.handlerEnabled(activeController);
     *      }
     *  }
     * 
*/ void enableCanvasHandler(CanvasHandler handler); /** * Removes the given CanvasHandler from this * Canvas. */ void removeCanvasHandler(CanvasHandler handler); /** * Returns the currently active CanvasHandler or null if no * handler is active. */ CanvasHandler getActiveCanvasHandler(); //** imlementation hints ** /** * Sets a rendering hint for implementation or platform specific rendering * information. * * @param hintName the name of the hint. * @param hint the rendering hint. */ void setImplHint(String hintName, Object hint); /** * Returns the rendering hint associated with the hint name. * * @param hintName the name of the hint. * @return the rendering hint. */ Object getImplHint(String hintName); //** CoordinateReferenceSystem methods ** /** * Returns the Coordinate Reference System associated with the display of * this Canvas. The display Coordinate Reference System * corresponds to the geometry of the display device (e.g. video monitor = * Cartesian, planetarium = Spherical). * * @return the display Coordinate Reference System */ CoordinateReferenceSystem getDisplayCoordinateReferenceSystem(); /** * Returns the objective Coordinate Reference System (e.g. the projection of * a georeferenced Coordinate Reference System) for this Canvas. * This is the default objective Coordinate Reference System for this * Canvas. * * @return the objective Coordinate Reference System */ CoordinateReferenceSystem getObjectiveCoordinateReferenceSystem(); /** * Sets the objective Coordinate Reference System (e.g. the projection of a * georeferenced Coordinate Reference System) for this Canvas. * This is the default objective Coordinate Reference System for this * Canvas. * * @param crs the objective Coordinate Reference System * @throws IncompatibleOperationException when the specified transformation does not apply to either the objective or the display Coordinate Reference Systems. */ void setObjectiveCoordinateReferenceSystem(CoordinateReferenceSystem crs); /** * Sets the objective Coordinate Reference System (e.g. the projection of a * georeferenced Coordinate Reference System) for this Canvas. * This is the default objective Coordinate Reference System for this * Canvas. * * @param crs the objective Coordinate Reference System * @param objectiveToDisplay the trasformation that converts between this objective Coordinate Reference System and the Canvas display Coordinate Reference System. * @param displayToObjective the trasformation that converts between the Canvas display Coordinate Reference System and this objective Coordinate Reference System. * @throws IncompatibleOperationException when the specified transformation does not apply to either the objective or the display Coordinate Reference Systems. */ void setObjectiveCoordinateReferenceSystem(CoordinateReferenceSystem crs, MathTransform objectiveToDisplay, MathTransform displayToObjective) throws IncompatibleOperationException; /** * Returns the coordinate transformation object for this * Canvas. This allows the Canvas to resolve * conversions of coordinates between the objective and display Coordinate Reference Systems. * @return the coordinate transformation object */ MathTransform getObjectiveToDisplayTransform(); /** * Returns the coordinate transformation object for this * Canvas. This allows the Canvas to resolve * conversions of coordinates between the display and objective Coordinate Reference Systems. * @return the coordinate transformation object */ MathTransform getDisplayToObjectiveTransform(); }

Ads help maintain this website.