MapView Class

  • [アーティクル]

Note

Bing Maps SDK for Android and iOS retirement

Bing Maps SDK for Android and iOS is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps SDK for Android and iOS until June 30th, 2025. Enterprise account customers can continue to use Bing Maps SDK for Android and iOS until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps SDK for Android and iOS will need to be updated to use Azure Maps Web SDK by the retirement date that applies to your Bing Maps for Enterprise account type.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

This is the master class for using the Map functionality within maps.

Android

class MapView extends FrameLayout

iOS

@interface MSMapView : UIView

See also: UIView

Constructors

Android

MapView(android.content.Context context, MapRenderMode rasterRenderMode)
MapView(android.content.Context context, android.util.AttributeSet attributeSet, MapRenderMode rasterRenderMode)

Properties

Bounds

Returns the current geo-bounding box bounds of the current view.

See also: GeoboundingBox

Android

GeoboundingBox getBounds()

iOS

@property (nonatomic, readonly) MSGeoboundingBox *mapBounds

BuildingsVisible

Determines whether 3D buildings are rendered on the map.

Android

boolean isBuildingsVisible()
void setBuildingsVisible(boolean visible)

iOS

@property (nonatomic) BOOL buildingsVisible

BusinessLandmarksVisible

Determines whether business landmarks (e.g., restaurants, hotels) are rendered on the map.

Android

boolean isBusinessLandmarksVisible()
void setBusinessLandmarksVisible(boolean visible)

iOS

@property (nonatomic) BOOL businessLandmarksVisible

Camera

Returns the current perspective of the current view of the map. The map's camera settings are updated whenever the view of the map is changed. For example, when updating the Center property or calling the SetScene method.

See also: MapCamera

Android

MapCamera getMapCamera()

iOS

@property (nonatomic, readonly) MSMapCamera *camera

Center

Returns the center of the current view. Keep in mind that in oblique views (where some horizon is shown), the "center" that is returned may not be at the physical center of the control's viewable rectangle.

See also: Geopoint

Android

Geopoint getCenter()

iOS

@property (nonatomic, readonly) MSGeopoint *mapCenter

FullVisibleRegion

Returns the current geopath that is the right-hand traverse of the currently visible area.

See also: Geopath

Android

Geopath getFullVisibleRegion()

iOS

@property (nonatomic, readonly) MSGeopath *fullVisibleRegion

NearVisibleRegion

Returns the current geopath is the right-hand traverse of the approximate area of interest in the current map view.

See also: Geopath

Android

Geopath getNearVisibleRegion()

iOS

@property (nonatomic, readonly) MSGeopath *nearVisibleRegion

Heading

Specifies the heading of the view in degrees where 0 is north, 90 is east, 180 is south, and 270 is west.
Valid values are between 0 and 360.

Android

double getHeading()
void setHeading(float heading)

iOS

@property (nonatomic) CLLocationDirection heading

Language

Specifies the language to be used when rendering locale-specific strings like country/region and city names.
The string can be an ISO 639 two-letter lowercase culture code associated with a language. Example values: "en", "fr", "ja".
The string can optionally be combined with an ISO 3166 two-letter uppercase subculture code associated with a country/region or region (delimited by -). Example values: "en-US", "ko-KR", "ja-JP".

Android

String getLanguage()
void setLanguage(String language)

iOS

@property (nonatomic) NSString *language

CredentialsKey

Specifies the license key authorizing use of the map. Get credentials at www.bingmapsportal.com.

Android

void setCredentialsKey(String credentialsKey)

iOS

@property (nonatomic) IBInspectable NSString *credentialsKey

Layers

Returns developer-added layers of content for the map.
Note that this concept of independent layers doesn't exist on the Windows version of the control. Rather, on Windows, directly add any elements you may have the to the MapElements collection exposed on the control.

See also: MapLayerCollection

Android

MapLayerCollection getLayers()

iOS

@property (nonatomic, readonly) MSMapLayerCollection *layers

RenderMode

Determines whether to render maps using raster tiles or vector data. Raster tiles will generally give a faster framerate at the expense of less readable text.

See also: MapRenderMode

Android

MapRenderMode getMapRenderMode()  
void setMapRenderMode(MapRenderMode mapRenderMode)

iOS

@property (nonatomic) MSMapRenderMode renderMode

Projection

Specifies the projection used to render the map.

See also: MapProjection

Android

MapProjection getMapProjection() 
void setMapProjection(MapProjection mapProjection)

iOS

