com.ls.widgets.map
Class MapWidget

java.lang.Object
  extended by View
      extended by com.ls.widgets.map.MapWidget
All Implemented Interfaces:
MapLocationListener

public class MapWidget
extends View
implements MapLocationListener


Constructor Summary
MapWidget(Bundle bundle, Context context, java.io.File rootMapFolder, int initialZoomLevel)
          Creates instance of map widget.
MapWidget(Bundle bundle, Context context, java.lang.String rootMapFolder, int initialZoomLevel)
          Creates instance of map widget.
MapWidget(Context context, java.io.File rootMapFolder)
          Creates instance of map widget.
MapWidget(Context context, java.io.File rootMapFolder, int initialZoomLevel)
          Creates instance of map widget.
MapWidget(Context context, java.lang.String rootMapFolder)
          Creates instance of map widget.
MapWidget(Context context, java.lang.String rootMapFolder, int initialZoomLevel)
          Creates instance of map widget.
 
Method Summary
 void addMapEventsListener(MapEventsListener listener)
          Adds listener for map events.
 void centerMap()
          Centers the map.
 void centerMapHorizontally()
          Centers the map horizontally
 void clearLayers()
          Removes all graphical object from all layers
 void computeScroll()
           
 MapLayer createLayer(long theLayerId)
          Creates new map layer with a given id.
 OfflineMapConfig getConfig()
          Returns the copy of the map widget's configuration
 GPSConfig getGpsConfig()
          Returns GPSConfig object that will allow you to configure the GPS receiver.
 Layer getLayer(int index)
          Returns map layer by index.
 Layer getLayerById(long id)
          Returns map layer by layer id.
 int getLayerCount()
          Returns total layer count
 MapGraphicsConfig getMapGraphicsConfig()
           
 int getMapHeight()
          Returns height of the map taking current scale into account.
 int getMapWidth()
          Returns width of the map taking current scale into account.
 int getOriginalMapHeight()
          Returns the height of the map on the max zoom level.
 int getOriginalMapWidth()
          Returns the width of the map on the max zoom level.
 float getScale()
          Returns the current scale of the map.
 int getZoomLevel()
          Returns current zoom level of the map.
 void jumpTo(int x, int y)
          Scrolls map to specific location
 void jumpTo(Location location)
          Scrolls the map to specific location without animation.
 void jumpTo(Point location)
          Scrolls the map to specific location.
 void jumpToCurrentLocation()
          Scrolls the map to current location marker without animation.
 void onChangePinVisibility(boolean visible)
           
 boolean onKeyDown(int keyCode, KeyEvent event)
           
 void onMovePinTo(Location location)
           
 boolean onTouchEvent(MotionEvent event)
           
 void removeAllLayers()
          Removes all layers from the map.
 void removeAllMapEventsListeners()
          Removes all map event listeners.
 void removeLayer(long theLayerId)
          Removes layer with the given id from the map.
 void removeMapEventsListener(MapEventsListener listener)
          Removes map event listener from the map.
 void saveState(Bundle bundle)
          Saves mapWidget internal state, that can be restored from onCreate();
 void scrollMapTo(int x, int y)
          Scrolls the map to specific location using scroll animation.
 void scrollMapTo(Location location)
          Scrolls the map to specific location using scroll animation.
 void scrollMapTo(Point location)
          Scrolls the map to specific location using scroll animation.
 void scrollToCurrentLocation()
          Scrolls the map to current location marker using scroll animation.
 void setAnimationEnabled(boolean isEnabled)
          Enables/disables the zoom in/zoom out animations
 void setMaxZoomLevel(int maxZoomLevel)
          The max zoom level the user can zoom in to.
 void setMinZoomLevel(int minZoomLevel)
          Sets the min zoom level the user can zoom out to.
 void setOnDoubleTapListener(OnMapDoubleTapListener listener)
          Sets the listener to handle double tap event.
 void setOnLocationChangedListener(OnLocationChangedListener listener)
          Sets listener for retrieving the location
 void setOnLongClickListener(OnLongClickListener listener)
          Sets the listener to handle long click event.
 void setOnMapLongClickListener(OnMapLongClickListener onMapLongClickListener)
          Sets the listener to handle long click on the map.
 void setOnMapScrolledListener(OnMapScrollListener mapScrollListener)
          Sets scroll listener to the map.
 void setOnMapTilesFinishLoadingListener(OnMapTilesFinishedLoadingListener listener)
          Sets the listener that will be called when all visible tiles has been loaded and displayed.
 void setOnMapTouchListener(OnMapTouchListener mapTouchListener)
          Sets touch listener to the map.
 void setOnTouchListener(OnTouchListener listener)
          Sets the listener to handle touch events
 void setScale(float scale)
          Set's the scale to the map.
 void setShowMyPosition(boolean show)
          Shows current position of the user on the map.
 void setTouchAreaSize(int pixels)
          Sets the size of the touch area when user touches the map.
 void setUseSoftwareZoom(boolean useSoftwareZoom)
          Enables the map to keep zooming in when no more zoom levels left.
 void setZoomButtonsVisible(boolean enabled)
          Enables or disables the standard zoom controls.
 void zoomIn()
          Zooms map in by one zoom level.
 void zoomIn(int pivotX, int pivotY)
           
 void zoomOut()
          Zooms map out by one zoom level.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MapWidget

