Feature/documentation maplibre map options (#2646)

Co-authored-by: Bart Louwers <bart.louwers@gmail.com>

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)

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:
+
+<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).

platform/android/MapLibreAndroidTestApp/src/main/AndroidManifest.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:tools="http://schemas.android.com/tools"
-    xmlns:android="http://schemas.android.com/apk/res/android">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
 
     <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
 
@@ -14,7 +14,6 @@
         android:roundIcon="@drawable/ic_launcher_round"
         android:supportsRtl="true"
         android:theme="@style/AppTheme">
-
         <activity
             android:name=".activity.FeatureOverviewActivity"
             android:exported="true"
@@ -718,8 +717,7 @@
             <meta-data
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
-        </activity>
-        <!-- Features -->
+        </activity> <!-- Features -->
         <activity
             android:name=".activity.feature.QueryRenderedFeaturesPropertiesActivity"
             android:description="@string/description_query_rendered_feature_properties_point"
@@ -828,9 +826,7 @@
             <meta-data
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
-        </activity>
-
-        <!-- Storage -->
+        </activity> <!-- Storage -->
         <activity
             android:name=".activity.storage.UrlTransformActivity"
             android:description="@string/description_url_transform"
@@ -878,9 +874,7 @@
             <meta-data
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
-        </activity>
-
-        <!-- TextureView -->
+        </activity> <!-- TextureView -->
         <activity
             android:name=".activity.textureview.TextureViewDebugModeActivity"
             android:description="@string/description_textureview_debug"
@@ -978,7 +972,6 @@
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
         </activity>
-
         <activity
             android:name=".activity.style.DraggableMarkerActivity"
             android:description="@string/description_draggable_marker"
@@ -1192,14 +1185,13 @@
             <meta-data
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
-        </activity>
-        <!-- Benchmark -->
+        </activity> <!-- Benchmark -->
         <activity
             android:name=".activity.benchmark.BenchmarkActivity"
-            android:screenOrientation="portrait"
             android:description="@string/description_world_tour_benchmark"
             android:exported="true"
             android:label="@string/activity_benchmark_world_tour"
+            android:screenOrientation="portrait"
             tools:ignore="LockedOrientationActivity">
             <meta-data
                 android:name="@string/category"
@@ -1207,8 +1199,7 @@
             <meta-data
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
-        </activity>
-        <!-- For Instrumentation tests -->
+        </activity> <!-- For Instrumentation tests -->
         <activity
             android:name=".activity.style.RuntimeStyleTimingTestActivity"
             android:screenOrientation="portrait" />
@@ -1226,26 +1217,49 @@
             android:screenOrientation="portrait" />
         <activity
             android:name=".activity.render.RenderTestActivity"
-            android:screenOrientation="landscape" />
-        <!-- Configuration Settings -->
+            android:screenOrientation="landscape" /> <!-- Configuration Settings -->
         <meta-data
             android:name="com.maplibre.TestEventsServer"
             android:value="api-events-staging.tilestream.net" />
         <meta-data
             android:name="com.maplibre.TestEventsAccessToken"
-            android:value="pk.eyJ1IjoiYmxzdGFnaW5nIiwiYSI6ImNpdDF3OHpoaTAwMDcyeXA5Y3Z0Nmk2dzEifQ.0IfB7v5Qbm2MGVYt8Kb8fg" />
-
-        <!-- Comment out this setting to switch to external storage (and disable internal) in your app -->
+            android:value="pk.eyJ1IjoiYmxzdGFnaW5nIiwiYSI6ImNpdDF3OHpoaTAwMDcyeXA5Y3Z0Nmk2dzEifQ.0IfB7v5Qbm2MGVYt8Kb8fg" /> <!-- Comment out this setting to switch to external storage (and disable internal) in your app -->
         <!-- Alternatively you can rely on FileSource#setResourceCachePath API instead -->
         <!-- <meta-data -->
         <!-- android:name="com.maplibre.SetStorageExternal" -->
         <!-- android:value="true" /> -->
-
         <!-- Set value to true to have tile loading measurements on -->
         <meta-data
             android:name="com.maplibre.MeasureTileDownloadOn"
             android:value="false" />
 
