Merge branch 'main' into main

.github/workflows/gh-pages-android-examples.yml

@@ -23,8 +23,8 @@ jobs:
         run: make mkdocs-build
 
       - name: Deploy 🚀
-        uses: JamesIves/[email protected].8
+        uses: JamesIves/[email protected].9
         with:
           branch: gh-pages
           folder: platform/android/site
-          target-folder: maplibre-native/android/examples/
+          target-folder: android/examples/

.github/workflows/gh-pages-mdbook.yml

@@ -5,11 +5,13 @@ on:
   push:
     branches:
       - main
+    paths:
+      - 'docs/mdbook/**'
 
 jobs:
-  build-docs:
+  gh-pages-mdbook-build:
     name: Build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: extractions/setup-just@v2
@@ -27,10 +29,10 @@ jobs:
           name: book
           path: docs/mdbook/book/
 
-  deploy-docs:
-    needs: build-docs
+  gh-pages-mdbook-deploy:
+    needs: gh-pages-mdbook-build
     name: Deploy
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Download book

docs/mdbook/src/SUMMARY.md

@@ -10,11 +10,5 @@
     - [Android Map Rendering Data Flow](design/android-map-rendering-data-flow.md)
     - [Geometry Tile Worker](design/geometry-tile-worker.md)
 
-- [MapLibre Native for Android](./android/README.md)
-    - [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)

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt

@@ -24,12 +24,13 @@ import timber.log.Timber
  * Shows how to use animate, ease and move camera update factory methods.
  */
 class CameraAnimationTypeActivity : AppCompatActivity(), OnMapReadyCallback {
+    // # --8<-- [start:callback]
     private val callback: CancelableCallback =
         object : CancelableCallback {
             override fun onCancel() {
                 Timber.i("Duration onCancel Callback called.")
                 Toast.makeText(
-                    this@CameraAnimationTypeActivity.applicationContext,
+                    applicationContext,
                     "Ease onCancel Callback called.",
                     Toast.LENGTH_LONG
                 )
@@ -39,13 +40,15 @@ class CameraAnimationTypeActivity : AppCompatActivity(), OnMapReadyCallback {
             override fun onFinish() {
                 Timber.i("Duration onFinish Callback called.")
                 Toast.makeText(
-                    this@CameraAnimationTypeActivity.applicationContext,
+                    applicationContext,
                     "Ease onFinish Callback called.",
                     Toast.LENGTH_LONG
                 )
                     .show()
             }
         }
+    // # --8<-- [end:callback]
+
     private lateinit var maplibreMap: MapLibreMap
     private lateinit var mapView: MapView
     private var cameraState = false
@@ -73,6 +76,7 @@ class CameraAnimationTypeActivity : AppCompatActivity(), OnMapReadyCallback {
         // handle move button clicks
         val moveButton = findViewById<View>(R.id.cameraMoveButton)
         moveButton?.setOnClickListener { view: View? ->
+            // # --8<-- [start:moveCamera]
             val cameraPosition =
                 CameraPosition.Builder()
                     .target(nextLatLng)
@@ -81,11 +85,13 @@ class CameraAnimationTypeActivity : AppCompatActivity(), OnMapReadyCallback {
                     .tilt(0.0)
                     .build()
             maplibreMap.moveCamera(CameraUpdateFactory.newCameraPosition(cameraPosition))
+            // # --8<-- [end:moveCamera]
         }
 
         // handle ease button clicks
         val easeButton = findViewById<View>(R.id.cameraEaseButton)
         easeButton?.setOnClickListener { view: View? ->
+            // # --8<-- [start:easeCamera]
             val cameraPosition =
                 CameraPosition.Builder()
                     .target(nextLatLng)
@@ -98,18 +104,21 @@ class CameraAnimationTypeActivity : AppCompatActivity(), OnMapReadyCallback {
                 7500,
                 callback
             )
+            // # --8<-- [end:easeCamera]
         }
 
         // handle animate button clicks
         val animateButton = findViewById<View>(R.id.cameraAnimateButton)
         animateButton?.setOnClickListener { view: View? ->
+            // # --8<-- [start:animateCamera]
             val cameraPosition =
                 CameraPosition.Builder().target(nextLatLng).bearing(270.0).tilt(20.0).build()
             maplibreMap.animateCamera(
                 CameraUpdateFactory.newCameraPosition(cameraPosition),
                 7500,
                 callback
             )
+            // # --8<-- [end:animateCamera]
         }
     }
 

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraPositionActivity.kt

@@ -83,7 +83,9 @@ class CameraPositionActivity : FragmentActivity(), OnMapReadyCallback, View.OnCl
         if (logCameraChanges) {
             maplibreMap.addOnCameraIdleListener(idleListener)
             maplibreMap.addOnCameraMoveCancelListener(moveCanceledListener)
+            // # --8<-- [start:addOnCameraMoveListener]
             maplibreMap.addOnCameraMoveListener(moveListener)
+            // # --8<-- [end:addOnCameraMoveListener]
             maplibreMap.addOnCameraMoveStartedListener(moveStartedListener)
         } else {
             maplibreMap.removeOnCameraIdleListener(idleListener)
@@ -151,12 +153,16 @@ class CameraPositionActivity : FragmentActivity(), OnMapReadyCallback, View.OnCl
             ContextCompat.getColor(this@CameraPositionActivity, android.R.color.holo_green_dark)
         )
     }
+
+    // # --8<-- [start:moveListener]
     private val moveListener = OnCameraMoveListener {
         Timber.e("OnCameraMove")
         fab.setColorFilter(
             ContextCompat.getColor(this@CameraPositionActivity, android.R.color.holo_orange_dark)
         )
     }
+    // # --8<-- [end:moveListener]
+
     private val moveCanceledListener = OnCameraMoveCanceledListener {
         Timber.e("OnCameraMoveCanceled")
     }
@@ -203,6 +209,7 @@ class CameraPositionActivity : FragmentActivity(), OnMapReadyCallback, View.OnCl
                 return
             }
 
+            // # --8<-- [start:cameraPosition]
             val cameraPosition = CameraPosition.Builder().target(LatLng(latitude, longitude)).zoom(zoom).bearing(bearing).tilt(tilt).build()
 
             maplibreMap?.animateCamera(
@@ -218,6 +225,7 @@ class CameraPositionActivity : FragmentActivity(), OnMapReadyCallback, View.OnCl
                     }
                 }
             )