public MapWidget(Context context,
                 java.lang.String rootMapFolder,
                 int initialZoomLevel)
Creates instance of map widget.

Parameters:
context - - context
rootMapFolder - - folder that contains map resources inside your assets.
initialZoomLevel - - initial zoom level.

MapWidget

public MapWidget(Context context,
                 java.io.File rootMapFolder,
                 int initialZoomLevel)
Creates instance of map widget.

Parameters:
context - - context
rootMapFolder - - instance of File that points to the map resources which are located on the external storage.
initialZoomLevel - - initial zoom level

MapWidget

public MapWidget(Context context,
                 java.lang.String rootMapFolder)
Creates instance of map widget. Zoom level will be set to 10.

Parameters:
context - - Context
rootMapFolder - - folder that contains map resources inside your assets.

MapWidget

public MapWidget(Context context,
                 java.io.File rootMapFolder)
Creates instance of map widget. Zoom level will be set to 10.

Parameters:
context - - Context
rootMapFolder - - instance of File that points to the map resources which are located on the external storage.

MapWidget

public MapWidget(Bundle bundle,
                 Context context,
                 java.io.File rootMapFolder,
                 int initialZoomLevel)
Creates instance of map widget.

Parameters:
bundle - - bundle that were used to save map widget's state.
context - - Context
rootMapFolder - - instance of File that points to the map resources which are located on the external storage.
initialZoomLevel - - zoom level that will be set in case if bundle doesn't contain previously saved state.

MapWidget

public MapWidget(Bundle bundle,
                 Context context,
                 java.lang.String rootMapFolder,
                 int initialZoomLevel)
Creates instance of map widget.

Parameters:
bundle - - bundle that were used to save map widget's state.
context - - Context
rootMapFolder - - folder that contains map resources inside your assets.
initialZoomLevel - - zoom level that will be set in case if bundle doesn't contain previously saved state.
Method Detail

addMapEventsListener

public void addMapEventsListener(MapEventsListener listener)
Adds listener for map events.

Parameters:
listener - - instance of MapEventListener

createLayer

public MapLayer createLayer(long theLayerId)
Creates new map layer with a given id.

Parameters:
theLayerId - - id of the new layer
Returns:
returns instance of the MapLayer or null if error occured.
Throws:
java.lang.IllegalArgumentException - when layer with the given id exists already.

removeLayer

public void removeLayer(long theLayerId)
Removes layer with the given id from the map.

Parameters:
theLayerId - the id of previously created layer.

removeAllLayers

public void removeAllLayers()
Removes all layers from the map.


centerMapHorizontally

public void centerMapHorizontally()
Centers the map horizontally


getLayer

public Layer getLayer(int index)
Returns map layer by index.

Parameters:
index - the index of the layer
Returns:
instance of Layer
Throws:
java.lang.ArrayIndexOutOfBoundsException - when index is out of bounds.

getLayerById

public Layer getLayerById(long id)
Returns map layer by layer id.

Parameters:
id - - layer id
Returns:
instance of Layer

getLayerCount

public int getLayerCount()
Returns total layer count

Returns:
layer count

getMapHeight

public int getMapHeight()
Returns height of the map taking current scale into account.

Returns:
height of the map in pixels.

