From c57bb55704d934fc684a18740c9ecd9cba1ac736 Mon Sep 17 00:00:00 2001 From: Dilshodbek Date: Tue, 30 Jul 2024 02:50:06 +0500 Subject: [PATCH] Feature/documentation maplibre map options (#2646) Co-authored-by: Bart Louwers --- docs/mdbook/src/SUMMARY.md | 1 + docs/mdbook/src/android/map-options-guide.md | 85 ++++++++++++++++ .../src/main/AndroidManifest.xml | 60 ++++++----- .../options/MapOptionsRuntimeActivity.kt | 99 +++++++++++++++++++ .../activity/options/MapOptionsXmlActivity.kt | 67 +++++++++++++ .../layout/activity_map_options_runtime.xml | 7 ++ .../res/layout/activity_map_options_xml.xml | 36 +++++++ .../src/main/res/values/categories.xml | 1 + .../src/main/res/values/descriptions.xml | 2 + .../src/main/res/values/titles.xml | 2 + 10 files changed, 337 insertions(+), 23 deletions(-) create mode 100644 docs/mdbook/src/android/map-options-guide.md create mode 100644 platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt create mode 100644 platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt create mode 100644 platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_runtime.xml create mode 100644 platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml diff --git a/docs/mdbook/src/SUMMARY.md b/docs/mdbook/src/SUMMARY.md index b868854fd..dd8a871a8 100644 --- a/docs/mdbook/src/SUMMARY.md +++ b/docs/mdbook/src/SUMMARY.md @@ -14,6 +14,7 @@ - [Quickstart](./android/getting-started-guide.md) - [Annotation: Marker](./android/annotation-guide.md) - [Location Component](./android/location-component-guide.md) + - [MapOptions Guide](./android/map-options-guide.md) - [Profiling applications that use MapLibre Native](./profiling/README.md) - [Tracy profiling](./profiling/tracy-profiling.md) diff --git a/docs/mdbook/src/android/map-options-guide.md b/docs/mdbook/src/android/map-options-guide.md new file mode 100644 index 000000000..c3fdc5b16 --- /dev/null +++ b/docs/mdbook/src/android/map-options-guide.md @@ -0,0 +1,85 @@ +# 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: + +
+ Screenshot with the MapLibreMapOptions +
+ +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). diff --git a/platform/android/MapLibreAndroidTestApp/src/main/AndroidManifest.xml b/platform/android/MapLibreAndroidTestApp/src/main/AndroidManifest.xml index 2506de637..4ac146116 100644 --- a/platform/android/MapLibreAndroidTestApp/src/main/AndroidManifest.xml +++ b/platform/android/MapLibreAndroidTestApp/src/main/AndroidManifest.xml @@ -1,6 +1,6 @@ - + @@ -14,7 +14,6 @@ android:roundIcon="@drawable/ic_launcher_round" android:supportsRtl="true" android:theme="@style/AppTheme"> - - - + - - - + - - - + - - - + - - + @@ -1226,26 +1217,49 @@ android:screenOrientation="portrait" /> - + android:screenOrientation="landscape" /> - - + android:value="pk.eyJ1IjoiYmxzdGFnaW5nIiwiYSI6ImNpdDF3OHpoaTAwMDcyeXA5Y3Z0Nmk2dzEifQ.0IfB7v5Qbm2MGVYt8Kb8fg" /> - + + + + + + + + + + \ No newline at end of file diff --git a/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt b/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt new file mode 100644 index 000000000..c7439f458 --- /dev/null +++ b/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsRuntimeActivity.kt @@ -0,0 +1,99 @@ +package org.maplibre.android.testapp.activity.options + +import android.os.Bundle +import android.view.View +import android.view.ViewGroup +import androidx.appcompat.app.AppCompatActivity +import org.maplibre.android.camera.CameraPosition +import org.maplibre.android.geometry.LatLng +import org.maplibre.android.maps.MapLibreMap +import org.maplibre.android.maps.MapLibreMapOptions +import org.maplibre.android.maps.MapView +import org.maplibre.android.maps.OnMapReadyCallback +import org.maplibre.android.maps.Style +import org.maplibre.android.testapp.R +import org.maplibre.android.testapp.styles.TestStyles + +/** + * TestActivity demonstrating configuring MapView with MapOptions + */ +class MapOptionsRuntimeActivity : AppCompatActivity(), OnMapReadyCallback { + + private lateinit var maplibreMap: MapLibreMap + private lateinit var mapView: MapView + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(R.layout.activity_map_options_runtime) + + // Create map configuration + val maplibreMapOptions = MapLibreMapOptions.createFromAttributes(this) + maplibreMapOptions.apply { + apiBaseUri("https://api.maplibre.org") + camera( + CameraPosition.Builder() + .bearing(0.0) + .target(LatLng(42.31230486601532, 64.63967338936439)) + .zoom(3.9) + .tilt(0.0) + .build() + ) + maxPitchPreference(90.0) + minPitchPreference(0.0) + maxZoomPreference(26.0) + minZoomPreference(2.0) + localIdeographFontFamily("Droid Sans") + zoomGesturesEnabled(true) + compassEnabled(true) + compassFadesWhenFacingNorth(true) + scrollGesturesEnabled(true) + rotateGesturesEnabled(true) + tiltGesturesEnabled(true) + } + + // Create map programmatically, add to view hierarchy + mapView = MapView(this, maplibreMapOptions) + mapView.getMapAsync(this) + mapView.onCreate(savedInstanceState) + (findViewById(R.id.container) as ViewGroup).addView(mapView) + } + + override fun onMapReady(maplibreMap: MapLibreMap) { + this.maplibreMap = maplibreMap + this.maplibreMap.setStyle("https://demotiles.maplibre.org/style.json") + } + + 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 onSaveInstanceState(outState: Bundle) { + super.onSaveInstanceState(outState) + mapView.onSaveInstanceState(outState) + } + + override fun onDestroy() { + super.onDestroy() + mapView.onDestroy() + } + + override fun onLowMemory() { + super.onLowMemory() + mapView.onLowMemory() + } +} \ No newline at end of file diff --git a/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt b/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt new file mode 100644 index 000000000..8fc41a1db --- /dev/null +++ b/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/options/MapOptionsXmlActivity.kt @@ -0,0 +1,67 @@ +package org.maplibre.android.testapp.activity.options + +import android.os.Bundle +import androidx.appcompat.app.AppCompatActivity +import org.maplibre.android.maps.MapLibreMap +import org.maplibre.android.maps.MapView +import org.maplibre.android.maps.OnMapReadyCallback +import org.maplibre.android.maps.Style +import org.maplibre.android.testapp.R +import org.maplibre.android.testapp.styles.TestStyles + +/** + * TestActivity demonstrating configuring MapView with XML + */ + +class MapOptionsXmlActivity : AppCompatActivity(), OnMapReadyCallback { + private lateinit var mapView: MapView + private lateinit var maplibreMap: MapLibreMap + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + setContentView(R.layout.activity_map_options_xml) + mapView = findViewById(R.id.mapView) + mapView.onCreate(savedInstanceState) + mapView.getMapAsync(this) + } + + override fun onMapReady(maplibreMap: MapLibreMap) { + this.maplibreMap = maplibreMap + this.maplibreMap.setStyle("https://demotiles.maplibre.org/style.json") + } + + 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 onSaveInstanceState(outState: Bundle) { + super.onSaveInstanceState(outState) + mapView.onSaveInstanceState(outState) + } + + override fun onDestroy() { + super.onDestroy() + mapView.onDestroy() + } + + override fun onLowMemory() { + super.onLowMemory() + mapView.onLowMemory() + } +} \ No newline at end of file diff --git a/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_runtime.xml b/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_runtime.xml new file mode 100644 index 000000000..c530213da --- /dev/null +++ b/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_runtime.xml @@ -0,0 +1,7 @@ + + \ No newline at end of file diff --git a/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml b/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml new file mode 100644 index 000000000..826d33bf1 --- /dev/null +++ b/platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml @@ -0,0 +1,36 @@ + + + + + + \ No newline at end of file diff --git a/platform/android/MapLibreAndroidTestApp/src/main/res/values/categories.xml b/platform/android/MapLibreAndroidTestApp/src/main/res/values/categories.xml index 9d60447ea..0c25c86c3 100644 --- a/platform/android/MapLibreAndroidTestApp/src/main/res/values/categories.xml +++ b/platform/android/MapLibreAndroidTestApp/src/main/res/values/categories.xml @@ -17,4 +17,5 @@ Location _Integration Turf + Map Options \ No newline at end of file diff --git a/platform/android/MapLibreAndroidTestApp/src/main/res/values/descriptions.xml b/platform/android/MapLibreAndroidTestApp/src/main/res/values/descriptions.xml index 6ad36b830..56c96b21d 100644 --- a/platform/android/MapLibreAndroidTestApp/src/main/res/values/descriptions.xml +++ b/platform/android/MapLibreAndroidTestApp/src/main/res/values/descriptions.xml @@ -97,4 +97,6 @@ Show a MapView inside a viewpager inside a recyclerView Show the use PerformanceEvent for performance measurements Use TurfTransformation#circle() to show a Cirlce expressed in physical units + Learn How to use MapOptions to configure map + Learn How to use custom map tags in xml to preconfigure MapView diff --git a/platform/android/MapLibreAndroidTestApp/src/main/res/values/titles.xml b/platform/android/MapLibreAndroidTestApp/src/main/res/values/titles.xml index 3a7becde3..39b55ef5a 100644 --- a/platform/android/MapLibreAndroidTestApp/src/main/res/values/titles.xml +++ b/platform/android/MapLibreAndroidTestApp/src/main/res/values/titles.xml @@ -97,4 +97,6 @@ Within expression Stretchable Image Image In Label + MapOptions Runtime + MapOptions XML \ No newline at end of file