com.maryanovsky.map.client
Class MapWidget

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          com.google.gwt.user.client.ui.Composite
              com.maryanovsky.map.client.MapWidget

All Implemented Interfaces:

EventListener

Direct Known Subclasses:

OverviewMapWidget

public class MapWidget
extends Composite

A widget displaying a map and possibly other elements on it, and allows interaction with them. The style name of this widget is "map-MapWidget".

Author:

Maryanovsky Alexander

Nested Class Summary

static class	MapWidget.MapClickAction A ClickAction on the map widget.
static class	MapWidget.MapDragAction A DragAction on the map widget.
static class	MapWidget.MapMoveAction A MoveAction on the map widget.
static class	MapWidget.MapWheelAction A WheelAction on the map widget.

Field Summary

static ClickAction	ANIMATED_PAN_MAP_ACTION A click action which pans the map with animation to the clicked point.
static WheelAction	ANIMATED_ZOOM_ACTION A mouse wheel action which zooms the map in on a scroll-up event and zooms it out on a scroll-down event, with animation, if supported.
static ClickAction	ANIMATED_ZOOM_IN_ACTION A click action which zooms the map in by one zoom and moves it to the clicked point, with animation, if supported.
static DragAction	DRAG_MAP_ACTION A drag action which allows the map to be dragged to a new location.
static String	MAP_PROPERTY_NAME The property name for the map this widget is displaying.
static ClickAction	PAN_MAP_ACTION A click action which pans the map without animation to the clicked point.
static String	SIZE_PROPERTY_NAME The property name for the size of the map widget.
static String	TEMPORARY_OFFSET_PROPERTY_NAME The property name for the temporary offset of the map widget.
static WheelAction	ZOOM_ACTION A mouse wheel action which zooms the map in on a scroll-up event and zooms it out on a scroll-down event.
static ClickAction	ZOOM_IN_ACTION A click action which zooms the map in by one zoom and moves it to the clicked point.

Constructor Summary

MapWidget(MapLocationModel mapLocationModel)
Creates a new MapWidget with the specified location model.

Method Summary