getMapWidth

public int getMapWidth()
Returns width of the map taking current scale into account.

Returns:
width of the map in pixels.

getOriginalMapHeight

public int getOriginalMapHeight()
Returns the height of the map on the max zoom level.

Returns:
original map height in pixels.

getOriginalMapWidth

public int getOriginalMapWidth()
Returns the width of the map on the max zoom level.

Returns:
original map width in pixels.

getConfig

public OfflineMapConfig getConfig()
Returns the copy of the map widget's configuration

Returns:
instance of OfflineMapConfig class.

getScale

public float getScale()
Returns the current scale of the map.

Returns:
float that represents the scale of the map. 1.0 = max zoom level. 0.5 - map is scaled down to half of it's size.

getZoomLevel

public int getZoomLevel()
Returns current zoom level of the map.

Returns:
current zoom level of the map. Should be greater than 0.

onKeyDown

public boolean onKeyDown(int keyCode,
                         KeyEvent event)

onTouchEvent

public boolean onTouchEvent(MotionEvent event)

removeMapEventsListener

public void removeMapEventsListener(MapEventsListener listener)
Removes map event listener from the map.

Parameters:
listener - instance of the MapEventsListener

removeAllMapEventsListeners

public void removeAllMapEventsListeners()
Removes all map event listeners.


clearLayers

public void clearLayers()
Removes all graphical object from all layers


setOnMapTouchListener

public void setOnMapTouchListener(OnMapTouchListener mapTouchListener)
Sets touch listener to the map.

Parameters:
mapTouchListener - instance of OnMapTouchListener.

setOnMapLongClickListener

public void setOnMapLongClickListener(OnMapLongClickListener onMapLongClickListener)
Sets the listener to handle long click on the map.

Parameters:
onMapLongClickListener - - instance of OnMapLongClickListener. Can be null.

setOnMapTilesFinishLoadingListener

public void setOnMapTilesFinishLoadingListener(OnMapTilesFinishedLoadingListener listener)
Sets the listener that will be called when all visible tiles has been loaded and displayed.

Parameters:
listener - instance of OnMapTilesFinishedLoadingListener or null.

setOnMapScrolledListener

public void setOnMapScrolledListener(OnMapScrollListener mapScrollListener)
Sets scroll listener to the map.

Parameters:
mapScrollListener - instance of OnMapScrollListener.

setOnLocationChangedListener

public void setOnLocationChangedListener(OnLocationChangedListener listener)
Sets listener for retrieving the location

Parameters:
listener - - instance of OnLocationChangedListener. May be null.

setOnLongClickListener

public void setOnLongClickListener(OnLongClickListener listener)
Sets the listener to handle long click event.

Parameters:
listener - instance of OnLongClickListener. Can be null.
See Also:
android.view.View.OnLongClickListener

setOnDoubleTapListener

public void setOnDoubleTapListener(OnMapDoubleTapListener listener)
Sets the listener to handle double tap event.

Parameters:
listener - instance of OnMapDoubleTapListener. Can be null.
See Also:
OnMapDoubleTapListener

setOnTouchListener

public void setOnTouchListener(OnTouchListener listener)
Sets the listener to handle touch events

Parameters:
listener - instance of OnTouchListener
See Also:
android.view.View.OnTouchListener

setZoomButtonsVisible

public void setZoomButtonsVisible(boolean enabled)
Enables or disables the standard zoom controls.

Parameters:
enabled - true in order to make zoom controls visible, otherwise false.

setMinZoomLevel

public void setMinZoomLevel(int minZoomLevel)
Sets the min zoom level the user can zoom out to.

Parameters:
minZoomLevel - int from 0 to count of zoom levels.

setMaxZoomLevel

public void setMaxZoomLevel(int maxZoomLevel)
The max zoom level the user can zoom in to.

Parameters:
maxZoomLevel - int from 0 to max zoom levels.

setScale

public void setScale(float scale)
Set's the scale to the map. Map will be scaled by resizing the existing tiles. Zoom level will be preserved.

Parameters:
scale - scale value. 2.0 means that you want to make map two times bigger.

setUseSoftwareZoom

public void setUseSoftwareZoom(boolean useSoftwareZoom)
Enables the map to keep zooming in when no more zoom levels left. Software scale will be used.

