Split out Android examples to separate documentation site (#2978)
This commit is contained in:
Bart Louwers
@@ -1,3 +0,0 @@
|
||||
# MapLibre Native for Android
|
||||
|
||||
MapLibre Native for Android is a library for embedding interactive map views with scalable, customizable vector maps onto Android devices.
|
||||
@@ -1,88 +0,0 @@
|
||||
# Annotation: Marker
|
||||
|
||||
This guide will show you how to add Markers in the map.
|
||||
|
||||
`Annotation` is an overlay on top of a Map. In package
|
||||
`org.maplibre.android.annotations`, it has the following subclasses:
|
||||
1. [Marker]
|
||||
2. [Polyline]
|
||||
3. [Polygon]
|
||||
|
||||
A Marker shows an icon image at a geographical location. By default, marker uses
|
||||
a [provided image] as its icon.
|
||||
|
||||
![marker image]
|
||||
|
||||
Or, the icon can be customized using [IconFactory] to generate an
|
||||
[Icon] using a provided image.
|
||||
|
||||
For more customization, please read the documentation about [MarkerOptions].
|
||||
|
||||
In this showcase, we continue the code from the [Quickstart],
|
||||
rename Activity into `JsonApiActivity`,
|
||||
and pull the GeoJSON data from a free and public API.
|
||||
Then add markers to the map with GeoJSON:
|
||||
|
||||
1. In your module Gradle file (usually `<project>/<app-module>/build.gradle`), add
|
||||
`okhttp` to simplify code for making HTTP requests.
|
||||
|
||||
```gradle
|
||||
dependencies {
|
||||
...
|
||||
implementation 'com.squareup.okhttp3:okhttp:4.10.0'
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
2. Sync your Android project the with Gradle files.
|
||||
|
||||
3. In `JsonApiActivity` we add a new variable for `MapboxMap`.
|
||||
It is used to add annotations to the map instance.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt:top}}
|
||||
```
|
||||
|
||||
4. Call `mapview.getMapSync()` in order to get a `MapboxMap` object.
|
||||
After `maplibreMap` is assigned, call the `getEarthQuakeDataFromUSGS()` method
|
||||
to make a HTTP request and transform data into the map annotations.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt:mapAsync}}
|
||||
```
|
||||
|
||||
5. Define a function `getEarthQuakeDataFromUSGS()` to fetch GeoJSON data from a public API.
|
||||
If we successfully get the response, call `addMarkersToMap()` on the UI thread.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt:getEarthquakes}}
|
||||
```
|
||||
|
||||
6. Now it is time to add markers into the map.
|
||||
- In the `addMarkersToMap()` method, we define two types of bitmap for the marker icon.
|
||||
- For each feature in the GeoJSON, add a marker with a snippet about earthquake details.
|
||||
- If the magnitude of an earthquake is bigger than 6.0, we use the red icon. Otherwise, we use the blue one.
|
||||
- Finally, move the camera to the bounds of the newly added markers
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt:addMarkers}}
|
||||
```
|
||||
|
||||
7. Here is the final result. For the full contents of `JsonApiActivity`, please visit source code of our [Test App].
|
||||
|
||||
<div style="align: center">
|
||||
<img src="https://github.com/maplibre/maplibre-native/assets/19887090/00446249-9b19-4a48-8a46-00d4c5a2f981" alt="Screenshot with the map in demotile style">
|
||||
</div>
|
||||
|
||||
[Marker]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.annotations/-marker/index.html
|
||||
[provided image]: https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroid/src/main/res/drawable-xxxhdpi/maplibre_marker_icon_default.png
|
||||
[Polyline]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.annotations/-polyline/index.html
|
||||
[Polygon]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.annotations/-polygon/index.html
|
||||
[marker image]: https://raw.githubusercontent.com/maplibre/maplibre-native/main/test/fixtures/sprites/default_marker.png
|
||||
[IconFactory]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.annotations/-icon-factory/index.html
|
||||
[Icon]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.annotations/-icon/index.html
|
||||
[Quickstart]: ./getting-started-guide.md
|
||||
[mvn]: https://mvnrepository.com/artifact/org.maplibre.gl/android-plugin-annotation-v9
|
||||
[Android Developer Documentation]: https://developer.android.com/topic/libraries/architecture/coroutines
|
||||
[MarkerOptions]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.annotations/-marker-options/index.html
|
||||
[Test App]: https://github.com/maplibre/maplibre-native/tree/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt
|
||||
@@ -1,120 +0,0 @@
|
||||
# Quickstart
|
||||
|
||||
<div class="warning">
|
||||
|
||||
In versions prior to the (upcoming) MapLibre Native for Android 11.0 release, you need to use `com.mapbox.mapboxsdk.*` for imports instead of `org.maplibre.android.*`. Classes with `Mapbox` in the name are replaced with `MapLibre`. Details can be found in the [changelog](https://github.com/maplibre/maplibre-native/blob/main/platform/android/CHANGELOG.md).
|
||||
|
||||
</div>
|
||||
|
||||
1. Add bintray Maven repositories to your project-level Gradle file (usually `<project>/<app-module>/build.gradle`).
|
||||
|
||||
```gradle
|
||||
allprojects {
|
||||
repositories {
|
||||
...
|
||||
mavenCentral()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Add the library as a dependency into your module Gradle file (usually `<project>/<app-module>/build.gradle`). Replace `<version>` with the latest MapLibre Native version (e.g.: `org.maplibre.gl:android-sdk:10.0.2`). Visit [https://mvnrepository.com/artifact/org.maplibre.gl/android-sdk](https://mvnrepository.com/artifact/org.maplibre.gl/android-sdk) to view the version history of MapLibre Native for android.
|
||||
|
||||
```gradle
|
||||
dependencies {
|
||||
...
|
||||
implementation 'org.maplibre.gl:android-sdk:<version>'
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
3. Sync your Android project with Gradle files.
|
||||
|
||||
4. Add a `MapView` to your layout XML file (usually `<project>/<app-module>/src/main/res/layout/activity_main.xml`).
|
||||
|
||||
```xml
|
||||
...
|
||||
<org.maplibre.android.maps.MapView
|
||||
android:id="@+id/mapView"
|
||||
android:layout_width="match_parent"
|
||||
android:layout_height="match_parent"
|
||||
/>
|
||||
...
|
||||
```
|
||||
|
||||
5. Initialize the `MapView` in your `MainActivity` file by following the example below:
|
||||
|
||||
```kotlin
|
||||
import androidx.appcompat.app.AppCompatActivity
|
||||
import android.os.Bundle
|
||||
import android.view.LayoutInflater
|
||||
import org.maplibre.android.Maplibre
|
||||
import org.maplibre.android.camera.CameraPosition
|
||||
import org.maplibre.android.geometry.LatLng
|
||||
import org.maplibre.android.maps.MapView
|
||||
import org.maplibre.android.testapp.R
|
||||
|
||||
class MainActivity : AppCompatActivity() {
|
||||
|
||||
// Declare a variable for MapView
|
||||
private lateinit var mapView: MapView
|
||||
|
||||
override fun onCreate(savedInstanceState: Bundle?) {
|
||||
super.onCreate(savedInstanceState)
|
||||
|
||||
// Init MapLibre
|
||||
MapLibre.getInstance(this)
|
||||
|
||||
// Init layout view
|
||||
val inflater = LayoutInflater.from(this)
|
||||
val rootView = inflater.inflate(R.layout.activity_main, null)
|
||||
setContentView(rootView)
|
||||
|
||||
// Init the MapView
|
||||
mapView = rootView.findViewById(R.id.mapView)
|
||||
mapView.getMapAsync { map ->
|
||||
map.setStyle("https://demotiles.maplibre.org/style.json")
|
||||
map.cameraPosition = CameraPosition.Builder().target(LatLng(0.0,0.0)).zoom(1.0).build()
|
||||
}
|
||||
}
|
||||
|
||||
override fun onStart() {
|
||||
super.onStart()
|
||||
mapView.onStart()
|
||||
}
|
||||
|
||||
override fun onResume() {
|
||||
super.onResume()
|
||||
mapView.onResume()
|
||||
}
|
||||
|
||||
override fun onPause() {
|
||||
super.onPause()
|
||||
mapView.onPause()
|
||||
}
|
||||
|
||||
override fun onStop() {
|
||||
super.onStop()
|
||||
mapView.onStop()
|
||||
}
|
||||
|
||||
override fun onLowMemory() {
|
||||
super.onLowMemory()
|
||||
mapView.onLowMemory()
|
||||
}
|
||||
|
||||
override fun onDestroy() {
|
||||
super.onDestroy()
|
||||
mapView.onDestroy()
|
||||
}
|
||||
|
||||
override fun onSaveInstanceState(outState: Bundle) {
|
||||
super.onSaveInstanceState(outState)
|
||||
mapView.onSaveInstanceState(outState)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
6. Build and run the app. If you run the app successfully, a map will be displayed as seen in the screenshot below.
|
||||
<div style="text-align: center;">
|
||||
<img src="https://user-images.githubusercontent.com/32692818/228113379-475e86f5-e3fa-4a36-8b4b-1fcba0f1eb3b.png" alt="Screenshot with the map in demotile style" width="50%" height="50%">
|
||||
</div>
|
||||
@@ -1,100 +0,0 @@
|
||||
# LocationComponent
|
||||
|
||||
This guide will demonstrate how to utilize the [LocationComponent] to represent the user's current location.
|
||||
|
||||
|
||||
1. When implementing the [LocationComponent], the application should request location permissions.
|
||||
|
||||
Declare the need for foreground location in the `AndroidManifest.xml` file.
|
||||
|
||||
For more information, please refer to the [Android Developer Documentation].
|
||||
|
||||
```xml
|
||||
<manifest ... >
|
||||
<!-- Always include this permission -->
|
||||
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
|
||||
|
||||
<!-- Include only if your app benefits from precise location access. -->
|
||||
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
|
||||
</manifest>
|
||||
```
|
||||
|
||||
2. Create a new activity named `BasicLocationPulsingCircleActivity`:
|
||||
- This Activity should implement the `OnMapReadyCallback` interface. The `onMapReady()` method is triggered when the map is ready to be used.
|
||||
- Add a variable `permissionsManager` to manage permissions.
|
||||
- Add a variable `locationComponent` to manage user location.
|
||||
- At the end of the `onCreate()` method, call `checkPermissions(`) to ensure that the application can access the user's location.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/location/BasicLocationPulsingCircleActivity.kt:top}}
|
||||
```
|
||||
|
||||
3. In the `checkPermissions()` method, the [PermissionManager] is used to request location permissions at runtime and handle the callbacks for permission granting or rejection.
|
||||
|
||||
Additionally, you should pass the results of `Activity.onRequestPermissionResult()` to it.
|
||||
|
||||
If the permissions are granted, call `mapView.getMapAsync(this)` to register the activity as a listener for onMapReady event.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/location/BasicLocationPulsingCircleActivity.kt:permission}}
|
||||
```
|
||||
|
||||
4. In the `onMapReady()` method, first set the style and then handle the user's location using the [LocationComponent].
|
||||
|
||||
To configure the [LocationComponent], developers should use [LocationComponentOptions].
|
||||
|
||||
In this demonstration, we create an instance of this class.
|
||||
|
||||
In this method:
|
||||
- Use the annotation `@SuppressLint("MissingPermission")` to suppress warnings related to missing location access permissions.
|
||||
- In `setStyle(),` you can utilize other public and token-free styles like [demotiles] instead of the [predefined styles].
|
||||
- For the builder of [LocationComponentOptions], use `pulseEnabled(true)` to enable the pulse animation, which enhances awareness of the user's location.
|
||||
- Use method `buildLocationComponentActivationOptions()` to set [LocationComponentActivationOptions], then activate `locatinoComponent` with it.
|
||||
- To apply options, make sure you call `activateLocationComponent()` of `locationComponent`. You can also set `locationComponent`'s various properties like `isLocationComponentEnabled` , `cameraMode` , etc...
|
||||
- `CameraMode.TRACKING`[^1] means that when the user's location is updated, the camera will reposition accordingly.
|
||||
- `locationComponent!!.forceLocationUpdate(lastLocation)` updates the the user's last known location.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/location/BasicLocationPulsingCircleActivity.kt:onMapReady}}
|
||||
```
|
||||
|
||||
5. [LocationComponentActivationOptions] is used to hold the style, [LocationComponentOptions] and other locating behaviors.
|
||||
- It can also be used to configure how to obtain the current location, such as [LocationEngine] and intervals.
|
||||
- In this demonstration, it sets 750ms as the fastest interval for location updates, providing high accuracy location results (but with higher power consumption).
|
||||
- For more information, please visit the [documentation page][LocationComponentActivationOptions].
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/location/BasicLocationPulsingCircleActivity.kt:LocationComponentActivationOptions}}
|
||||
```
|
||||
|
||||
6. For further customization, you can also utilize the `foregroundTintColor()` and `pulseColor()` methods on the [LocationComponentOptions] builder:
|
||||
|
||||
```kotlin
|
||||
val locationComponentOptions =
|
||||
LocationComponentOptions.builder(this@BasicLocationPulsingCircleActivity)
|
||||
.pulseEnabled(true)
|
||||
.pulseColor(Color.RED) // Set color of pulse
|
||||
.foregroundTintColor(Color.BLACK) // Set color of user location
|
||||
.build()
|
||||
```
|
||||
|
||||
7. Here is the final results with different color configurations. For the complete content of this demo, please refer to the source code of the [Test App] [^2].
|
||||
|
||||
|
||||
|
||||
|
||||
[^1]: A variety of [camera modes] determine how the camera will track the user location.
|
||||
They provide the right context to your users at the correct time.
|
||||
[^2]: Menu items to manage user location icon are used in the [Test App], too.
|
||||
|
||||
[LocationComponent]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location/-location-component/index.html
|
||||
[Android Developer Documentation]: https://developer.android.com/training/location/permissions
|
||||
[onMapReadyCallback]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.maps/-on-map-ready-callback/index.html
|
||||
[PermissionManager]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location.permissions/-permissions-manager/index.html
|
||||
[LocationComponentOptions]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location/-location-component-options/index.html
|
||||
[demotiles]: https://demotiles.maplibre.org/style.json
|
||||
[predefined styles]: https://github.com/maplibre/maplibre-native/tree/main/src/mbgl/util/tile_server_options.cpp
|
||||
[LocationComponentActivationOptions]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location/-location-component-activation-options/index.html
|
||||
[LocationEngine]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location.engine/-location-engine/index.html
|
||||
[Test APP]: https://github.com/maplibre/maplibre-native/tree/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/location/BasicLocationPulsingCircleActivity.kt
|
||||
[camera modes]: https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.location.modes/-camera-mode/index.html
|
||||
@@ -1,85 +0,0 @@
|
||||
# MapLibre Configuration
|
||||
|
||||
This guide will explain various ways to create a map.
|
||||
|
||||
When working with maps, you likely want to configure the `MapView`.
|
||||
|
||||
There are several ways to build a `MapView`:
|
||||
|
||||
1. Using existing XML namespace tags for`MapView` in the layout.
|
||||
2. Creating `MapLibreMapOptions` and passing builder function values into the `MapView`.
|
||||
3. Creating a `SupportMapFragment` with the help of `MapLibreMapOptions`.
|
||||
|
||||
Before diving into `MapView` configurations, let's understand the capabilities of both XML namespaces and `MapLibreMapOptions`.
|
||||
|
||||
Here are some common configurations you can set:
|
||||
- Map base URI
|
||||
- Camera settings
|
||||
- Zoom level
|
||||
- Pitch
|
||||
- Gestures
|
||||
- Compass
|
||||
- Logo
|
||||
- Attribution
|
||||
- Placement of the above elements on the map and more
|
||||
|
||||
We will explore how to achieve these configurations in XML layout and programmatically in Activity code, step by step.
|
||||
|
||||
### `MapView` Configuration with an XML layout
|
||||
|
||||
To configure `MapView` within an XML layout, you need to use the right namespace and provide the necessary data in the layout file.
|
||||
|
||||
```xml
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml}}
|
||||
```
|
||||
|
||||
This can be found in [`activity_map_options_xml.xml`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_fragment.xml).
|
||||
|
||||
You can assign any other existing values to the `maplibre...` tags. Then, you only need to create `MapView` and `MapLibreMap` objects with a simple setup in the Activity.
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt}}
|
||||
```
|
||||
|
||||
This can be found in [`MapOptionsXmlActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt).
|
||||
|
||||
### `MapView` configuration with `MapLibreMapOptions`
|
||||
|
||||
Here we don't have to create MapView from XML since we want to create it programmatically.
|
||||
```xml
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml}}
|
||||
```
|
||||
|
||||
This can be found in [`activity_map_options_runtime.xml`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_runtime.xml).
|
||||
|
||||
A `MapLibreMapOptions` object must be created and passed to the MapView constructor. All setup is done in the Activity code:
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt}}
|
||||
```
|
||||
|
||||
This can be found in [`MapOptionsRuntimeActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt).
|
||||
|
||||
Finally you will see a result similar to this:
|
||||
|
||||
<div style="text-align: center">
|
||||
<img src="https://github.com/user-attachments/assets/dd85f496-3e6f-4788-933e-4ec3d5999935" alt="Screenshot with the MapLibreMapOptions">
|
||||
</div>
|
||||
|
||||
For the full contents of `MapOptionsRuntimeActivity` and `MapOptionsXmlActivity`, please take a look at the source code of [MapLibreAndroidTestApp](https://github.com/maplibre/maplibre-native/tree/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options).
|
||||
|
||||
You can read more about `MapLibreMapOptions` in the [Android API documentation](https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.maps/-map-libre-map-options/index.html?query=open%20class%20MapLibreMapOptions%20:%20Parcelable).
|
||||
|
||||
### `SupportMapFragment` with the help of `MapLibreMapOptions`.
|
||||
|
||||
If you are using MapFragment in your project, it is also easy to provide initial values to the `newInstance()` static method of `SupportMapFragment`, which requires a `MapLibreMapOptions` parameter.
|
||||
|
||||
Let's see how this can be done in a sample activity:
|
||||
|
||||
```kotlin
|
||||
{{#include ../../../../platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/fragment/SupportMapFragmentActivity.kt}}
|
||||
```
|
||||
|
||||
You can also find the full contents of `SupportMapFragmentActivity` in the [MapLibreAndroidTestApp](https://github.com/maplibre/maplibre-native/tree/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/fragment/SupportMapFragmentActivity.kt).
|
||||
|
||||
To learn more about `SupportMapFragment`, please visit the [Android API documentation](https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.maps/-support-map-fragment/index.html?query=open%20class%20SupportMapFragment%20:%20Fragment,%20OnMapReadyCallback).
|
||||
Reference in New Issue
Block a user