/**************************************************************************************************
**
** $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:
*
* - pixelWidth
* - pixelHeight
* - center
* - width
* - scale
* - envelope
*
*
* @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.