org.jdesktop.swingx

Class JXMapViewer

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JPanel

org.jdesktop.swingx.JXMapViewer

All Implemented Interfaces:

ImageObserver, MenuContainer, DesignMode, Serializable, Accessible

public class JXMapViewer
extends JPanel
implements DesignMode

A tile oriented map component that can easily be used with tile sources on the web like Google and Yahoo maps, satellite data such as NASA imagery, and also with file based sources like pre-processed NASA images. A known map provider can be used with the SLMapServerInfo, which will connect to a 2km resolution version of NASA's Blue Marble Next Generation imagery. @see SLMapServerInfo for more information. Note, the JXMapViewer has three center point properties. The addressLocation property represents an abstract center of the map. This would usually be something like the first item in a search result. It is a GeoPosition. The centerPosition property represents the current center point of the map. If the user pans the map then the centerPosition point will change but the addressLocation will not. Calling recenterToAddressLocation() will move the map back to that center address. The center property represents the same point as the centerPosition property, but as a Point2D in pixel space instead of a GeoPosition in lat/long space. Note that the center property is a Point2D in the entire world bitmap, not in the portion of the map currently visible. You can use the getViewportBounds() method to find the portion of the map currently visible and adjust your calculations accordingly. Changing the center property will change the centerPosition property and vice versa. All three properties are bound.

Author:

Joshua.Marinacci@sun.com

See Also:

SLMapServerInfo, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JPanel

JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class javax.swing.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 java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.beans.DesignMode

PROPERTYNAME

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
JXMapViewer() Create a new JXMapViewer.

Method Summary

Methods

Modifier and Type	Method and Description
void	calculateZoomFrom(Set<GeoPosition> positions) Calculates a zoom level so that all points in the specified set will be visible on screen.
Point2D	convertGeoPositionToPoint(GeoPosition pos) Converts the specified GeoPosition to a point in the JXMapViewer's local coordinate space.
GeoPosition	convertPointToGeoPosition(Point2D pt) Converts the specified Point2D in the JXMapViewer's local coordinate space to a GeoPosition on the map.
protected void	drawMapTiles(Graphics g, int zoom, Rectangle viewportBounds) Draw the map tiles.
GeoPosition	getAddressLocation() Gets the current address location of the map.
Point2D	getCenter() Gets the current pixel center of the map.
GeoPosition	getCenterPosition() A property indicating the center position of the map
Image	getLoadingImage() A property for an image which will be display when an image is still loading.
Painter<? super JXMapViewer>	getOverlayPainter() Gets the current map overlay
TileFactory	getTileFactory() Get the current factory
Rectangle	getViewportBounds() Returns the bounds of the viewport in pixels.
int	getZoom() Gets the current zoom level
boolean	isDesignTime() Indicates whether the component is being used at design time, such as in a visual editor like NetBeans' Matisse
boolean	isDrawTileBorders() Indicates if the tile borders should be drawn.
boolean	isHorizontalWrapped()
boolean	isNegativeYAllowed()
boolean	isRestrictOutsidePanning()
protected void	paintComponent(Graphics g)
void	recenterToAddressLocation() Re-centers the map to have the current address location be at the center of the map, accounting for the map's width and height.
void	setAddressLocation(GeoPosition addressLocation) Gets the current address location of the map
void	setCenter(Point2D center) Sets the new center of the map in pixel coordinates.
void	setCenterPosition(GeoPosition geoPosition) A property indicating the center position of the map
void	setDesignTime(boolean b) Indicate that the component is being used at design time, such as in a visual editor like NetBeans' Matisse
void	setDrawTileBorders(boolean drawTileBorders) Set if the tile borders should be drawn.
void	setHorizontalWrapped(boolean horizontalWrapped)
void	setLoadingImage(Image loadingImage) A property for an image which will be display when an image is still loading.
void	setOverlayPainter(Painter<? super JXMapViewer> overlay) Sets the map overlay.
void	setRestrictOutsidePanning(boolean restrictOutsidePanning)
void	setTileFactory(TileFactory factory) Set the current tile factory (must not be null)
void	setZoom(int zoom) Set the current zoom level
void	zoomToBestFit(Set<GeoPosition> positions, double maxFraction) Zoom and center the map to a best fit around the input GeoPositions.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, 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, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, 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 java.awt.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, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.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, 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, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JXMapViewer

public JXMapViewer()

Create a new JXMapViewer. By default it will use the EmptyTileFactory

Method Detail

paintComponent

protected void paintComponent(Graphics g)

Overrides:

paintComponent in class JComponent

setDesignTime

public void setDesignTime(boolean b)

Indicate that the component is being used at design time, such as in a visual editor like NetBeans' Matisse

Specified by:

setDesignTime in interface DesignMode

Parameters:

b - indicates if the component is being used at design time

isDesignTime

public boolean isDesignTime()

Indicates whether the component is being used at design time, such as in a visual editor like NetBeans' Matisse

Specified by:

isDesignTime in interface DesignMode

Returns:

boolean indicating if the component is being used at design time

drawMapTiles

protected void drawMapTiles(Graphics g,
                int zoom,
                Rectangle viewportBounds)

