org.opengis.go.display.canvas
Interface Canvas

All Known Subinterfaces:
Map2D, WebCanvas, WebMap2D

public interface Canvas

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:


Method Summary
 Graphic add(Graphic graphic)
          Adds the given Graphic to this Canvas.
 Graphic addAsEditable(Graphic graphic)
          Adds the given Graphic to this Canvas, immediately placing the Graphic in an editing/drawing mode, as defined by the Canvas implementation.
 void addCanvasListener(CanvasListener listener)
          Adds the given listener that will be notified when the state of this Canvas has changed.
 void addEventManager(EventManager eventManager)
          Adds the EventManager subinterface if it not currently in the Canvas's collection of EventManagers.
 void dispose()
          Method that may be called when a Canvas is no longer needed.
 void disposeEventManagers()
          Method that may be called when the EventManagers of a Canvas are no longer needed.
 void enableCanvasHandler(CanvasHandler handler)
          Enables the given CanvasHandler, removing the current handler (if any).
 EventManager findEventManager(Class eventManagerClass)
          Returns the EventManager subinterface, based on the class type.
 CanvasHandler getActiveCanvasHandler()
          Returns the currently active CanvasHandler or null if no handler is active.
 CoordinateReferenceSystem getDisplayCoordinateReferenceSystem()
          Returns the Coordinate Reference System associated with the display of this Canvas.
 MathTransform getDisplayToObjectiveTransform()
          Returns the coordinate transformation object for this Canvas.
 DisplayFactory getFactory()
          Returns the DisplayFactory associated with this Canvas.
 Graphic[] getGraphicsAt(DirectPosition directPosition)
          Returns the Graphics that occupy the given DirectPosition.
 Graphic[] getGraphicsIn(Envelope bounds)
          Returns the Graphics that occupy the given Envelope.
 Object getImplHint(String hintName)
          Returns the rendering hint associated with the hint name.
 CoordinateReferenceSystem getObjectiveCoordinateReferenceSystem()
          Returns the objective Coordinate Reference System (e.g. the projection of a georeferenced Coordinate Reference System) for this Canvas.
 MathTransform getObjectiveToDisplayTransform()
          Returns the coordinate transformation object for this Canvas.
 CanvasState getState()
          Returns a copy of the current state of this Canvas.
 String getTitle()
          Returns the title assigned to this Canvas.
 Graphic getTopGraphicAt(DirectPosition directPosition)
          Returns the top-most Graphic that occupies given DirectPosition.
 String getUID()
          Returns the unique identifier of this Canvas, which is assigned by the implementation.
 boolean isVisible(DirectPosition coordinate)
          Returns true if the given coordinate is visible on this Canvas.
 void remove(Graphic graphic)
          Removes the given Graphic from this Canvas.
 void removeCanvasHandler(CanvasHandler handler)
          Removes the given CanvasHandler from this Canvas.
 void removeCanvasListener(CanvasListener listener)
          Removes the given listener.
 void setImplHint(String hintName, Object hint)
          Sets a rendering hint for implementation or platform specific rendering information.
 void setObjectiveCoordinateReferenceSystem(CoordinateReferenceSystem crs)
          Sets the objective Coordinate Reference System (e.g. the projection of a georeferenced Coordinate Reference System) for this Canvas.
 void setObjectiveCoordinateReferenceSystem(CoordinateReferenceSystem crs, MathTransform objectiveToDisplay, MathTransform displayToObjective)
          Sets the objective Coordinate Reference System (e.g. the projection of a georeferenced Coordinate Reference System) for this Canvas.
 void setTitle(String title)
          Sets the title of this Canvas.
 

Method Detail

dispose

void dispose()
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.


disposeEventManagers

void disposeEventManagers()
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.


getUID

String getUID()
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.

Returns:
the UID of this Canvas.

setTitle

void setTitle(String title)
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.

Parameters:
title - the new title for this Canvas.

getTitle

String getTitle()
Returns the title assigned to this Canvas.

Returns:
the title of this Canvas.

getFactory

