org.geotools.swing
Class JMapPane

Object
  extended by Component
      extended by Container
          extended by JComponent
              extended by JPanel
                  extended by JMapPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, EventListener, Accessible, MapBoundsListener, MapLayerListListener

public class JMapPane
extends JPanel
implements MapLayerListListener, MapBoundsListener

A map display pane that works with a GTRenderer and MapContext to display features. It supports the use of tool classes to implement, for example, mouse-controlled zooming and panning.

Rendering is performed on a background thread and is managed by the RenderingExecutor class.

Adapted from original code by Ian Turton.

Since:
2.6
Author:
Michael Bedward, Ian Turton
See Also:
JMapFrame, MapPaneListener, CursorTool, Serialized Form
Module:
modules/unsupported/swing (gt-swing.jar)

Nested Class Summary
 
Nested classes/interfaces inherited from class JPanel
JPanel.AccessibleJPanel
 
Nested classes/interfaces inherited from class JComponent
JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
static int DEFAULT_RESIZING_PAINT_DELAY
          Default delay (milliseconds) before the map will be redrawn when resizing the pane.
 
Fields inherited from class JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JMapPane()
          Constructor - creates an instance of JMapPane with no map context or renderer initially
JMapPane(GTRenderer renderer, MapContext context)
          Constructor - creates an instance of JMapPane with the given renderer and map context.
 
Method Summary
 void addMapPaneListener(MapPaneListener listener)
          Register an object that wishes to receive MapPaneEvents
 void addMouseListener(MapMouseListener listener)
          Register an object that wishes to receive MapMouseEvents such as a StatusBar
protected  void afterImageMove(ReferencedEnvelope env, Rectangle paintArea)
          Called after the base image has been dragged.
 RenderedImage getBaseImage()
          Retrieve the map pane's current base image.
 ReferencedEnvelope getDisplayArea()
          Return a (copy of) the currently displayed map area.
 MapContext getMapContext()
          Get the map context associated with this map pane
 GTRenderer getRenderer()
          Get the renderer being used by this map pane
 int getResizeDelay()
          Get the length of the delay period between the pane being resized and the next repaint.
 AffineTransform getScreenToWorldTransform()
          Get a (copy of) the screen to world coordinate transform being used by this map pane.
 AffineTransform getWorldToScreenTransform()
          Get a (copy of) the world to screen coordinate transform being used by this map pane.
 boolean isAcceptingRepaints()
          Query whether the map pane is currently accepting or ignoring repaint requests from other GUI components and the system.
 void layerAdded(MapLayerListEvent event)
          Called when a new map layer has been added.
 void layerChanged(MapLayerListEvent event)
          Called when a map layer has changed, e.g. features added to a displayed feature collection
 void layerMoved(MapLayerListEvent event)
          Called when the bounds of a map layer have changed
 void layerRemoved(MapLayerListEvent event)
          Called when a map layer has been removed
 void mapBoundsChanged(MapBoundsEvent event)
          Called by the map context when its bounds have changed.
 void moveImage(int dx, int dy)
          Move the image currently displayed by the map pane from its current origin (x,y) to (x+dx, y+dy).
 void onRenderingCancelled()
          Called by the JMapPane.RenderingTask when rendering was cancelled.
 void onRenderingCompleted()
          Called by the JMapPane.RenderingTask when rendering has been completed Publishes a MapPaneEvent of type MapPaneEvent.Type.RENDERING_STOPPED to listeners.
 void onRenderingFailed()
          Called by the JMapPane.RenderingTask when rendering failed.
 void onRenderingRejected()
          Called when a rendering request has been rejected.
protected  void paintComponent(Graphics g)
          Called by the system to draw the layers currently visible layers.
 void removeMouseListener(MapMouseListener listener)
          Unregister the MapMouseListener object.
 void reset()
          Reset the map area to include the full extent of all layers and redraw the display
 void setCursorTool(CursorTool tool)
          Set the current cursor tool
 void setDisplayArea(Envelope envelope)
          Sets the area to display by calling the MapContext.setAreaOfInterest(com.vividsolutions.jts.geom.Envelope) method of this pane's map context.
 void setMapContext(MapContext context)
          Set the map context for this map pane to display
 void setMapLayerTable(MapLayerTable layerTable)
          Register a MapLayerTable object to be receive layer change events from this map pane and to control layer ordering, visibility and selection.
 void setRenderer(GTRenderer renderer)
          Set the renderer for this map pane.
 void setRepaint(boolean repaint)
          Specify whether the map pane should defer its normal repainting behaviour.
 void setResizeDelay(int delay)
          Set the length of the delay period between the pane being resized and the next repaint.
 