@property (nonatomic) MSMapProjection projection

MapSize

Specifies the size of rendered map in device-independent pixels.

Note that in Android, class android.graphics.Point is used since android.util.Size is only available in API level 21.

Android

Point getMapSize()  
void setMapSize(Point size)

iOS

@property (nonatomic) CGSize mapSize

Pitch

Specifies the pitch of the camera in degrees, where 0 is looking straight down (minimum) and 90 is looking towards the horizon (maximum). Values outside of this range will cause an exception.
Note that pitch may be limited in some views.

Android

double getPitch()  
void setPitch(double pitch)

iOS

@property (nonatomic) double pitch

Region

Specifies the region of the world to display a map for. Different regions of the world have different views of the world including borders and contested regions.
The string can be an ISO 3166 two-letter uppercase code associated with a country or region. Example values: "US", "CA", "FR".

Android

String getRegion()
void setRegion(String region)

iOS

@property (nonatomic) NSString *region

TransitFeaturesVisible

Determines whether transit features (e.g., transit stops) are rendered on the map.

Android

boolean isTransitFeaturesVisible()
void setTransitFeaturesVisible(boolean visible)

iOS

@property (nonatomic) BOOL transitFeaturesVisible

UserInterfaceOptions

Returns a container class that lets a developer access configuration controls for the map user interface.

See also: MapUserInterfaceOptions

Android

MapUserInterfaceOptions getUserInterfaceOptions()

iOS

@property (nonatomic, readonly) MSMapUserInterfaceOptions *userInterfaceOptions

ViewPadding

Specifies the padding inside the map control in device-independent pixels.

Android

void setViewPadding(ViewPadding viewPadding)
ViewPadding getViewPadding()

@Deprecated
void setViewPadding(double left, double top, double right, double bottom)

See also: ViewPadding iOS

@property (nonatomic) UIEdgeInsets viewPadding

See also: UIEdgeInsets

ZoomLevel

Returns the zoom level of the current view.

Android

double getZoomLevel()

iOS

@property (nonatomic, readonly) double zoomLevel

StyleSheet

Specifies the style sheet that defines the style of the map, such as Road Light, Aerial, or other styles.

See also: MapStyleSheet

Android

MapStyleSheet getMapStyleSheet()
void setMapStyleSheet(MapStyleSheet mapStyleSheet)

iOS

@property (nonatomic) MSMapStyleSheet *styleSheet

UserLocation

Returns an instance of the MapUserLocation class to access the user location API.

See also: MapUserLocation

Android

MapUserLocation getUserLocation()

iOS

@property(nonatomic, readonly) MSMapUserLocation* userLocation

Lifecycle methods (Android only)

You must override lifecycle methods in parent activity or fragment, and call respective MapView methods listed below.

See also: Understand the Activity Lifecycle

OnCreate

Map handler for Create event.

See also:

void onCreate(@Nullable Bundle savedInstanceState)

OnStart

Map handler for Start event. Starts the map, creating rendering resources as necessary.

See also:

void onStart()

OnResume

Map handler for Resume event.

See also:

void onResume()

OnPause

Map handler for Pause event.

See also:

void onPause()

OnSaveInstanceState

Map handler for Save Instance State event.

See also:

void onSaveInstanceState(Bundle outState)

OnStop

Map handler for Stop event. Suspends the map, freeing up resources as necessary.

See also:

void onStop()

OnDestroy

Map handler for Destroy event. Disposes the map, releasing all resources.

See also:

void onDestroy()

OnLowMemory

Map handler for Low Memory event.

See also:

void onLowMemory()

Methods

SetBackgroundColor

The background color of the map that is rendered if there is nothing else to render. As soon as map tiles are available to render the background color is controlled by the active MapStyleSheet instead.

Android

void setBackgroundColor(int color)

iOS

- (void)setMapBackgroundColor:(UIColor *)color

CancelAnimation

Cancels the active animation, if running. If an animation is not running, this method does nothing.

Android

void cancelAnimation()

iOS

- (void)cancelAnimation

CaptureImage

Begins an asynchronous operation to capture a screenshot of the MapView.

Android

void beginCaptureImage(CaptureScreenShotListener listener)

See also: CaptureScreenshotListener

iOS

- (void)beginCaptureImageWithCompletionCallback:(MSMapDidCaptureImageCallback)callback

See also: MSMapDidCaptureImageCallback

FindMapElementsAtOffset

Returns the MapElements that are near a Point offset on the map. This API can be used to implement hit testing of MapElements. For example, on a Tapped event, it can be used to return the closest MapIcon and then that MapIcon's flyout can be shown.