void	addOverlay(Overlay overlay) Adds an overlay to this MapWidget.
void	addOverlays(Collection collection) A convenience method for adding a collection of overlays.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener) Adds the specified PropertyChangeListener to be notified when the property with the specified name changes.
void	applyTemporaryOffset() Makes the temporary offset permanent and clears it.
void	endCurrentAnimation() Ends the currently running animation, if any.
LatLng	getCenter() Returns the center of the displayed map.
Map	getMap() Returns the currently displayed map.
MapLocationModel	getMapLocationModel() Returns the location model of this MapWidget.
SizeView	getMapSize() Returns the size of the displayed map, in pixels.
static MapWidget	getMapWidgetFromActionTarget(Widget target) Returns the MapWidget corresponding to the specified action target widget.
AbsolutePanel	getOverlayPanel() Returns the panel into which overlays should be added.
int	getPanAnimationLength() Returns the length of pan animations, in milliseconds.
PointView	getTemporaryOffset() Returns the temporary offset of the map, in pixels, from its "official", permanent, location.
double	getTileCoverSize() Returns the current size of the tile cover, as a percentage of the size of the widget itself.
UserEventManager	getUserEventManager() Returns the UserEventManager associated with this widget.
AbsolutePanel	getWidgetPanel() Returns the panel into which widgets can be added over the map.
int	getZoomAnimationLength() Returns the length of zoom animations, in milliseconds.
static boolean	isAnimatedZoomSupported() Returns whether animated zoom is supported by the current environment.
boolean	isGrabCursor() Returns whether the map widget will have the grab cursor.
LatLng	localToMap(PointView point) Converts from local (in the widget's coordinate system), pixel coordinates to map coordinates.
Point	mapToLocal(LatLng location) Converts from map to local (in the widget's coordinate system), pixel coordinates.
void	moveTo(LatLng location, boolean animate) Moves the map to center on the specified coordinate, possibly animating the transition.
protected void	onLoad() Invoked when the widget is attached to the DOM.
protected void	onUnload() Invoked when the widget is removed from the DOM.
void	panBy(PointView offset, boolean animate) Pans the map by the specified offset, in pixels, possibly animating the transition.
void	panTo(PointView location, boolean animate) Pans the map to center on the specified point, in widget coordinates, possibly animating the transition.
void	removeOverlay(Overlay overlay) Removes an overlay from this MapWidget.
void	removeOverlays(Collection collection) A convenience method for removing a collection of overlays.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener) Removes the specified PropertyChangeListener from being notified when the property with the specified name changes.
void	resized() Call this method whenever you manually adjust the size of the widget after it has been displayed.
void	setGrabCursor(boolean isGrabCursor) Sets whether the map widget will use the grab cursor.
void	setMap(Map map) Sets the currently displayed map.
void	setPanAnimationLength(int panAnimationLength) Sets the length of pan animations, in milliseconds.
void	setTemporaryOffset(PointView offset) Adds a temporary offset, in pixels, to the "official", permanent, location of the map.
void	setTileCoverSize(double tileCoverSize) Sets the size of the area covered by tiles, relative to the the size of the widget itself.
void	setZoomAnimationLength(int zoomAnimationLength) Sets the length of zoom animations, in milliseconds.
boolean	shouldAnimateTo(LatLng newCenter) Returns whether panning to the specified location should use animation or not.
void	startAnimation(Animation animation) Ends the current animation, if any, and starts a new one.
void	zoomBy(int zoomChange, boolean animate) Zooms in or out by the specified number of zooms, optionally with animation (if supported).
void	zoomByFixPoint(int zoomChange, PointView fixedPoint, boolean animate) Zooms in or out by specified number of zooms, while keeping the specified pixel point (in widget coordinates) fixed on the screen, optionally with animation (if supported).
void	zoomByTargetLocation(int zoomChange, LatLng targetLocation, boolean animate) Zooms in or out by specified number of zooms, while moving the map to the specified location, optionally with animation (if supported)
void	zoomByTargetPoint(int zoomChange, PointView targetPoint, boolean animate) Zooms in or out by specified number of zooms, while moving the map to the specified pixel location (in widget coordinates), optionally with animation (if supported)
void	zoomTo(int zoom, boolean animate) Zooms to the specified zoom, optionally with animation (if supported).
void	zoomToFixPoint(int zoom, PointView fixedPoint, boolean animate) Zooms to the specified zoom, while keeping the specified pixel point (in widget coordinates) fixed on the screen, optionally with animation (if supported).
void	zoomToTargetLocation(int zoom, LatLng targetLocation, boolean animate) Zooms to the specified zoom, while moving the map to the specified location, optionally with animation (if supported).
void	zoomToTargetPoint(int zoom, PointView targetPoint, boolean animate) Zooms to the specified zoom, while moving the map to the specified pixel location (in widget coordinates), optionally with animation (if supported).

Methods inherited from class com.google.gwt.user.client.ui.Composite

getElement, getWidget, initWidget, isAttached, onAttach, onDetach, setWidget

Methods inherited from class com.google.gwt.user.client.ui.Widget

doAttachChildren, doDetachChildren, getParent, onBrowserEvent, removeFromParent, setElement

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, addStyleName, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkEvents, toString, unsinkEvents

Methods inherited from class java.lang.Object

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

Field Detail

MAP_PROPERTY_NAME

public static final String MAP_PROPERTY_NAME

The property name for the map this widget is displaying.

See Also:

Constant Field Values

SIZE_PROPERTY_NAME

public static final String SIZE_PROPERTY_NAME

The property name for the size of the map widget.

See Also:

Constant Field Values

TEMPORARY_OFFSET_PROPERTY_NAME

public static final String TEMPORARY_OFFSET_PROPERTY_NAME

The property name for the temporary offset of the map widget.

See Also:

Constant Field Values

DRAG_MAP_ACTION

public static final DragAction DRAG_MAP_ACTION

A drag action which allows the map to be dragged to a new location.

PAN_MAP_ACTION

public static final ClickAction PAN_MAP_ACTION

A click action which pans the map without animation to the clicked point.

ANIMATED_PAN_MAP_ACTION

public static final ClickAction ANIMATED_PAN_MAP_ACTION

A click action which pans the map with animation to the clicked point.

ZOOM_IN_ACTION

public static final ClickAction ZOOM_IN_ACTION

A click action which zooms the map in by one zoom and moves it to the clicked point.

ANIMATED_ZOOM_IN_ACTION

public static final ClickAction ANIMATED_ZOOM_IN_ACTION

A click action which zooms the map in by one zoom and moves it to the clicked point, with animation, if supported.

ZOOM_ACTION

public static final WheelAction ZOOM_ACTION

A mouse wheel action which zooms the map in on a scroll-up event and zooms it out on a scroll-down event. Following the zoom change, the map location under the mouse cursor remains unmoved.

ANIMATED_ZOOM_ACTION

public static final WheelAction ANIMATED_ZOOM_ACTION

A mouse wheel action which zooms the map in on a scroll-up event and zooms it out on a scroll-down event, with animation, if supported. Following the zoom change (and during the animation), the map location under the mouse cursor remains unmoved.

Constructor Detail

MapWidget

public MapWidget(MapLocationModel mapLocationModel)

Creates a new MapWidget with the specified location model.

Method Detail

getMapWidgetFromActionTarget

public static MapWidget getMapWidgetFromActionTarget(Widget target)

Returns the MapWidget corresponding to the specified action target widget. This method is for the benefit of actions set on the user event manager.

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)

