Scale bar
The Scale Bar Plugin for Android displays numbers and a line to help visualize how far various map features are from one another at a certain zoom level. The scale bar can be customized with options such as the text color and size, refresh interval, margins, and border width.
View a demo of using the plugin to add and style the scale bar.
Install the Scale Bar Plugin
To start developing an application using the Scale Bar Plugin, you'll need to add the appropriate dependencies inside your build.gradle file. You can find the dependency given below on MavenCentral.
Add the dependency
- Start Android Studio.
- Open up your application's
build.gradle. - Make sure that your project's
minSdkVersionis API 14 or higher. - Under dependencies, add a new build rule for the latest
mapbox-android-plugin-scalebar-v9. - Click the Sync Project with Gradle Files near the toolbar in Studio.
repositories {
mavenCentral()
}
dependencies {
implementation 'com.mapbox.mapboxsdk:mapbox-android-plugin-scalebar-v9:0.5.0'
}
Add the scale bar
Initialize the plugin inside of onStyleLoaded because the Scale Bar Plugin requires the mapboxMap object and the scale bar is rendered on top of the map.
@Override
public void onMapReady(@NonNull MapboxMap mapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
@Override
public void onStyleLoaded(@NonNull Style style) {
ScaleBarPlugin scaleBarPlugin = new ScaleBarPlugin(mapView, mapboxMap);
// Create a ScaleBarOptions object to use the Plugin's default styling
scaleBarPlugin.create(new ScaleBarOptions(this));
}
});
}
override fun onMapReady(mapboxMap: MapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS) { style ->
val scaleBarPlugin = ScaleBarPlugin(mapView!!, mapboxMap)
// Create a ScaleBarOptions object to use the Plugin's default styling
scaleBarPlugin.create(ScaleBarOptions(this))
}
}
Customizing the scale bar
The plugin's ScaleBarOptions provides many options for customizing the look of the scale bar and how the scale bar responds to map interaction. Once you create a ScaleBarOptions object, you can run various styling methods to set your preferences. Once you're done styling the scale bar the way that you'd like, give the ScaleBarOptions object to the ScaleBarPlugin object via the create() method.
@Override
public void onMapReady(@NonNull MapboxMap mapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
@Override
public void onStyleLoaded(@NonNull Style style) {
ScaleBarPlugin scaleBarPlugin = new ScaleBarPlugin(mapView, mapboxMap);
// Set the custom styling via a ScaleBarOptions object
ScaleBarOptions scaleBarOptions = new ScaleBarOptions(this)
.setTextColor(R.color.mapboxRed)
.setTextSize(40f)
.setBarHeight(15f)
.setBorderWidth(5f)
.setMetricUnit(true)
.setRefreshInterval(15)
.setMarginTop(30f)
.setMarginLeft(16f)
.setTextBarMargin(15f)
// Give the plugin the ScaleBarOptions object to style the scale bar
scaleBarPlugin.create(scaleBarOptions);
}
});
}
override fun onMapReady(mapboxMap: MapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS) { style ->
val scaleBarPlugin = ScaleBarPlugin(mapView!!, mapboxMap)
// Set the custom styling via a ScaleBarOptions object
val scaleBarOptions = ScaleBarOptions(this)
scaleBarOptions
.setTextColor(R.color.mapboxRed)
.setTextSize(40f)
.setBarHeight(15f)
.setBorderWidth(5f)
.setMetricUnit(true)
.setRefreshInterval(15)
.setMarginTop(30f)
.setMarginLeft(16f)
.setTextBarMargin(15f)
// Give the plugin the ScaleBarOptions object to style the scale bar
scaleBarPlugin.create(scaleBarOptions)
}
}
Scale bar visibility
The ScaleBarPlugin class has a setEnabled() method to adjust the scale bar's visibility. Pass true as a parameter to make the scale bar visible and false to hide the scale bar. The scale bar is visible by default on scaleBarPlugin.create(), which means that you don't have to use setEnabled() to initially show the scale bar.
// To hide the scale bar
scaleBarPlugin.setEnabled(false);
// To hide the scale bar
scaleBarPlugin.isEnabled = false