Feature/documentation maplibre map options (#2646)

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

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>