Adds the specified PropertyChangeListener to be notified when the property with the specified name changes. Currently supported properties are:

• MAP_PROPERTY_NAME
• SIZE_PROPERTY_NAME
• TEMPORARY_OFFSET_PROPERTY_NAME

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)

Removes the specified PropertyChangeListener from being notified when the property with the specified name changes.

setMap

public void setMap(Map map)

Sets the currently displayed map.

getMap

public Map getMap()

Returns the currently displayed map.

getMapLocationModel

public MapLocationModel getMapLocationModel()

Returns the location model of this MapWidget.

getUserEventManager

public UserEventManager getUserEventManager()

Returns the UserEventManager associated with this widget. With it, you may set any of the available map (or your own, custom) actions to be performed when some user event occurs.

getWidgetPanel

public AbsolutePanel getWidgetPanel()

Returns the panel into which widgets can be added over the map. Note that the widget panel is not guaranteed to be initially clean, and may contain widgets without which the MapWidget will not function properly. Basically, do not touch anything in it which you have not added yourself.

addOverlay

public void addOverlay(Overlay overlay)

Adds an overlay to this MapWidget. Overlays, unlike widgets, are (logically) positioned relative to the map, and they normally move and change when the map moves or changes zooms.

addOverlays

public void addOverlays(Collection collection)

A convenience method for adding a collection of overlays. See addOverlay(Overlay) for more information.

removeOverlay

public void removeOverlay(Overlay overlay)

Removes an overlay from this MapWidget.

removeOverlays

public void removeOverlays(Collection collection)

A convenience method for removing a collection of overlays. See removeOverlay(Overlay) for more information.

getOverlayPanel

public AbsolutePanel getOverlayPanel()

Returns the panel into which overlays should be added.

getCenter

public LatLng getCenter()

Returns the center of the displayed map. Note that this may differs from the getMapLocationModel()'s center due to getTemporaryOffset().

getMapSize

public SizeView getMapSize()

Returns the size of the displayed map, in pixels.

setGrabCursor

public void setGrabCursor(boolean isGrabCursor)

Sets whether the map widget will use the grab cursor. Note that this may not be supported under all browsers. See UiUtils.setGrabCursor(Widget) and UiUtils.setGrabbingCursor(Widget) for more information.

isGrabCursor

public boolean isGrabCursor()

Returns whether the map widget will have the grab cursor.

setTileCoverSize

public void setTileCoverSize(double tileCoverSize)

Sets the size of the area covered by tiles, relative to the the size of the widget itself. For example, setTileCoverSize(1) would cause the tiles to cover at least the entire area of the widget (actually, slightly more, due to rounding to the tile grid). Normally, however, the tile cover should be larger than the widget, to allow the prefetching of some tiles around the visible ones.

getTileCoverSize

public double getTileCoverSize()

Returns the current size of the tile cover, as a percentage of the size of the widget itself. Note that the actual cover may be slightly larger, because of rounding to the tile grid.

localToMap

public LatLng localToMap(PointView point)