Methods inherited from class JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
 
Methods inherited from class JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_RESIZING_PAINT_DELAY

public static final int DEFAULT_RESIZING_PAINT_DELAY
Default delay (milliseconds) before the map will be redrawn when resizing the pane. This is to avoid flickering while drag-resizing.

See Also:
Constant Field Values
Constructor Detail

JMapPane

public JMapPane()
Constructor - creates an instance of JMapPane with no map context or renderer initially


JMapPane

public JMapPane(GTRenderer renderer,
                MapContext context)
Constructor - creates an instance of JMapPane with the given renderer and map context.

Parameters:
renderer - a renderer object
context - an instance of MapContext
Method Detail

setCursorTool

public void setCursorTool(CursorTool tool)
Set the current cursor tool

Parameters:
tool - the tool to set; null means no active cursor tool

addMouseListener

public void addMouseListener(MapMouseListener listener)
Register an object that wishes to receive MapMouseEvents such as a StatusBar

Parameters:
listener - an object that implements MapMouseListener
Throws:
IllegalArgumentException - if listener is null
See Also:
MapMouseListener

removeMouseListener

public void removeMouseListener(MapMouseListener listener)
Unregister the MapMouseListener object.

Parameters:
listener - the listener to remove
Throws:
IllegalArgumentException - if listener is null

addMapPaneListener

public void addMapPaneListener(MapPaneListener listener)
Register an object that wishes to receive MapPaneEvents

Parameters:
listener - an object that implements MapPaneListener
See Also:
MapPaneListener

setMapLayerTable

public void setMapLayerTable(MapLayerTable layerTable)
Register a MapLayerTable object to be receive layer change events from this map pane and to control layer ordering, visibility and selection.

Parameters:
layerTable - an instance of MapLayerTable
Throws:
IllegalArgumentException - if layerTable is null

getRenderer

public GTRenderer getRenderer()
Get the renderer being used by this map pane

Returns:
live reference to the renderer being used

setRenderer

public void setRenderer(GTRenderer renderer)
Set the renderer for this map pane.

Parameters:
renderer - the renderer to use

getMapContext

public MapContext getMapContext()
Get the map context associated with this map pane

Returns:
a live reference to the current map context

setMapContext

public void setMapContext(MapContext context)
Set the map context for this map pane to display

Parameters:
context - the map context

getDisplayArea

public ReferencedEnvelope getDisplayArea()
Return a (copy of) the currently displayed map area.

Note, this will not always be the same as the envelope returned by MapContext.getAreaOfInterest(). For example, when the map is displayed at the full extent of all layers MapContext.getAreaOfInterest() will return the union of the layer bounds while this method will return an evnelope that can included extra space beyond the bounds of the layers.

Returns:
the display area in world coordinates as a new ReferencedEnvelope

setDisplayArea

public void setDisplayArea(Envelope envelope)
Sets the area to display by calling the MapContext.setAreaOfInterest(com.vividsolutions.jts.geom.Envelope) method of this pane's map context. Does nothing if the MapContext has not been set. If neither the context or the envelope have coordinate reference systems defined this method does nothing.

The map area that ends up being displayed will often be larger than the requested display area. For instance, if the square area is requested, but the map pane's screen area is a rectangle with width greater than height, then the displayed area will be centred on the requested square but include additional area on each side.

You can pass any GeoAPI Envelope implementation to this method such as ReferenedEnvelope or Envelope2D.

Note: This method does not check that the requested area overlaps the bounds of the current map layers.

Parameters:
envelope - the bounds of the map to display
Throws:
IllegalStateException - if a map context is not set

reset

public void reset()
Reset the map area to include the full extent of all layers and redraw the display


setRepaint

public void setRepaint(boolean repaint)
Specify whether the map pane should defer its normal repainting behaviour.

Typical use:

myMapPane.setRepaint(false);

 // do various things that would cause time-consuming
 // re-paints normally

 myMapPane.setRepaint(true);
 myMapPane.repaint();
 

Parameters:
repaint - if true, paint requests will be handled normally; if false, paint requests will be deferred.
See Also:
isAcceptingRepaints()

isAcceptingRepaints

public boolean isAcceptingRepaints()
Query whether the map pane is currently accepting or ignoring repaint requests from other GUI components and the system.

Returns:
true if the pane is currently accepting repaint requests; false if it is ignoring them
See Also:
setRepaint(boolean)

getBaseImage

public RenderedImage getBaseImage()
Retrieve the map pane's current base image.