+        <activity
+            android:name=".activity.options.MapOptionsRuntimeActivity"
+            android:description="@string/description_map_options_run_time"
+            android:exported="true"
+            android:label="@string/activity_map_options_runtime">
+            <meta-data
+                android:name="@string/category"
+                android:value="@string/category_map_options" />
+            <meta-data
+                android:name="android.support.PARENT_ACTIVITY"
+                android:value=".activity.FeatureOverviewActivity" />
+        </activity>
+
+        <activity
+            android:name=".activity.options.MapOptionsXmlActivity"
+            android:exported="true"
+            android:description="@string/description_map_options_xml"
+            android:label="@string/activity_map_options_xml"
+            >
+            <meta-data
+                android:name="@string/category"
+                android:value="@string/category_map_options" />
+            <meta-data
+                android:name="android.support.PARENT_ACTIVITY"
+                android:value=".activity.FeatureOverviewActivity" />
+        </activity>
+
     </application>
 
 </manifest>

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<View>(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()
+    }
+}

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()
+    }
+}

platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_runtime.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<FrameLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/container"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="vertical"/>

platform/android/MapLibreAndroidTestApp/src/main/res/layout/activity_map_options_xml.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="utf-8"?>
+<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:id="@+id/main"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    tools:context=".activity.options.MapOptionsXmlActivity">
+
+    <org.maplibre.android.maps.MapView
+        android:id="@+id/mapView"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"
+        app:maplibre_apiBaseUri="https://api.maplibre.org"
+        app:maplibre_cameraBearing="0.0"
+        app:maplibre_cameraPitchMax="90.0"
+        app:maplibre_cameraPitchMin="0.0"
+        app:maplibre_cameraTargetLat="42.31230486601532"
+        app:maplibre_cameraTargetLng="64.63967338936439"
+        app:maplibre_cameraTilt="0.0"
+        app:maplibre_cameraZoom="3.9"
+        app:maplibre_cameraZoomMax="26.0"
+        app:maplibre_cameraZoomMin="2.0"
+        app:maplibre_localIdeographFontFamilies="@array/array_local_ideograph_family_test"
+        app:maplibre_localIdeographFontFamily="Droid Sans"
+        app:maplibre_uiCompass="true"
+        app:maplibre_uiCompassFadeFacingNorth="true"
+        app:maplibre_uiCompassGravity="top|end"
+        app:maplibre_uiDoubleTapGestures="true"
+        app:maplibre_uiHorizontalScrollGestures="true"
+        app:maplibre_uiRotateGestures="true"
+        app:maplibre_uiScrollGestures="true"
+        app:maplibre_uiTiltGestures="true"
+        app:maplibre_uiZoomGestures="true" />
+
+</androidx.constraintlayout.widget.ConstraintLayout>

platform/android/MapLibreAndroidTestApp/src/main/res/values/categories.xml

@@ -17,4 +17,5 @@
     <string name="category_location">Location</string>
     <string name="category_integration">_Integration</string>
     <string name="category_turf">Turf</string>
+    <string name="category_map_options">Map Options</string>
 </resources>

platform/android/MapLibreAndroidTestApp/src/main/res/values/descriptions.xml

@@ -97,4 +97,6 @@
     <string name="description_nested_viewpager">Show a MapView inside a viewpager inside a recyclerView</string>
     <string name="description_performance_measurement">Show the use PerformanceEvent for performance measurements</string>
     <string name="description_physical_circle">Use TurfTransformation#circle() to show a Cirlce expressed in physical units</string>
+    <string name="description_map_options_run_time">Learn How to use MapOptions to configure map</string>
+    <string name="description_map_options_xml">Learn How to use custom map tags in xml to preconfigure MapView</string>
 </resources>

platform/android/MapLibreAndroidTestApp/src/main/res/values/titles.xml

@@ -97,4 +97,6 @@
     <string name="activity_within">Within expression</string>
     <string name="activity_stretchable_image">Stretchable Image</string>
     <string name="activity_image_in_label">Image In Label</string>
+    <string name="activity_map_options_runtime">MapOptions Runtime</string>
+    <string name="activity_map_options_xml">MapOptions XML</string>
 </resources>