com.maryanovsky.map.client
Class MapWidget

java.lang.Object
  extended by com.google.gwt.user.client.ui.UIObject
      extended by com.google.gwt.user.client.ui.Widget
          extended by com.google.gwt.user.client.ui.Composite
              extended by com.maryanovsky.map.client.MapWidget
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsRenderable, IsWidget
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.MapAnimation
          The superclass for map-related animations.
 
Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject
UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled
 
Field Summary
static String MAGNIFICATION_PROPERTY_NAME
          The property name for magnification of the map widget.
static String MAP_PROPERTY_NAME
          The property name for the map this widget is displaying.
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.
 
Fields inherited from class com.google.gwt.user.client.ui.UIObject
DEBUG_ID_PREFIX
 
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<? extends Overlay> overlays)
          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 addReadyListener(ReadyListener<MapWidget> listener)
          Adds the specified ReadyListener to be notified when the map widget becomes ready or unready.
 void applyMagnification(boolean animate)
          Applies the current magnification by setting the zoom and location of the map to values closest to those seen by the user.
 void applyMagnification(boolean animate, int roundingDirection)
          Applies the current magnification by setting the zoom and location of the map to values closest to those seen by the user.
 void applyTemporaryOffset()
          Makes the temporary offset permanent and clears it.
 void endCurrentAnimation()
          Ends the currently running animation, if any.
 LatLngBounds getBounds()
          Returns the bounds of the currently displayed area, in geographical coordinates.
 LatLng getCenter()
          Returns the center of the displayed map.
 Pair<Double,PointView> getMagnification()
          Returns the current magnification.
 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.
 HasAllMouseHandlers getMouseEventsSource()
          Returns the source of mouse events for the map widget.
 AbsolutePanel getOverlayPanel()
          Returns the panel into which overlays should be added.
 Collection<Overlay> getOverlays()
          Returns all the overlays.
 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.
 HasAllTouchHandlers getTouchEventsSource()
          Returns the source of touch events for the map widget.
 Widget getUserEventWidget()
          Returns the widget with which event listeners should be registered in order to receive user interaction events from the map 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()
          Deprecated. 
 boolean isGrabCursor()
          Returns whether the map widget will have the grab cursor.
 boolean isLoadTilesDuringTemporaryChanges()
          Returns whether tiles are loaded during temporary changes in the map's location.
 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 coordinates 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<? extends Overlay> overlays)
          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 removeReadyListener(ReadyListener<MapWidget> listener)
          Removes the specified ReadyListener from being notified when the ready state of the map widget 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 setLoadTilesDuringTemporaryChanges(boolean isLoadTilesDuringTemporaryChanges)
          Sets whether tiles are to be loaded during temporary changes in the map's location.
 void setMagnification(double magnification, PointView fixedPoint)
          Sets the magnification of the map while keeping the specified point (in pixels, relative to the view) fixed on the screen.
 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 show(LatLngBounds bounds, boolean animate)
          Displays the specified area, centered at the center of the bounds, using the maximal zoom at which the entire area is visible.
 void startAnimation(MapWidget.MapAnimation 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
claimElement, getWidget, initializeClaimedElement, initWidget, isAttached, onAttach, onBrowserEvent, onDetach, render, render, resolvePotentialElement, setWidget
 
Methods inherited from class com.google.gwt.user.client.ui.Widget
addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, fireEvent, getHandlerCount, getLayoutData, getParent, isOrWasAttached, removeFromParent, setLayoutData, sinkEvents
 
Methods inherited from class com.google.gwt.user.client.ui.UIObject
addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, 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

MAGNIFICATION_PROPERTY_NAME

public static final String MAGNIFICATION_PROPERTY_NAME
The property name for magnification of the map widget.

See Also:
Constant Field Values
Constructor Detail

MapWidget

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

Method Detail

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:


removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)
Removes the specified PropertyChangeListener from being notified when the property with the specified name changes.


addReadyListener

public void addReadyListener(ReadyListener<MapWidget> listener)
Adds the specified ReadyListener to be notified when the map widget becomes ready or unready. The map widget is considered ready when all of the tiles needed to display the current location at the current size have finished loading.


removeReadyListener

public void removeReadyListener(ReadyListener<MapWidget> listener)
Removes the specified ReadyListener from being notified when the ready state of the map widget 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.


getUserEventWidget

public Widget getUserEventWidget()
Returns the widget with which event listeners should be registered in order to receive user interaction events from the map widget. Note that usually you should be using the event sources returned by getMouseEventsSource() and/or getTouchEventsSource() to register listeners. This method exposes the widget to allow registering for events not (yet) supported explicitly.


getMouseEventsSource

public HasAllMouseHandlers getMouseEventsSource()
Returns the source of mouse events for the map widget. The coordinates of the fired mouse events are in this map widget's local coordinate system.


getTouchEventsSource

public HasAllTouchHandlers getTouchEventsSource()
Returns the source of touch events for the map widget. The coordinates of the fired touch events are in this map widget's local coordinate system.


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<? extends Overlay> overlays)
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<? extends Overlay> overlays)
A convenience method for removing a collection of overlays. See removeOverlay(Overlay) for more information.


getOverlays

public Collection<Overlay> getOverlays()
Returns all the overlays. The returned collection is unmodifiable.


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 differ from the getMapLocationModel()'s center due to getTemporaryOffset().


getMapSize

public SizeView getMapSize()
Returns the size of the displayed map, in pixels.


getBounds

public LatLngBounds getBounds()
Returns the bounds of the currently displayed area, in geographical coordinates.


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.


setLoadTilesDuringTemporaryChanges

public void setLoadTilesDuringTemporaryChanges(boolean isLoadTilesDuringTemporaryChanges)
Sets whether tiles are to be loaded during temporary changes in the map's location. Setting this to false can speed up panning and zooming animations on slow devices.


isLoadTilesDuringTemporaryChanges

public boolean isLoadTilesDuringTemporaryChanges()
Returns whether tiles are loaded during temporary changes in the map's location.


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 coordinates 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(MapWidget.MapAnimation 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

@Deprecated
public static boolean isAnimatedZoomSupported()
Deprecated. 

Returns whether animated zoom is supported by the current environment. Since animated zoom is now supported on all browsers, this method is deprecated and always returns true.


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, 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, 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, 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, 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, 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, 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, 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, the zoom will change with a short animation.

show

public void show(LatLngBounds bounds,
                 boolean animate)
Displays the specified area, centered at the center of the bounds, using the maximal zoom at which the entire area is visible.

Parameters:
bounds - The bounds of the area to display.
animate - Whether the transition from the current location should be animated.

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.


setMagnification

public void setMagnification(double magnification,
                             PointView fixedPoint)
Sets the magnification of the map while keeping the specified point (in pixels, relative to the view) fixed on the screen. Note that this is just a visual effect; it does not affect the current zoom or location.


getMagnification

public Pair<Double,PointView> getMagnification()
Returns the current magnification.


applyMagnification

public void applyMagnification(boolean animate,
                               int roundingDirection)
Applies the current magnification by setting the zoom and location of the map to values closest to those seen by the user. The direction in which magnification is rounded to the closest supported zoom is determined by the roundingDirection parameter. A negative value specifies that the zoom should be selected such that its magnification is smaller than the current magnification. A positive value specifies that it should be larger than the current magnification. A value of 0 specifies that it should be rounded to the closest supported zoom, whether up or down.


applyMagnification

public void applyMagnification(boolean animate)
Applies the current magnification by setting the zoom and location of the map to values closest to those seen by the user.


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