## 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:

- pixelWidth
- pixelHeight
- center
- width
- scale
- envelope

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 `EventManager`s.
`void` `dispose()` Method that may be called when a `Canvas` is no longer needed.
`void` `disposeEventManagers()` Method that may be called when the `EventManager`s 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 `Graphic`s that occupy the given `DirectPosition`.
`Graphic[]` `getGraphicsIn(Envelope bounds)` Returns the `Graphic`s 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 `EventManager`s 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 `Graphic`s 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 `EventManager`s.

  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 `Graphic`s.
  Returns:
    the top-most `Graphic` at the given `DirectPosition`.

### getGraphicsAt

    Graphic[] getGraphicsAt(DirectPosition directPosition)

  Returns the `Graphic`s that occupy the given `DirectPosition`. The order is implementation-specific.

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

### getGraphicsIn

    Graphic[] getGraphicsIn(Envelope bounds)

  Returns the `Graphic`s that occupy the given `Envelope`. The order is implementation-specific.

  Parameters:
    `bounds` - the `Envelope` in which to look for `Graphic`s.
  Returns:
    the array of `Graphic`s 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.