public final class Map
extends java.lang.Object
Map
object represents a virtual model of the world. When embedded in a
MapFragment
, or
MapView
, Map
objects can be used to show
maps, add/remove map objects, and enable user interactions.Modifier and Type | Class and Description |
---|---|
static class |
Map.Animation
Represents values that describe animation types for on-screen map movements.
|
static interface |
Map.InfoBubbleAdapter
Interface for implementing custom info bubbles for
MapMarker objects. |
static interface |
Map.OnSchemeChangedListener
Listener for
Map scheme changed events. |
static interface |
Map.OnTransformListener
Listener for
Map transform events. |
static class |
Map.PixelResult
Result class for conversion of a GeoCoordinate to screen pixel coordinates.
|
static class |
Map.Scheme
Represents a collection of schemes that the
Map class supports. |
Modifier and Type | Field and Description |
---|---|
static float |
MOVE_PRESERVE_ORIENTATION
A valid orientation value that lies outside the minimum and maximum supported tilt range,
used to indicate that the current orientation should be preserved.
|
static float |
MOVE_PRESERVE_TILT
A valid value indicating that the tilt is to be preserved when calling compound
Map
transform operations. |
static double |
MOVE_PRESERVE_ZOOM_LEVEL
A valid zoom level value that lies outside the range of
getMinZoomLevel() and
getMaxZoomLevel() , used to indicate that the current zoom level should be preserved. |
Constructor and Description |
---|
Map() |
Modifier and Type | Method and Description |
---|---|
boolean |
addMapObject(MapObject object)
Adds a
MapObject to this Map . |
boolean |
addMapObjects(java.util.List<MapObject> objects)
|
boolean |
addRasterTileSource(MapRasterTileSource source)
Adds a user-defined
MapRasterTileSource to this Map . |
void |
addSchemeChangedListener(Map.OnSchemeChangedListener listener)
Adds a
Map.OnSchemeChangedListener to listen for map scheme change events. |
void |
addTransformListener(Map.OnTransformListener listener)
Adds a
Map.OnTransformListener to this Map to listen for map transform events. |
GeoBoundingBox |
getBoundingBox()
Returns the current visible map area as a
GeoBoundingBox . |
GeoCoordinate |
getCenter()
Returns the
GeoCoordinate location at the current center of this Map . |
int |
getHeight()
Returns the current height of this
Map , in number of pixels. |
java.lang.String |
getMapDisplayLanguage()
Get the language which the Map is set to render
|
java.lang.String |
getMapScheme()
Returns the current scheme for the
Map . |
java.util.List<java.lang.String> |
getMapSchemes()
Returns a list containing all supported schemes for the
Map . |
java.lang.String |
getMapSecondaryDisplayLanguage()
Get the secondary language which the Map is set to render
|
double |
getMaxZoomLevel()
Returns the highest valid zoom level for
Map , representing the closest view near the
street-level |
double |
getMinZoomLevel()
Returns the lowest valid zoom level for
Map , representing the most distant view away
from street-level. |
PositionIndicator |
getPositionIndicator()
Returns the
PositionIndicator instance
that renders the current position with a marker. |
double |
getScaleFromZoomLevel(double level)
Returns a map scale value based on the specified zoom level.
|
java.util.List<ViewObject> |
getSelectedObjects(android.graphics.PointF p)
Returns the list of selectable
ViewObject
instances which are located at the specified screen pixel coordinates. |
java.util.List<ViewObject> |
getSelectedObjects(ViewRect rect)
Returns the list of selectable
ViewObject
objects which are within a specified ViewRect . |
android.graphics.PointF |
getTransformCenter()
Returns the current center coordinate for
Map transformations such as zooming and
rotation. |
int |
getWidth()
Returns the current width of this
Map , in number of pixels. |
double |
getZoomLevel()
Returns the current zoom level, which will be within a range between
getMinZoomLevel() and getMaxZoomLevel() . |
void |
pan(android.graphics.PointF from,
android.graphics.PointF to)
Moves the map from one specified screen pixel coordinates to another in a linear motion.
|
java.util.List<GeoCoordinate> |
pixelToGeo(java.util.List<android.graphics.PointF> points)
Converts and returns a list of
GeoCoordinate objects from a <List> of screen pixel coordinates. |
GeoCoordinate |
pixelToGeo(android.graphics.PointF point)
Converts and returns
GeoCoordinate from
screen pixel coordinates. |
Map.PixelResult |
projectToPixel(GeoCoordinate coordinate)
Converts and returns a
PixelResult that represents screen pixel coordinates from a
GeoCoordinate . |
java.util.List<Map.PixelResult> |
projectToPixel(java.util.List<GeoCoordinate> coordinates)
Converts and returns a list of
Map.PixelResult elements that represent screen pixel
coordinates from a <List> of GeoCoordinate objects. |
boolean |
removeMapObject(MapObject object)
Removes a
MapObject from this Map . |
boolean |
removeMapObjects(java.util.List<MapObject> objects)
|
boolean |
removeRasterTileSource(MapRasterTileSource source)
Removes a user-defined
MapRasterTileSource from this Map . |
void |
removeSchemeChangedListener(Map.OnSchemeChangedListener listener)
Removes an existing
Map.OnSchemeChangedListener . |
void |
removeTransformListener(Map.OnTransformListener listener)
Removes an existing
Map.OnTransformListener from this Map . |
void |
setCenter(GeoCoordinate point,
Map.Animation animation)
|
void |
setCenter(GeoCoordinate point,
Map.Animation animation,
double level,
float orientation,
float tilt)
Moves the center of this
Map to a specific
GeoCoordinate , while simultaneously setting
a zoom level (a fraction within the range of minimum and maximum levels), orientation (from 0
degrees to 360 degrees), and tilt (within the range of minimum and maximum tilt angles). |
void |
setCenter(android.graphics.PointF newCenter,
Map.Animation animation,
double zoomLevel,
float orientation,
float tilt)
Centers the map at the specified screen pixel coordinates.
|
void |
setInfoBubbleAdapter(Map.InfoBubbleAdapter adapter)
Sets the custom info bubble adapter for this map.
|
boolean |
setMapDisplayLanguage(java.util.Locale language)
Set the map display language using a locale.
|
Map |
setMapScheme(java.lang.String scheme)
Sets a scheme for the
Map to the specified <String> value. |
boolean |
setMapSecondaryDisplayLanguage(java.util.Locale language)
Set the map secondary display language using a locale.
|
Map |
setTransformCenter(android.graphics.PointF center)
Sets a center coordinate for
Map transformations such as zooming and rotation. |
boolean |
setUseSystemLanguage()
Set the map display language using the system default locale.
|
Map |
setZoomLevel(double level)
Sets a zoom level for the
Map to a fraction that is within the range of minimum and
maximum zoom levels. |
void |
setZoomLevel(double level,
Map.Animation animation)
Sets a zoom level for the
Map to a fraction that is within the range of minimum and
maximum zoom levels. |
void |
setZoomLevel(double level,
android.graphics.PointF focus,
Map.Animation animation)
Sets a zoom level for the
Map to a fraction that is within the range of minimum and
maximum zoom levels while keeping the specified screen coordinate at the same Geographical
Location. |
void |
zoomTo(GeoBoundingBox geoRect,
int width,
int height,
Map.Animation animation,
float orientation)
Moves this
Map instance and changes its zoom level to show the specified
GeoBoundingBox within the specified pixel
dimensions around the transform center. |
void |
zoomTo(GeoBoundingBox geoRect,
Map.Animation animation,
float orientation)
Moves this
Map instance's map center and changes the zoom level to show the specified
GeoBoundingBox at the given orientation. |
public static final double MOVE_PRESERVE_ZOOM_LEVEL
getMinZoomLevel()
and
getMaxZoomLevel()
, used to indicate that the current zoom level should be preserved.
Pass this value to preserve the zoom level when calling compound Map
transform
operations.public static final float MOVE_PRESERVE_ORIENTATION
Map
transform operations.public static final float MOVE_PRESERVE_TILT
Map
transform operations.public int getWidth()
Map
, in number of pixels.public int getHeight()
Map
, in number of pixels.public void setCenter(GeoCoordinate point, Map.Animation animation, double level, float orientation, float tilt)
Map
to a specific
GeoCoordinate
, while simultaneously setting
a zoom level (a fraction within the range of minimum and maximum levels), orientation (from 0
degrees to 360 degrees), and tilt (within the range of minimum and maximum tilt angles). If
you wish to keep the current zoom level, orientation, or tilt after setting a new center,
pass one or more of the following values as the relevant parameter:
MOVE_PRESERVE_ZOOM_LEVEL
to keep the current zoom levelMOVE_PRESERVE_ORIENTATION
to keep the current orientationMOVE_PRESERVE_TILT
to keep the current tile
Note: it is unlikely that you would pass all three of the special
MOVE_PRESERVE_ZOOM_LEVEL
, MOVE_PRESERVE_ORIENTATION
and
MOVE_PRESERVE_TILT
parameters when calling this method (it would make more sense to
call setCenter(GeoCoordinate, Animation)
). More likely, you would use one or two of
the special parameters (for example, change the orientation and tilt along with the center
coordinate while keeping the current zoom level).
point
- A GeoCoordinate
representing the new centeranimation
- A Map.Animation
to illustrate the transformationlevel
- Desired zoom level of the newly-centered Map
(pass
MOVE_PRESERVE_ZOOM_LEVEL
to keep the current level)orientation
- Desired orientation of the newly-centered Map
(pass
MOVE_PRESERVE_ORIENTATION
to keep the current orientation)tilt
- Desired tilt angle of the newly-centered Map
(pass
MOVE_PRESERVE_TILT
to keep the current tilt)java.lang.UnsupportedOperationException
- If orientation angle is not set to MOVE_PRESERVE_ORIENTATION or tilt is not
set to MOVE_PRESERVE_TILT.setCenter(GeoCoordinate, Animation)
,
getMaxZoomLevel()
,
getMinZoomLevel()
public void setCenter(GeoCoordinate point, Map.Animation animation)
point
- A GeoCoordinate
representing the new centeranimation
- An Animation
to illustrate the transformationsetCenter(GeoCoordinate, Animation, double, float, float)
public void setCenter(android.graphics.PointF newCenter, Map.Animation animation, double zoomLevel, float orientation, float tilt)
newCenter
- A PointF
representing the screen pixel coordinates to set as map center.animation
- An Animation
to illustrate the transformationzoomLevel
- Desired zoom level of the newly-centered Map
. Use
MOVE_PRESERVE_ZOOM_LEVEL
to keep the current zoom level.orientation
- Desired orientation of the newly-centered Map
. Use
MOVE_PRESERVE_ORIENTATION
to keep the current orientation angle.tilt
- Desired tilt angle of the newly-centered Map
. Use
MOVE_PRESERVE_TILT
to keep the current tilt angle.java.lang.UnsupportedOperationException
- if orientation angle is not set to MOVE_PRESERVE_ORIENTATION or tilt is not
set to MOVE_PRESERVE_TILT.setCenter(GeoCoordinate, Animation, double, float, float)
public Map setTransformCenter(android.graphics.PointF center)
Map
transformations such as zooming and rotation.
Transformations performed after calling this method will be based on this new center
coordinate. The transform center may be different than the Map
center.center
- A <PointF>
representing the center used for transformationsMap
public android.graphics.PointF getTransformCenter()
Map
transformations such as zooming and
rotation. The transform center may be different than the Map
center.<PointF>
representing the current center used for transformationspublic void zoomTo(GeoBoundingBox geoRect, Map.Animation animation, float orientation)
Map
instance's map center and changes the zoom level to show the specified
GeoBoundingBox
at the given orientation.
Do not call this method before this map instance is initialized. If you call this method
while this map is uninitialized (either getWidth()
or getHeight()
returns
0), it will throw a RuntimeException
. Please note the effects of this method will
apply on Map
slightly after the method invocation.
geoRect
- A GeoBoundingBox
to show after the transformationanimation
- An Animation
to illustrate the transformationorientation
- Desired orientation of the Map
(Use MOVE_PRESERVE_ORIENTATION
to
keep the current orientation)java.lang.UnsupportedOperationException
- If orientation angle is not set to MOVE_PRESERVE_ORIENTATION.public void zoomTo(GeoBoundingBox geoRect, int width, int height, Map.Animation animation, float orientation)
Map
instance and changes its zoom level to show the specified
GeoBoundingBox
within the specified pixel
dimensions around the transform center.
Do not call this method before this map instance is initialized. If you call this method
while this map is uninitialized (either getWidth()
or getHeight()
returns
0), it will throw a <RuntimeException>
. Please note the effects of this method will
apply on Map
slightly after the method invocation.
geoRect
- A GeoBoundingBox
to show after the transformationwidth
- The width, in number of pixels, of the bounding area around the transform center,
which the geoRect
will fit into.height
- The height, in number of pixels, of the bounding area around the transform center,
which the geoRect
will fit into.animation
- An Animation
to illustrate the transformationorientation
- Desired orientation of the Map
(pass MOVE_PRESERVE_ORIENTATION
to
keep the current orientation)java.lang.UnsupportedOperationException
- If orientation angle is not set to MOVE_PRESERVE_ORIENTATION.setTransformCenter(PointF)
public void pan(android.graphics.PointF from, android.graphics.PointF to)
from
- A <PointF>
representing the screen pixel coordinates to pan the map from.to
- A <PointF>
representing the screen pixel coordinates to pan the map to.public double getMaxZoomLevel()
Map
, representing the closest view near the
street-levelpublic double getMinZoomLevel()
Map
, representing the most distant view away
from street-level.public Map setZoomLevel(double level)
Map
to a fraction that is within the range of minimum and
maximum zoom levels. No animation will be used to illustrate the transformation.
Legal values are the range between getMinZoomLevel()
and getMaxZoomLevel()
,
inclusive.
If this method is called before map animation has finished (for example, if you had called
setCenter(GeoCoordinate, Animation)
), the existing animation may be stopped and the
map will proceed directly to change the zoom level. Consider using other methods that combine
multiple actions to avoid unintentionally canceling map animations. For example, use
setCenter(GeoCoordinate, Map.Animation, double, float, float)
.
Note: The zoom level is only precise to three decimal places due to numerical operations performed internally when rendering the map.
level
- Desired fractional zoom levelMap
.setZoomLevel(double, Animation)
,
setZoomLevel(double, PointF, Animation)
,
getMinZoomLevel()
,
getMaxZoomLevel()
public void setZoomLevel(double level, Map.Animation animation)
Map
to a fraction that is within the range of minimum and
maximum zoom levels.
Legal values are the range between getMinZoomLevel()
and getMaxZoomLevel()
inclusive.
If this method is called before map animation is finished (for example, if you had called
setCenter(GeoCoordinate, Animation)
), the existing animation may be stopped and the
map will proceed directly to change the zoom level. Consider using other methods that combine
multiple actions to avoid unintentionally canceling map animations. For example, use
setCenter(GeoCoordinate, Animation, double, float, float)
.
Note: The zoom level is only precise to three decimal places due to numerical operations performed internally when rendering the map.
level
- Desired fractional zoom levelanimation
- An Animation
to illustrate the transformationsetZoomLevel(double)
,
setZoomLevel(double, PointF, Animation)
,
getMinZoomLevel()
,
getMaxZoomLevel()
public void setZoomLevel(double level, android.graphics.PointF focus, Map.Animation animation)
Map
to a fraction that is within the range of minimum and
maximum zoom levels while keeping the specified screen coordinate at the same Geographical
Location. Concretely, the GeoCoordinate
of
the specified <PointF>
is the same before and after the transformation.
Legal values are the range between getMinZoomLevel()
and getMaxZoomLevel()
inclusive.
For the purposes of calculating the focus GeoCoordinate
, the tilt of the map is
considered to be 0. The actual map tilt will not change.
Note: do not call this method before setting the map is initialized. If you call this method
while either getWidth()
or getHeight()
returns 0 it will throw a
RuntimeException
.
Note: The zoom level is only precise to three decimal places due to numerical operations performed internally when rendering the map.
level
- Desired fractional zoom levelfocus
- A PointF
to keep fixed, in pixel coordinates.animation
- An Animation
to illustrate the transformationsetZoomLevel(double)
,
setZoomLevel(double, Animation)
,
getMinZoomLevel()
,
getMaxZoomLevel()
public double getZoomLevel()
getMinZoomLevel()
and getMaxZoomLevel()
. The zoom level is only precise to
three decimal places due to numerical operations performed internally when rendering the map.public double getScaleFromZoomLevel(double level)
level
- The zoom level to be translated to a map scale.level
. Units are in geo centimeters per screen
inchpublic java.util.List<java.lang.String> getMapSchemes()
Map
.Map.Scheme
,
getMapScheme()
,
setMapScheme(String)
public java.lang.String getMapScheme()
Map
.Map.Scheme
,
getMapSchemes()
public Map setMapScheme(java.lang.String scheme)
Map
to the specified <String>
value.scheme
- The desired scheme from getMapSchemes()
.Map
.java.security.AccessControlException
- If the required permission is missing.Map.Scheme
,
getMapSchemes()
public GeoCoordinate getCenter()
GeoCoordinate
location at the current center of this Map
.public GeoCoordinate pixelToGeo(android.graphics.PointF point)
GeoCoordinate
from
screen pixel coordinates.
This method returns null
if the conversion fails. (For example, if the coordinate is
not a valid value.)
point
- The screen pixel coordinates to convertGeoCoordinate
representing the map location. null
if the conversion
fails.pixelToGeo(List)
public java.util.List<GeoCoordinate> pixelToGeo(java.util.List<android.graphics.PointF> points)
GeoCoordinate
objects from a <List>
of screen pixel coordinates.
This method returns one or more list elements as null
if the conversion of the
corresponding pixel coordinates fails.
points
- A <List>
of screen pixel coordinates to convertGeoCoordinate
or null
elements.pixelToGeo(PointF)
public Map.PixelResult projectToPixel(GeoCoordinate coordinate)
PixelResult
that represents screen pixel coordinates from a
GeoCoordinate
. This method is converts a
GeoCoordinate
from world space to screen space.coordinate
- A GeoCoordinate
to convertPixelResult
representing screen pixel coordinates and operation success
code. Check PixelResult#getError()
to check the success of the conversion.projectToPixel(List<GeoCoordinate>)
public java.util.List<Map.PixelResult> projectToPixel(java.util.List<GeoCoordinate> coordinates)
Map.PixelResult
elements that represent screen pixel
coordinates from a <List>
of GeoCoordinate
objects.
This method returns one or more list elements as null
if the conversion of the
corresponding GeoCoordinate
instances fails.
coordinates
- A List
of GeoCoordinate
objects to convertPixelResult
results. Check PixelResult#getError()
to
check the success of each conversion.projectToPixel(GeoCoordinate)
public GeoBoundingBox getBoundingBox()
GeoBoundingBox
.
Note that a bounding box is always rectangular, and its sides are always parallel to latitude
and longitude. If the map is rotated when this method is called (for example, if the
orientation is 10 degrees east of true-north), the returned bounding box will be a
circumscribed rectangle that is larger than the visible map area. Similarly, when the map is
tilted (for example, if the map is tilted by 45 degrees), the visible map area represents a
trapezoidal area in the world. Calling getBoundingBox()
will then return a larger
circumscribed rectangle that contains this trapezoid area.
The bounding box may be invalid when this method is called at low zoom levels, as the map area does not fill the screen.
GeoBoundingBox
containing the visible map area.public PositionIndicator getPositionIndicator()
PositionIndicator
instance
that renders the current position with a marker. The position indicator should be used with
PositioningManager
.PositionIndicator
public boolean addMapObject(MapObject object)
MapObject
to this Map
.object
- A MapObject
to addMapObject
was added successfully, false otherwisejava.lang.NullPointerException
- If object is null.addMapObjects(List<MapObject>)
,
removeMapObject(MapObject)
public boolean addMapObjects(java.util.List<MapObject> objects)
objects
- A <List>
of MapObject
objects to addMapObject
s in the <List>
were added successfully,
false otherwisejava.lang.NullPointerException
- If objects is null.addMapObject(MapObject)
,
removeMapObjects(List<MapObjects>)
public boolean removeMapObject(MapObject object)
MapObject
from this Map
.object
- A MapObject
to removeMapObject
was removed successfully, false otherwiseremoveMapObjects(List<MapObject>)
public boolean removeMapObjects(java.util.List<MapObject> objects)
objects
- A List
of MapObject
objects to removeMapObject
s in the List
were removed successfully,
false otherwiseremoveMapObject(MapObject)
public java.util.List<ViewObject> getSelectedObjects(android.graphics.PointF p)
ViewObject
instances which are located at the specified screen pixel coordinates.p
- Screen pixel coordinate to check for ViewObject
.ViewObject
objects at the pixel coordinate. If no object exists
at p
, returns an empty list.public java.util.List<ViewObject> getSelectedObjects(ViewRect rect)
ViewObject
objects which are within a specified ViewRect
.rect
- A ViewRect
with selected ViewObject
objectsViewObject
objects within the ViewRect
. If no object
exists within rect
, returns an empty list.public void addTransformListener(Map.OnTransformListener listener)
Map.OnTransformListener
to this Map
to listen for map transform events.listener
- A Map.OnTransformListener
to add to the Map
removeTransformListener(OnTransformListener)
public void removeTransformListener(Map.OnTransformListener listener)
Map.OnTransformListener
from this Map
.listener
- A Map.OnTransformListener
to remove from the Map
public void addSchemeChangedListener(Map.OnSchemeChangedListener listener)
Map.OnSchemeChangedListener
to listen for map scheme change events.listener
- A Map.OnSchemeChangedListener
to add to the Map
removeTransformListener(OnTransformListener)
public void removeSchemeChangedListener(Map.OnSchemeChangedListener listener)
Map.OnSchemeChangedListener
.listener
- A Map.OnSchemeChangedListener
to remove from the Map
public void setInfoBubbleAdapter(Map.InfoBubbleAdapter adapter)
adapter
- A custom implementation for the info bubble.MapMarker.showInfoBubble()
public boolean addRasterTileSource(MapRasterTileSource source)
MapRasterTileSource
to this Map
.source
- A MapRasterTileSource
representing a user-defined raster tile sourceremoveRasterTileSource(MapRasterTileSource)
public boolean removeRasterTileSource(MapRasterTileSource source)
MapRasterTileSource
from this Map
.source
- A MapRasterTileSource
representing a user-defined raster tile sourcepublic boolean setUseSystemLanguage()
public boolean setMapDisplayLanguage(java.util.Locale language)
When this method is called, it will override the device's current locale until the device's locale is changed. This language change does not affect other features like search.
For a full list of supported display languages, see the list for the "lg" parameter in the Map Tile API Developer's Guide.
language
- The language locale as described in
http://developer.android.com/reference/java/util/Locale.htm..public boolean setMapSecondaryDisplayLanguage(java.util.Locale language)
null
will cause the display of secondary language to be disabled.
Setting a secondary display language will cause the language to be displayed below the primary language for some map labels (e.g. countries).
language
- The language locale as described in
http://developer.android.com/reference/java/util/Locale.htm.. or null
to disable display of secondary language.setMapDisplayLanguage(Locale)
public java.lang.String getMapDisplayLanguage()
public java.lang.String getMapSecondaryDisplayLanguage()