The map pane caches the most recent rendering of map layers as an image to avoid time-consuming rendering requests whenever possible. The base image will be re-drawn whenever there is a change to map layer data, style or visibility; and it will be replaced by a new image when the pane is resized.

This method returns a live reference to the current base image. Use with caution.

Returns:
a live reference to the current base image

getResizeDelay

public int getResizeDelay()
Get the length of the delay period between the pane being resized and the next repaint.

The map pane imposes a delay between resize events and repainting to avoid flickering of the display during drag-resizing.

Returns:
delay in milliseconds

setResizeDelay

public void setResizeDelay(int delay)
Set the length of the delay period between the pane being resized and the next repaint.

The map pane imposes a delay between resize events and repainting to avoid flickering of the display during drag-resizing.

Parameters:
delay - the delay in milliseconds; if < 0 the default delay period will be set

getScreenToWorldTransform

public AffineTransform getScreenToWorldTransform()
Get a (copy of) the screen to world coordinate transform being used by this map pane.

Returns:
a copy of the screen to world coordinate transform

getWorldToScreenTransform

public AffineTransform getWorldToScreenTransform()
Get a (copy of) the world to screen coordinate transform being used by this map pane. This method can be used to determine the current drawing scale...
double scale = mapPane.getWorldToScreenTransform().getScaleX();
 

Returns:
a copy of the world to screen coordinate transform

moveImage

public void moveImage(int dx,
                      int dy)
Move the image currently displayed by the map pane from its current origin (x,y) to (x+dx, y+dy). This method allows dragging the map without the overhead of redrawing the features during the drag. For example, it is used by PanTool.

Parameters:
dx - the x offset in pixels
dy - the y offset in pixels.

paintComponent

protected void paintComponent(Graphics g)
Called by the system to draw the layers currently visible layers. Client code should not use this method directly; instead call repaint().

Overrides:
paintComponent in class JComponent

onRenderingCompleted

public void onRenderingCompleted()
Called by the JMapPane.RenderingTask when rendering has been completed Publishes a MapPaneEvent of type MapPaneEvent.Type.RENDERING_STOPPED to listeners.

See Also:
MapPaneListener.onRenderingStopped(org.geotools.swing.event.MapPaneEvent)

onRenderingCancelled

public void onRenderingCancelled()
Called by the JMapPane.RenderingTask when rendering was cancelled. Publishes a MapPaneEvent of type MapPaneEvent.Type.RENDERING_STOPPED to listeners.

See Also:
MapPaneListener.onRenderingStopped(org.geotools.swing.event.MapPaneEvent)

onRenderingFailed

public void onRenderingFailed()
Called by the JMapPane.RenderingTask when rendering failed. Publishes a MapPaneEvent of type MapPaneEvent.Type.RENDERING_STOPPED to listeners.

See Also:
MapPaneListener.onRenderingStopped(org.geotools.swing.event.MapPaneEvent)

onRenderingRejected

public void onRenderingRejected()
Called when a rendering request has been rejected. This will be common, such as when the user pauses during drag-resizing fo the map pane. The base implementation does nothing. It is provided for sub-classes to override if required.


afterImageMove

protected void afterImageMove(ReferencedEnvelope env,
                              Rectangle paintArea)
Called after the base image has been dragged. Sets the new map area and transforms

Parameters:
env - the display area (world coordinates) prior to the image being moved
paintArea - the current drawing area (screen units)

layerAdded

public void layerAdded(MapLayerListEvent event)
Called when a new map layer has been added. Sets the layer as selected (for queries) and, if the layer table is being used, adds the new layer to the table.

Specified by:
layerAdded in interface MapLayerListListener
Parameters:
event - encapsulating the event information

layerRemoved

public void layerRemoved(MapLayerListEvent event)
Called when a map layer has been removed

Specified by:
layerRemoved in interface MapLayerListListener
Parameters:
event - encapsulating the event information

layerChanged

public void layerChanged(MapLayerListEvent event)
Called when a map layer has changed, e.g. features added to a displayed feature collection

Specified by:
layerChanged in interface MapLayerListListener
Parameters:
event - encapsulating the event information

layerMoved

public void layerMoved(MapLayerListEvent event)
Called when the bounds of a map layer have changed

Specified by:
layerMoved in interface MapLayerListListener
Parameters:
event - encapsulating the event information

mapBoundsChanged

public void mapBoundsChanged(MapBoundsEvent event)
Called by the map context when its bounds have changed. Used here to watch for a changed CRS, in which case the map is redisplayed at (new) full extent.

Specified by:
mapBoundsChanged in interface MapBoundsListener
Parameters:
event - The change event.


Copyright © 1996-2010 Geotools. All Rights Reserved.