Android

LinkedList<MapElement> findMapElementsAtOffset(Point offset)

iOS

- (NSSet<MSMapElement *> *)findMapElementsAtOffset:(CGPoint)offset

IsLocationInView

Returns whether the given location is visible in the map view.

Android

boolean isLocationInView(Geopoint location)

iOS

- (BOOL)doesViewContainLocation:(MSGeopoint *)location

LocationFromOffset

Converts a point relative to the map view to a geographic location, with an option to select a desired altitude reference system. Note that the return value can be null: for instance, a point in the sky will fail to return a location.

Android

These methods operate with screen pixels.

@Nullable Geopoint getLocationFromOffset(Point offset)
@Nullable Geopoint getLocationFromOffset(Point offset, AltitudeReferenceSystem desiredAltitudeReferenceSystem)

iOS

These methods operate with device-independent points.

- (BOOL)tryToConvertOffset:(CGPoint)offset 
              intoLocation:(MSGeopoint * _Nullable * _Nonnull)location  
- (BOOL)tryToConvertOffset:(CGPoint)offset 
    usingAltitudeReference:(MSAltitudeReferenceSystem)altitudeReferenceSystem 
              intoLocation:(MSGeopoint * _Nullable * _Nonnull)location

OffsetFromLocation

Converts a geographic location to a point on the map (pixel offset). Note that the return value can be null, for instance, locations that are not in view will fail to return an offset.

Android

@Nullable Point getOffsetFromLocation(Geopoint location)

iOS

- (BOOL)tryToConvertLocation:(MSGeopoint *)location intoOffset:(CGPoint *)offset

Rotate

Rotates the map by the specified number of degrees.

Android

void rotate(double degrees)

iOS

- (void)rotateWithDegrees:(CLLocationDirection)degrees

RotateTo

Performs a rotate operation to a particular point. rotateTo(0) will put the MapView with north up.

Android

void rotateTo(double angleInDegrees)

iOS

- (void)rotateToDegrees:(CLLocationDirection)degrees

BeginRotate

Performs a rotate operation and invokes the callback when complete.

Android