+            // # --8<-- [end:cameraPosition]
             Timber.v(cameraPosition.toString())
         }
     }

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt

@@ -44,29 +44,39 @@ class ManualZoomActivity : AppCompatActivity() {
     override fun onOptionsItemSelected(item: MenuItem): Boolean {
         return when (item.itemId) {
             R.id.action_zoom_in -> {
+                // # --8<-- [start:zoomIn]
                 maplibreMap.animateCamera(CameraUpdateFactory.zoomIn())
+                // # --8<-- [end:zoomIn]
                 true
             }
             R.id.action_zoom_out -> {
+                // # --8<-- [start:zoomOut]
                 maplibreMap.animateCamera(CameraUpdateFactory.zoomOut())
+                // # --8<-- [end:zoomOut]
                 true
             }
             R.id.action_zoom_by -> {
+                // # --8<-- [start:zoomBy]
                 maplibreMap.animateCamera(CameraUpdateFactory.zoomBy(2.0))
+                // # --8<-- [end:zoomBy]
                 true
             }
             R.id.action_zoom_to -> {
+                // # --8<-- [start:zoomTo]
                 maplibreMap.animateCamera(CameraUpdateFactory.zoomTo(2.0))
+                // # --8<-- [end:zoomTo]
                 true
             }
             R.id.action_zoom_to_point -> {
+                // # --8<-- [start:zoomToPoint]
                 val view = window.decorView
                 maplibreMap.animateCamera(
                     CameraUpdateFactory.zoomBy(
                         1.0,
                         Point(view.measuredWidth / 4, view.measuredHeight / 4)
                     )
                 )
+                // # --8<-- [end:zoomToPoint]
                 true
             }
             else -> super.onOptionsItemSelected(item)

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/MaxMinZoomActivity.kt

@@ -15,12 +15,6 @@ import timber.log.Timber
 class MaxMinZoomActivity : AppCompatActivity(), OnMapReadyCallback {
     private lateinit var mapView: MapView
     private lateinit var maplibreMap: MapLibreMap
-    private val clickListener = OnMapClickListener {
-        if (this::maplibreMap.isInitialized) {
-            maplibreMap.setStyle(Style.Builder().fromUri(TestStyles.getPredefinedStyleWithFallback("Outdoor")))
-        }
-        true
-    }
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -33,10 +27,20 @@ class MaxMinZoomActivity : AppCompatActivity(), OnMapReadyCallback {
 
     override fun onMapReady(map: MapLibreMap) {
         maplibreMap = map
-        maplibreMap.setStyle(TestStyles.getPredefinedStyleWithFallback("Streets"))
+        maplibreMap.setStyle(TestStyles.OPENFREEMAP_LIBERY)
+        // # --8<-- [start:zoomPreference]
         maplibreMap.setMinZoomPreference(3.0)
         maplibreMap.setMaxZoomPreference(5.0)
-        maplibreMap.addOnMapClickListener(clickListener)
+        // # --8<-- [end:zoomPreference]
+
+        // # --8<-- [start:addOnMapClickListener]
+        maplibreMap.addOnMapClickListener {
+            if (this::maplibreMap.isInitialized) {
+                maplibreMap.setStyle(Style.Builder().fromUri(TestStyles.AMERICANA))
+            }
+            true
+        }
+        // # --8<-- [end:addOnMapClickListener]
     }
 
     override fun onStart() {
@@ -66,9 +70,6 @@ class MaxMinZoomActivity : AppCompatActivity(), OnMapReadyCallback {
 
     override fun onDestroy() {
         super.onDestroy()
-        if (this::maplibreMap.isInitialized) {
-            maplibreMap.removeOnMapClickListener(clickListener)
-        }
         mapView.onDestroy()
     }
 

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ScrollByActivity.kt

@@ -60,10 +60,12 @@ class ScrollByActivity : AppCompatActivity(), OnMapReadyCallback {
         val fab = findViewById<FloatingActionButton>(R.id.fab)
         fab.setColorFilter(ContextCompat.getColor(this@ScrollByActivity, R.color.primary))
         fab.setOnClickListener { _: View? ->
+            // # --8<-- [start:scrollBy]
             maplibreMap.scrollBy(
                 (seekBarX.progress * MULTIPLIER_PER_PIXEL).toFloat(),
                 (seekBarY.progress * MULTIPLIER_PER_PIXEL).toFloat()
             )
+            // # --8<-- [end:scrollBy]
         }
     }
 

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

@@ -29,6 +29,7 @@
             android:layout_width="0dp"
             android:layout_height="wrap_content"
             android:layout_weight="1"
+            android:textColor="@color/white"
             android:text="@string/button_camera_move"/>
 
         <Button
@@ -37,6 +38,7 @@
             android:layout_width="0dp"
             android:layout_height="wrap_content"
             android:layout_weight="1"
+            android:textColor="@color/white"
             android:text="@string/button_camera_ease"/>
 
         <Button
@@ -45,6 +47,7 @@
             android:layout_width="0dp"
             android:layout_height="wrap_content"
             android:layout_weight="1"
+            android:textColor="@color/white"
             android:text="@string/button_camera_animate"/>
 
     </LinearLayout>

platform/android/docs/assets/extra.css

@@ -13,6 +13,11 @@
   display: none;
 }
 
-.md-grid {
-  max-width: 1800px; 
+.md-nav--primary .md-nav__link[for=__toc] > .md-nav__icon,
+.md-nav--primary .md-nav__link[for=__toc] ~ .md-nav {
+  display: none;
+}
+
+.md-copyright__highlight {
+  color: inherit;
 }

platform/android/docs/camera/animation-types.md

@@ -1,13 +1,64 @@
 # Animation Types
 
+!!! note
+
+    You can find the full source code of this example in [`CameraAnimationTypeActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/activity/camera/CameraAnimationTypeActivity.kt) of the MapLibreAndroidTestApp.
+
 This example showcases the different animation types.
 
 - **Move**: available via the `MapLibreMap.moveCamera` method.
 - **Ease**: available via the `MapLibreMap.easeCamera` method.
 - **Animate**: available via the `MapLibreMap.animateCamera` method.
 
-It also shows how to pass callbacks that are called when an animation is cancelled.
+### Move
+
+The `MapLibreMap.moveCamera` method jumps to the camera position provided.
+
+```kotlin
+--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt:moveCamera"
+```
+
+<figure markdown="span">
+  <video controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/move_animation_thumbnail.jpg">
+    <source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/move_animation.mp4" />
+  </video>
+</figure>
+
+### Ease
+
+The `MapLibreMap.moveCamera` eases to the camera position provided (with constant ground speed).
+
+```kotlin
+--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt:easeCamera"
+```
+
+<figure markdown="span">
+  <video preload="none" controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/ease_animation_thumbnail.jpg">
+    <source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/ease_animation.mp4" />
+  </video>
+</figure>
+
+
+### Animate
+
+The `MapLibreMap.animateCamera` uses a powered flight animation move to the camera position provided[^1].
+
+[^1]: The implementation is based on  Van Wijk, Jarke J.; Nuij, Wim A. A. “Smooth and efficient zooming and panning.” INFOVIS ’03. pp. 15–22. [https://www.win.tue.nl/~vanwijk/zoompan.pdf#page=5](https://www.win.tue.nl/~vanwijk/zoompan.pdf#page=5)
+
+```kotlin
+--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt:animateCamera"
+```
+
+<figure markdown="span">
+  <video preload="none" controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/animate_animation_thumbnail.jpg">
+    <source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/animate_animation.mp4" />
+  </video>
+</figure>
+
+## Animation Callbacks
+
+In the previous section a `CancellableCallback` was passed to the last two animation methods. This callback shows a toast message when the animation is cancelled or when it is finished.
 
-```kotlin title="CameraAnimationTypeActivity.kt"
---8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt"
+```kotlin
+--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt:callback"
 ```