Converts from local (in the widget's coordinate system), pixel coordinates to map coordinates.

mapToLocal

public Point mapToLocal(LatLng location)

Converts from map to local (in the widget's coordinate system), pixel coordinates.

setZoomAnimationLength

public void setZoomAnimationLength(int zoomAnimationLength)

Sets the length of zoom animations, in milliseconds.

getZoomAnimationLength

public int getZoomAnimationLength()

Returns the length of zoom animations, in milliseconds.

setPanAnimationLength

public void setPanAnimationLength(int panAnimationLength)

Sets the length of pan animations, in milliseconds.

getPanAnimationLength

public int getPanAnimationLength()

Returns the length of pan animations, in milliseconds.

shouldAnimateTo

public boolean shouldAnimateTo(LatLng newCenter)

Returns whether panning to the specified location should use animation or not. The current implementation returns whether the current bounds and the resulting bounds intersect.

endCurrentAnimation

public void endCurrentAnimation()

Ends the currently running animation, if any.

startAnimation

public void startAnimation(Animation animation)

Ends the current animation, if any, and starts a new one.

panTo

public void panTo(PointView location,
                  boolean animate)

Pans the map to center on the specified point, in widget coordinates, possibly animating the transition.

panBy

public void panBy(PointView offset,
                  boolean animate)

Pans the map by the specified offset, in pixels, possibly animating the transition.

moveTo

public void moveTo(LatLng location,
                   boolean animate)

Moves the map to center on the specified coordinate, possibly animating the transition.

isAnimatedZoomSupported

public static boolean isAnimatedZoomSupported()

Returns whether animated zoom is supported by the current environment.

zoomByTargetLocation

public void zoomByTargetLocation(int zoomChange,
                                 LatLng targetLocation,
                                 boolean animate)

Zooms in or out by specified number of zooms, while moving the map to the specified location, optionally with animation (if supported)

Parameters:

zoomChange - The number of zooms to change by (use negative values to zoom out). For convenience, if the resulting zoom is illegal, the method zooms to the nearest legal zoom instead.

targetLocation - The location which will be centered at the end of the zoom change.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomToTargetLocation

public void zoomToTargetLocation(int zoom,
                                 LatLng targetLocation,
                                 boolean animate)

Zooms to the specified zoom, while moving the map to the specified location, optionally with animation (if supported).

Parameters:

zoom - The new zoom.

targetLocation - The location which will be centered at the end of the zoom change.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomByTargetPoint

public void zoomByTargetPoint(int zoomChange,
                              PointView targetPoint,
                              boolean animate)

Zooms in or out by specified number of zooms, while moving the map to the specified pixel location (in widget coordinates), optionally with animation (if supported)

Parameters:

zoomChange - The number of zooms to change by (use negative values to zoom out). For convenience, if the resulting zoom is illegal, the method zooms to the nearest legal zoom instead.

targetPoint - The point on the widget (in widget coordinates) which will be centered at the end of the zoom change.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomToTargetPoint

public void zoomToTargetPoint(int zoom,
                              PointView targetPoint,
                              boolean animate)

Zooms to the specified zoom, while moving the map to the specified pixel location (in widget coordinates), optionally with animation (if supported).

Parameters:

zoom - The new zoom.

targetPoint - The point on the widget (in widget coordinates) which will be centered at the end of the zoom change.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomByFixPoint

public void zoomByFixPoint(int zoomChange,
                           PointView fixedPoint,
                           boolean animate)

Zooms in or out by specified number of zooms, while keeping the specified pixel point (in widget coordinates) fixed on the screen, optionally with animation (if supported).

Parameters:

zoomChange - The number of zooms to change by (use negative values to zoom out). For convenience, if the resulting zoom is illegal, the method zooms to the nearest legal zoom instead.

fixedPoint - The point on the widget (in widget coordinates) which will remain unmoved on the screen during and after the zoom change.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomToFixPoint

public void zoomToFixPoint(int zoom,
                           PointView fixedPoint,
                           boolean animate)

Zooms to the specified zoom, while keeping the specified pixel point (in widget coordinates) fixed on the screen, optionally with animation (if supported).

Parameters:

zoom - The new zoom.

fixedPoint - The point on the widget (in widget coordinates) which will remain unmoved on the screen during and after the zoom change.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomBy

public void zoomBy(int zoomChange,
                   boolean animate)

Zooms in or out by the specified number of zooms, optionally with animation (if supported).

Parameters:

zoomChange - The number of zooms to change by (use negative values to zoom out). For convenience, if the resulting zoom is illegal, the method zooms to the nearest legal zoom instead.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

zoomTo

public void zoomTo(int zoom,
                   boolean animate)

Zooms to the specified zoom, optionally with animation (if supported).

Parameters:

zoom - The new zoom.

animate - If true, and animated zoom is supported (see isAnimatedZoomSupported()), the zoom will change with a short animation.

resized

public void resized()

Call this method whenever you manually adjust the size of the widget after it has been displayed. This is necessary because there is currently no way to detect such size changes. Note that this method should also be called when the border, margin or padding change, because they may affect the size of the map.

setTemporaryOffset

public void setTemporaryOffset(PointView offset)

Adds a temporary offset, in pixels, to the "official", permanent, location of the map.

getTemporaryOffset

public PointView getTemporaryOffset()

Returns the temporary offset of the map, in pixels, from its "official", permanent, location.

applyTemporaryOffset

public void applyTemporaryOffset()

Makes the temporary offset permanent and clears it.

onLoad

protected void onLoad()

Invoked when the widget is attached to the DOM. Causes the tiles to be displayed.

Overrides:

onLoad in class Widget

onUnload

protected void onUnload()

Invoked when the widget is removed from the DOM.

Overrides:

onUnload in class Widget