Draw the map tiles. This method is for implementation use only.

Parameters:

g - Graphics

zoom - zoom level to draw at

viewportBounds - the bounds to draw within

setOverlayPainter

public void setOverlayPainter(Painter<? super JXMapViewer> overlay)

Sets the map overlay. This is a Painter which will paint on top of the map. It can be used to draw waypoints, lines, or static overlays like text messages.

Parameters:

overlay - the map overlay to use

getOverlayPainter

public Painter<? super JXMapViewer> getOverlayPainter()

Gets the current map overlay

Returns:

the current map overlay

getViewportBounds

public Rectangle getViewportBounds()

Returns the bounds of the viewport in pixels. This can be used to transform points into the world bitmap coordinate space.

Returns:

the bounds in pixels of the "view" of this map

setZoom

public void setZoom(int zoom)

Set the current zoom level

Parameters:

zoom - the new zoom level

getZoom

public int getZoom()

Gets the current zoom level

Returns:

the current zoom level

getAddressLocation

public GeoPosition getAddressLocation()

Gets the current address location of the map. This property does not change when the user pans the map. This property is bound.

Returns:

the current map location (address)

setAddressLocation

public void setAddressLocation(GeoPosition addressLocation)

Gets the current address location of the map

Parameters:

addressLocation - the new address location

recenterToAddressLocation

public void recenterToAddressLocation()

Re-centers the map to have the current address location be at the center of the map, accounting for the map's width and height.

isDrawTileBorders

public boolean isDrawTileBorders()

Indicates if the tile borders should be drawn. Mainly used for debugging.

Returns:

the value of this property

setDrawTileBorders

public void setDrawTileBorders(boolean drawTileBorders)

Set if the tile borders should be drawn. Mainly used for debugging.

Parameters:

drawTileBorders - new value of this drawTileBorders

setCenterPosition

public void setCenterPosition(GeoPosition geoPosition)

A property indicating the center position of the map

Parameters:

geoPosition - the new property value

getCenterPosition

public GeoPosition getCenterPosition()

A property indicating the center position of the map

Returns:

the current center position

getTileFactory

public TileFactory getTileFactory()

Get the current factory

Returns:

the current property value

setTileFactory

public void setTileFactory(TileFactory factory)

Set the current tile factory (must not be null)

Parameters:

factory - the new property value

getLoadingImage

public Image getLoadingImage()

A property for an image which will be display when an image is still loading.

Returns:

the current property value

setLoadingImage

public void setLoadingImage(Image loadingImage)

A property for an image which will be display when an image is still loading.

Parameters:

loadingImage - the new property value

getCenter

public Point2D getCenter()

Gets the current pixel center of the map. This point is in the global bitmap coordinate system, not as lat/longs.

Returns:

the current center of the map as a pixel value

setCenter

public void setCenter(Point2D center)

Sets the new center of the map in pixel coordinates.

Parameters:

center - the new center of the map in pixel coordinates

calculateZoomFrom

public void calculateZoomFrom(Set<GeoPosition> positions)

Calculates a zoom level so that all points in the specified set will be visible on screen. This is useful if you have a bunch of points in an area like a city and you want to zoom out so that the entire city and it's points are visible without panning.

Parameters:

positions - A set of GeoPositions to calculate the new zoom from

zoomToBestFit

public void zoomToBestFit(Set<GeoPosition> positions,
                 double maxFraction)

Zoom and center the map to a best fit around the input GeoPositions. Best fit is defined as the most zoomed-in possible view where both the width and height of a bounding box around the positions take up no more than maxFraction of the viewport width or height respectively.

Parameters:

positions - A set of GeoPositions to calculate the new zoom from

maxFraction - the maximum fraction of the viewport that should be covered

isRestrictOutsidePanning

public boolean isRestrictOutsidePanning()

Returns:

true if panning is restricted or not

setRestrictOutsidePanning

public void setRestrictOutsidePanning(boolean restrictOutsidePanning)

Parameters:

restrictOutsidePanning - set if panning is restricted or not

isHorizontalWrapped

public boolean isHorizontalWrapped()

Returns:

true if horizontally wrapped or not

setHorizontalWrapped

public void setHorizontalWrapped(boolean horizontalWrapped)

Parameters:

horizontalWrapped - true if horizontal wrap is enabled

convertGeoPositionToPoint

public Point2D convertGeoPositionToPoint(GeoPosition pos)

Converts the specified GeoPosition to a point in the JXMapViewer's local coordinate space. This method is especially useful when drawing lat/long positions on the map.

Parameters:

pos - a GeoPosition on the map

Returns:

the point in the local coordinate space of the map

convertPointToGeoPosition

public GeoPosition convertPointToGeoPosition(Point2D pt)

Converts the specified Point2D in the JXMapViewer's local coordinate space to a GeoPosition on the map. This method is especially useful for determining the GeoPosition under the mouse cursor.

Parameters:

pt - a point in the local coordinate space of the map

Returns:

the point converted to a GeoPosition

isNegativeYAllowed

public boolean isNegativeYAllowed()

Returns:

isNegativeYAllowed