tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve Android Example Documentation, Animation Types (#3019)

Browse Source
This commit is contained in:
Bart Louwers
2024-11-14 23:46:58 +01:00
committed by GitHub
parent 38bf215e4f
commit e9afa1f461
17 changed files with 244 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
platform/android/docs/camera/animation-types.md
View File

@@ -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
```kotlin title="CameraAnimationTypeActivity.kt"
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt"
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
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraAnimationTypeActivity.kt:callback"
```

34
platform/android/docs/camera/cameraposition.md
View File

@@ -1,7 +1,35 @@
# CameraPosition Capabilities
!!! note
You can find the full source code of this example in [`CameraPositionActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraPositionActivity.kt) of the MapLibreAndroidTestApp.
This example showcases how to listen to camera change events.
```kotlin title="CameraPositionActivity.kt"
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraPositionActivity.kt"
```
<figure markdown="span">
<video controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/cameraposition_thumbnail.jpg">
<source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/cameraposition.mp4" />
</video>
</figure>
The camera animation is kicked off with this code:
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraPositionActivity.kt:cameraPosition"
```
Notice how the color of the button in the bottom right changes color. Depending on the state of the camera.
We can listen for changes to the state of the camera by registering a `OnCameraMoveListener`, `OnCameraIdleListener`, `OnCameraMoveCanceledListener` or `OnCameraMoveStartedListener` with the `MapLibreMap`. For example, the `OnCameraMoveListener` is defined with:
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraPositionActivity.kt:moveListener"
```
And registered with:
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/CameraPositionActivity.kt:addOnCameraMoveListener"
```
Refer to the full example to learn the methods to register the other types of camera change events.

9
platform/android/docs/camera/lat-lng-bounds.md
View File

@@ -3,16 +3,17 @@
!!! note
You can find the full source code of this example in [`LatLngBoundsActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/testapp/activity/camera/LatLngBoundsActivity.kt) of the MapLibreAndroidTestApp.
You can find the full source code of this example in [`LatLngBoundsActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/LatLngBoundsActivity.kt) of the MapLibreAndroidTestApp.
This example demonstrates setting the camera to some bounds defined by some features. It sets these bounds when the map is initialized and when the [bottom sheet](https://m2.material.io/components/sheets-bottom) is opened or closed.
<figure markdown="span">
<video controls width="250">
<source src="https://github.com/user-attachments/assets/46a89dfb-3abc-448a-be53-8abe39b2919b" />
</video>
<video controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/lat_lng_bounds_thumbnail.jpg">
<source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/lat_lng_bounds.mp4" />
</video>
</figure>
Here you can see how the feature collection is loaded and how `MapLibreMap.getCameraForLatLngBounds` is used to set the bounds during map initialization:
```kotlin

28
platform/android/docs/camera/min-max-zoom.md Normal file
View File

@@ -0,0 +1,28 @@
# Min/Max Zoom
!!! note
You can find the full source code of this example in [`MaxMinZoomActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/MaxMinZoomActivity.kt) of the MapLibreAndroidTestApp.
This example shows how to configure a maximum and a minimum zoom level.
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/MaxMinZoomActivity.kt:zoomPreference"
```
## Bonus: Add Click Listener
As a bonus, this example also shows how you can define a click listener to the map.
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/MaxMinZoomActivity.kt:addOnMapClickListener"
```
You can remove a click listener again with `MapLibreMap.removeOnMapClickListener`. To use this API you need to assign the click listener to a variable, since you need to pass the listener to that method.
<figure markdown="span">
<video controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/max_min_zoom_thumbnail.jpg">
<source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/max_min_zoom.mp4" />
</video>
</figure>

15
platform/android/docs/camera/move-map-pixels.md Normal file
View File

@@ -0,0 +1,15 @@
# Scroll by Method
!!! note
You can find the full source code of this example in [`ScrollByActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ScrollByActivity.kt) of the MapLibreAndroidTestApp.
This example shows how you can move the map by x/y pixels.
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ScrollByActivity.kt:scrollBy"
```
<figure markdown="span">
![Screenshot of Example Activity to move the map by some pixels](https://github.com/user-attachments/assets/f8ae0ec7-a165-4fb3-ab9f-bfb5579c7dd8){ width="300" }
</figure>

46
platform/android/docs/camera/zoom-methods.md Normal file
View File

@@ -0,0 +1,46 @@
# Zoom Methods
!!! note
You can find the full source code of this example in [`ManualZoomActivity.kt`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt) of the MapLibreAndroidTestApp.
This example shows different methods of zooming in.
<figure markdown="span">
<video controls width="250" poster="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/zoom_methods_thumbnail.jpg">
<source src="https://maplibre-native.s3.eu-central-1.amazonaws.com/android-documentation-resources/zoom_methods.mp4" />
</video>
</figure>
Each method uses `MapLibreMap.animateCamera`, but with a different `CameraUpdateFactory`.
#### Zooming In
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt:zoomIn"
```
#### Zooming Out
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt:zoomOut"
```
#### Zoom By Some Amount of Zoom Levels
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt:zoomBy"
```
#### Zoom to a Zoom Level
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt:zoomTo"
```
#### Zoom to a Point
```kotlin
--8<-- "MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/ManualZoomActivity.kt:zoomToPoint"
```