Parameters:
useSoftwareZoom - true if you want to enable software zoom, false otherwise.

setAnimationEnabled

public void setAnimationEnabled(boolean isEnabled)
Enables/disables the zoom in/zoom out animations

Parameters:
isEnabled - true if you want to enable the animations, false otherwise.

setTouchAreaSize

public void setTouchAreaSize(int pixels)
Sets the size of the touch area when user touches the map.

Parameters:
pixels - radius of the touch area in pixels

zoomIn

public void zoomIn()
Zooms map in by one zoom level.


setShowMyPosition

public void setShowMyPosition(boolean show)
Shows current position of the user on the map. You can configure the view of the pointer. See MapWidget.getMapGraphicsConfig() for details. You can configure the GPS receiver by setting configuration parameters before setShowMyPosition is called. See MapWidget.getGPSConfig() for details.

In order to calibrate the map you should add the calibration data to the map.xml. Calibration data consists of two points - top left and bottom right. X and Y is a coordinate of the point in your original map image in pixels. lat and lon is latitude and longitude of the same point in real world.

 For example, your map.xml may look like this:
<Image TileSize="256" Overlap="1" Format="png"> <Size Width="1918" Height="978"/> <CalibrationRect> <Point x="0" y="0" lat="42.924251753870685" lon="-103.99658203125" topLeft="1"/> <Point x="1918" y="978" lat="40.81380923056961" lon="-98.3056640625"/> </CalibrationRect> </Image>

Parameters:
show - - set true in order to show the position marker on the map, false - in order to hide it.
Throws:
java.lang.IllegalStateException - () in case if map is not calibrated.

getMapGraphicsConfig

public MapGraphicsConfig getMapGraphicsConfig()
Returns:
instance of MapGraphicsConfig or null, if map was not configured properly

getGpsConfig

public GPSConfig getGpsConfig()
Returns GPSConfig object that will allow you to configure the GPS receiver.

Returns:
instance of GPSConfig, or null if map configuration file doesn't contain GPS calibration data or file was not found.

zoomIn

public void zoomIn(int pivotX,
                   int pivotY)

zoomOut

public void zoomOut()
Zooms map out by one zoom level.


computeScroll

public void computeScroll()

onMovePinTo

public void onMovePinTo(Location location)
Specified by:
onMovePinTo in interface MapLocationListener

onChangePinVisibility

public void onChangePinVisibility(boolean visible)
Specified by:
onChangePinVisibility in interface MapLocationListener

jumpToCurrentLocation

public void jumpToCurrentLocation()
Scrolls the map to current location marker without animation. Location marker should be visible in order for this method to work.


scrollToCurrentLocation

public void scrollToCurrentLocation()
Scrolls the map to current location marker using scroll animation. Location marker should be visible in order for this method to work.


jumpTo

public void jumpTo(Location location)
Scrolls the map to specific location without animation.

Parameters:
location - - instance of android.location.Location object.
Throws:
java.lang.IllegalStateException - if map was not calibrated. For more details see MapWidget.setShowMyPosition().

jumpTo

public void jumpTo(Point location)
Scrolls the map to specific location.

Parameters:
location - - instance of Point. The coordinates of the point should be set in pixels in map coordinate system.

jumpTo

public void jumpTo(int x,
                   int y)
Scrolls map to specific location

Parameters:
x - - x coordinate in map coordinate system.
y - - y coordinate in map coordinate system.

scrollMapTo

public void scrollMapTo(Location location)
Scrolls the map to specific location using scroll animation.

Parameters:
location - - instance of android.location.Location.
Throws:
java.lang.IllegalStateException - if map is not calibrated. For more details see MapWidget.setShowMyPosition().

scrollMapTo

public void scrollMapTo(Point location)
Scrolls the map to specific location using scroll animation.

Parameters:
location - - instance of android.graphics.Point. Coordinates of the point should be set in pixels in map coordinates.

scrollMapTo

public void scrollMapTo(int x,
                        int y)
Scrolls the map to specific location using scroll animation.

Parameters:
x - - x coordinate of the point in map coordinates.
y - - y coordinate of the point in map coordinates.

saveState

public void saveState(Bundle bundle)
Saves mapWidget internal state, that can be restored from onCreate();

Parameters:
bundle -

centerMap

public void centerMap()
Centers the map.