DisplayFactory getFactory()
Returns the DisplayFactory associated with this Canvas.

Returns:
the DisplayFactory.

getState

CanvasState getState()
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.


isVisible

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


add

Graphic add(Graphic graphic)
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.

Parameters:
graphic - the Graphic to add.

addAsEditable

Graphic addAsEditable(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.

Parameters:
graphic - the Graphic to add as editable.

remove

void remove(Graphic graphic)
Removes the given Graphic from this Canvas.

Parameters:
graphic - the Graphic to remove.

findEventManager

EventManager findEventManager(Class eventManagerClass)
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.

Parameters:
eventManagerClass - the class type of the EventManager subinterface.
Returns:
a class that implements the requested EventManager subinterface, or null if there is no implementing class.

addEventManager

void addEventManager(EventManager eventManager)
Adds the EventManager subinterface if it not currently in the Canvas's collection of EventManagers.

Parameters:
eventManager - the EventManager type to be added to the Canvas's collection.

getTopGraphicAt

Graphic getTopGraphicAt(DirectPosition directPosition)
Returns the top-most Graphic that occupies given DirectPosition. The top-most Graphic will have the highest zOrder.

Parameters:
directPosition - the DirectPosition at which to look for Graphics.
Returns:
the top-most Graphic at the given DirectPosition.

getGraphicsAt

Graphic[] getGraphicsAt(DirectPosition directPosition)
Returns the Graphics that occupy the given DirectPosition. The order is implementation-specific.

Parameters:
directPosition - the DirectPosition at which to look for Graphics.
Returns:
the array of Graphics at the given DirectPosition.

getGraphicsIn

Graphic[] getGraphicsIn(Envelope bounds)
Returns the Graphics that occupy the given Envelope. The order is implementation-specific.

Parameters:
bounds - the Envelope in which to look for Graphics.
Returns:
the array of Graphics in the given Envelope.

addCanvasListener

void addCanvasListener(CanvasListener listener)
Adds the given listener that will be notified when the state of this Canvas has changed.


removeCanvasListener

void removeCanvasListener(CanvasListener listener)
Removes the given listener.


enableCanvasHandler

void enableCanvasHandler(CanvasHandler handler)
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);
      }
  }
 


removeCanvasHandler

void removeCanvasHandler(CanvasHandler handler)
Removes the given CanvasHandler from this Canvas.


getActiveCanvasHandler

CanvasHandler getActiveCanvasHandler()
Returns the currently active CanvasHandler or null if no handler is active.


setImplHint

void setImplHint(String hintName,
                 Object hint)
Sets a rendering hint for implementation or platform specific rendering information.

Parameters:
hintName - the name of the hint.
hint - the rendering hint.

getImplHint

Object getImplHint(String hintName)
Returns the rendering hint associated with the hint name.

Parameters:
hintName - the name of the hint.
Returns:
the rendering hint.

getDisplayCoordinateReferenceSystem

CoordinateReferenceSystem getDisplayCoordinateReferenceSystem()
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).

Returns:
the display Coordinate Reference System

getObjectiveCoordinateReferenceSystem

CoordinateReferenceSystem getObjectiveCoordinateReferenceSystem()
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.

Returns:
the objective Coordinate Reference System

setObjectiveCoordinateReferenceSystem

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.

Parameters:
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.

setObjectiveCoordinateReferenceSystem

void setObjectiveCoordinateReferenceSystem(CoordinateReferenceSystem crs,
                                           MathTransform objectiveToDisplay,
                                           MathTransform displayToObjective)
                                           throws IncompatibleOperationException
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.

Parameters:
crs - the objective Coordinate Reference System
objectiveToDisplay - the trasformation that converts between this objective Coordinate Reference System and the Canvas display Coordinate Reference System.
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.

getObjectiveToDisplayTransform

MathTransform getObjectiveToDisplayTransform()
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.

Returns:
the coordinate transformation object

getDisplayToObjectiveTransform

MathTransform getDisplayToObjectiveTransform()
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.

Returns:
the coordinate transformation object


Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.