void beginRotate(double degrees, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginRotateWithDegrees:(CLLocationDirection)degrees completionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

BeginRotateTo

Perform a rotate operation to a particular point and invokes the callback when complete. beginRotateTo(0) will put the MapView with north up.

Android

void beginRotateTo(double angle, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginRotateToDegrees:(CLLocationDirection)degrees withCompletionCallback:(MSMapDidChangeSceneCallback)callback;

See also: MSMapDidChangeSceneCallback

SetMapStyleSheet

DEPRECATED
Use the StyleSheet property instead.

Sets the style sheet that defines the style of the map, such as Road Light, Aerial, or other styles.

See also: MapStyleSheet

Android

void setMapStyleSheet(MapStyleSheet mapStyleSheet)

iOS

- (void)setStyleSheet:(MSMapStyleSheet*)mapStyleSheet;

SetScene

Sets the scene of the map based on the animation provided.

See also:

Android

void setScene(MapScene scene, MapAnimationKind kind)

iOS

- (void)setScene:(MSMapScene *)scene withAnimationKind:(MSMapAnimationKind)kind

BeginSetScene

Sets the scene of the map based on the animation provided. When the scene has finished changing, the provided callback is invoked.

See also:

Android

void beginSetScene(MapScene scene, MapAnimationKind kind, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginSetScene:(MSMapScene *)scene withAnimationKind:(MSMapAnimationKind)kind withCompletionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

StartContinuousPan

Performs a continuous pan operation.

Android

void startContinuousPan(double horizontalDeviceIndependentPixelsPerSecond, double verticalDeviceIndependentPixelsPerSecond)

iOS

- (void)startContinuousPanWithHorizontalPointsPerSecond:(double)horizontalPointsPerSecond verticalPointsPerSecond:(double)verticalPointsPerSecond

StartContinuousRotate

Starts a continuous rotate operation.

Android

void startContinuousRotate(double rateInDegreesPerSecond)

iOS

- (void)startContinuousRotateWithDegreesPerSecond:(double)degreesPerSecond

StartContinuousTilt

Performs a continuous tilt operation. Call stopContinuousTilt to stop an in-progress tilt.

Android

void startContinuousTilt(double rateInDegreesPerSecond)

iOS

- (void)startContinuousTiltWithDegreesPerSecond:(double)degreesPerSecond

StartContinuousZoom

Performs an ongoing zoom operation.

Android

void startContinuousZoom(double rateOfChangePerSecond)

iOS

- (void)startContinuousZoomWithZoomLevelsPerSecond:(double)zoomLevelsPerSecond

StopContinuousPan

Stops a continuous pan operation.

Android

void stopContinuousPan()

iOS

- (void)stopContinuousPan

StopContinuousRotate

Stops a previously started rotate operation

Android

void stopContinuousRotate()

iOS

- (void)stopContinuousRotate

StopContinuousTilt

Stops an in-progress tilt operation.

Android

void stopContinuousTilt()

iOS

- (void)stopContinuousTilt

StopContinuousZoom

Stops a continuous zoom operation.

Android

void stopContinuousZoom()

iOS

- (void)stopContinuousZoom

Tilt

Performs an operation to tilt the map's camera from its current position. Valid values are between -90 and 90. Invalid values will be clamped.

Android

void tilt(double degrees)

iOS

- (void)tiltWithDegrees:(double)degrees

BeginTilt

Performs an operation to tilt the map's camera from its current position and invokes the callback when complete. Valid values are between -90 and 90. Invalid values will be clamped.

Android

void beginTilt(double degrees, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginTiltWithDegrees:(double)degrees completionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

TiltTo

Performs a tilt operation to a particular point. tiltTo(0) to have the map face nadir. Valid values are between 0 and 90. Invalid values will be clamped.

Android

void tiltTo(double degrees)

iOS

- (void)tiltToDegrees:(double)degrees

BeginTiltTo

Performs a tiltTo operation and invokes the callback when complete. Valid values are between 0 and 90. Invalid values will be clamped.

Android

void beginTiltTo(double degrees, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginTiltToDegrees:(double)degrees withCompletionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

CanTiltDown

Returns true if tilting down (away from nadir) is possible.

Android

boolean canTiltDown()

iOS

- (BOOL)canTiltDown

CanTiltUp

Returns true if tilting up (towards nadir) is possible.

Android

boolean canTiltUp()

iOS

- (BOOL)canTiltUp

ZoomIn

Performs a zoom in operation, equivalent to double tapping on the map.

Note that this void is also repeatable, such that if called multiple times in rapid order (e.g., the user repeatedly presses the zoom in button), the resulting operation is still smooth.

Android

void zoomIn()

iOS

- (void)zoomIn

ZoomOut

Performs a zoom out operation, equivalent to clicking the zoom out button on the map. Note that this method is also repeatable, such that if called multiple times in rapid order (e.g., the user repeatedly presses the zoom out button), the resulting operation is still smooth.

Android

void zoomOut()

iOS

- (void)zoomOut

ZoomTo

Performs a zoom operation to the specified zoom level.

Android

void zoomTo(double zoomLevel)

iOS

- (void)zoomToLevel:(double)zoomLevel

BeginZoomIn

Performs a zoom in operation, equivalent to double tapping on the map, and invokes the provided callback when the zoom is complete.

Android

void beginZoomIn(@Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginZoomInWithCompletionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

BeginZoomOut

Performs a zoom out operation, equivalent to double tapping on the map, and invokes the provided callback when the zoom is complete.

Android

void beginZoomOut(@Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginZoomOutWithCompletionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

BeginZoomTo

Performs a zoom operation to the specified zoom level and invokes the provided callback when the zoom is complete.

Android

void beginZoomTo(double zoomLevel, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginZoomToLevel:(double)level, withCompletionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

CanZoomIn

Returns true if calling zoomIn will affect camera.

Android

boolean canZoomIn()

iOS

- (BOOL)canZoomIn

CanZoomOut

Returns true if calling zoomOut will affect camera.

Android

boolean canZoomOut()

iOS

- (BOOL)canZoomOut

Pan

Perform a pan operation from the current location.

Android

void pan(double horizontalDeviceIndependentPixels, double verticalDeviceIndependentPixels)

iOS

- (void)panWithHorizontalPoints:(double)horizontalPoints verticalPoints:(double)verticalPoints

BeginPan

Perform a pan operation from the current location, and invokes the provided callback when the pan is complete.

Android

void beginPan(double horizontalDeviceIndependentPixels, double verticalDeviceIndependentPixels, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

-(void)beginPanWithHorizontalPoints:(double)horizontalPoints verticalPoints:(double)verticalPoints completionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

PanTo

Perform a pan operation from the current location to the specified location.

Android

void panTo(Geopoint location)

iOS

- (void)panToLocation:(MSGeopoint *)location

BeginPanTo

Perform a pan operation from the current location to the specified location and invokes the provided callback when the pan is complete.

Android

void beginPanTo(Geopoint location, @Nullable OnMapSceneCompletedListener listener)

See also: OnMapSceneCompletedListener

iOS

- (void)beginPanToLocation:(MSGeopoint *)location withCompletionCallback:(MSMapDidChangeSceneCallback)callback

See also: MSMapDidChangeSceneCallback

Events

CameraChanged

Fired when the camera location changed.

Android

void addOnMapCameraChangedListener(OnMapCameraChangedListener listener)
void removeOnMapCameraChangedListener(OnMapCameraChangedListener listener)

See also: OnMapCameraChangedListener

iOS

- (MSMapHandlerId)addCameraDidChangeHandler:(MSMapCameraDidChangeHandler)handler
- (BOOL)removeCameraDidChangeHandler:(MSMapHandlerId)handlerId

See also: MSMapCameraDidChangeHandler

CameraChanging

Fired when the camera location is changing. This event is fired frequently and it is adviced to instead listen to cameraChanged and even then throttle the events and wait until the map is idle so as not to run code too frequently.

Android

void addOnMapCameraChangingListener(OnMapCameraChangingListener listener)
void removeOnMapCameraChangingListener(OnMapCameraChangingListener listener)

See also: OnMapCameraChangingListener

iOS

- (MSMapHandlerId)addCameraWillChangeHandler:(MSMapCameraWillChangeHandler)handler
- (BOOL)removeCameraWillChangeHandler:(MSMapHandlerId)handlerId

See also: MSMapCameraWillChangeHandler

DoubleTapped

Fired when the map is double tapped by the user.

Android

The Position value of this event's arguments is in screen pixels.

void addOnMapDoubleTappedListener(OnMapDoubleTappedListener listener)
void removeOnMapDoubleTappedListener(OnMapDoubleTappedListener listener)

See also: OnMapDoubleTappedListener

iOS

The Position value of this event's arguments is in device-independent points.

- (MSMapHandlerId)addUserDidDoubleTapHandler:(MSMapUserDidDoubleTapHandler)handler
- (BOOL)removeUserDidDoubleTapHandler:(MSMapHandlerId)handlerId

See also: MSMapUserDidDoubleTapHandler

Holding

Fired when finger is held on the map by the user.

Android

The Position value of this event's arguments is in screen pixels.

void addOnMapHoldingListener(OnMapHoldingListener listener)
void removeOnMapHoldingListener(OnMapHoldingListener listener)

See also: OnMapHoldingListener

iOS

The Position value of this event's arguments is in device-independent points.

- (MSMapHandlerId)addUserIsHoldingHandler:(MSMapUserIsHoldingHandler)handler
- (BOOL)removeUserIsHoldingHandler:(MSMapHandlerId)handlerId

See also: MSMapUserIsHoldingHandler

LoadingStatusChanged

Fired when the loading status of the map has changed.

See also: MapLoadingStatus

Android

void addOnMapLoadingStatusChangedListener(OnMapLoadingStatusChangedListener listener)
void removeOnMapLoadingStatusChangedListener(OnMapLoadingStatusChangedListener listener)

See also: MapLoadingStatusChangedListener

iOS

- (MSMapHandlerId)addLoadingStatusDidChangeHandler:(MSMapLoadingStatusDidChangeHandler)handler
- (BOOL)removeLoadingStatusDidChangeHandler:(MSMapHandlerId)handlerId

See also: MSMapLoadingStatusDidChangeHandler

Tapped

Fired when the map is tapped by the user.

Android

The Position value of this event's arguments is in screen pixels.

void addOnMapTappedListener(OnMapTappedListener listener)
void removeOnMapTappedListener(OnMapTappedListener listener)

See also: OnMapTappedListener

iOS

The Position value of this event's arguments is in device-independent points.

- (MSMapHandlerId)addUserDidTapHandler:(MSMapUserDidTapHandler)handler
- (BOOL)removeUserDidTapHandler:(MSMapHandlerId)handlerId

See also: MSMapUserDidTapHandler

Accessibility

MapView is accessible, supporting narrated scenarios as well as keyboard navigation.
Currently, it exposes the following accessibility elements:

  1. Map view itself, narrated as a description of the current view.
  2. User map elements, potentially interactive.
  3. Toolbar elements, interactive.

See also: MapElement - Accessibility