Add doc for annotation (#1135)

Co-authored-by: Hsieh Chin Fan <pham@topo.tw>
Co-authored-by: Bart Louwers <bart@emeel.net>
Co-authored-by: Bart Louwers <bart.louwers@gmail.com>

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

@@ -111,6 +111,19 @@
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".activity.FeatureOverviewActivity" />
         </activity>
+        <activity
+            android:name=".activity.annotation.JsonApiActivity"
+            android:configChanges="orientation|keyboardHidden|screenSize"
+            android:description="@string/description_add_makers_by_json_api"
+            android:exported="true"
+            android:label="@string/activity_json_api">
+            <meta-data
+                android:name="@string/category"
+                android:value="@string/category_annotation" />
+            <meta-data
+                android:name="android.support.PARENT_ACTIVITY"
+                android:value=".activity.FeatureOverviewActivity" />
+        </activity>
         <activity
             android:name=".activity.camera.CameraAnimationTypeActivity"
             android:description="@string/description_camera_animation_types"

platform/android/MapboxGLAndroidSDKTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt

@@ -0,0 +1,185 @@
+package org.maplibre.android.testapp.activity.annotation
+
+import android.graphics.Color
+import android.os.Bundle
+import android.widget.Toast
+import androidx.appcompat.app.AppCompatActivity
+import androidx.core.content.res.ResourcesCompat
+import androidx.core.graphics.drawable.toBitmap
+import com.mapbox.geojson.FeatureCollection
+import com.mapbox.geojson.Point
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import org.maplibre.android.MapLibre
+import org.maplibre.android.annotations.IconFactory
+import org.maplibre.android.annotations.MarkerOptions
+import org.maplibre.android.camera.CameraPosition
+import org.maplibre.android.geometry.LatLng
+import org.maplibre.android.geometry.LatLngBounds
+import org.maplibre.android.maps.MapLibreMap
+import org.maplibre.android.maps.MapView
+import org.maplibre.android.testapp.R
+import java.io.IOException
+import java.text.SimpleDateFormat
+import java.util.Locale
+
+/* ANCHOR: top */
+class JsonApiActivity : AppCompatActivity() {
+
+    // Declare a variable for MapView
+    private lateinit var mapView: MapView
+
+    // Declare a variable for MapboxMap
+    private lateinit var maplibreMap: MapLibreMap
+    /* ANCHOR_END: top */
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // Init MapLibre
+        MapLibre.getInstance(this)
+
+        // Init layout view
+        setContentView(R.layout.activity_json_api)
+
+        // Init the MapView
+        mapView = findViewById(R.id.mapView)
+
+        /* ANCHOR: mapAsync */
+        mapView.getMapAsync { map ->
+            maplibreMap = map
+
+            maplibreMap.setStyle("https://demotiles.maplibre.org/style.json")
+
+            // Fetch data from USGS
+            getEarthQuakeDataFromUSGS()
+        }
+        /* ANCHOR_END: mapAsync */
+    }
+
+    /* ANCHOR: getEarthquakes */
+    // Get Earthquake data from usgs.gov, read API doc at:
+    // https://earthquake.usgs.gov/fdsnws/event/1/
+    private fun getEarthQuakeDataFromUSGS() {
+        val url = "https://earthquake.usgs.gov/fdsnws/event/1/query".toHttpUrl().newBuilder()
+            .addQueryParameter("format", "geojson")
+            .addQueryParameter("starttime", "2022-01-01")
+            .addQueryParameter("endtime", "2022-12-31")
+            .addQueryParameter("minmagnitude", "5.8")
+            .addQueryParameter("latitude", "24")
+            .addQueryParameter("longitude", "121")
+            .addQueryParameter("maxradius", "1.5")
+            .build()
+        val request: Request = Request.Builder().url(url).build()
+
+        OkHttpClient().newCall(request).enqueue(object : Callback {
+            override fun onFailure(call: Call, e: IOException) {
+                Toast.makeText(this@JsonApiActivity, "Fail to fetch data", Toast.LENGTH_SHORT)
+                    .show()
+            }
+
+            override fun onResponse(call: Call, response: Response) {
+                val featureCollection = response.body?.string()
+                    ?.let(FeatureCollection::fromJson)
+                    ?: return
+                // If FeatureCollection in response is not null
+                // Then add markers to map
+                runOnUiThread { addMarkersToMap(featureCollection) }
+            }
+        })
+    }
+    /* ANCHOR_END: getEarthquakes */
+
+    /* ANCHOR: addMarkers */
+    private fun addMarkersToMap(data: FeatureCollection) {
+        val bounds = mutableListOf<LatLng>()
+
+        // Get bitmaps for marker icon
+        val infoIconDrawable = ResourcesCompat.getDrawable(
+            this.resources,
+            // Intentionally specify package name
+            // This makes copy from another project easier
+            org.maplibre.android.R.drawable.maplibre_info_icon_default,
+            null
+        )!!
+        val bitmapBlue = infoIconDrawable.toBitmap()
+        val bitmapRed = infoIconDrawable
+            .mutate()
+            .apply { setTint(Color.RED) }
+            .toBitmap()
+
+        // Add symbol for each point feature
+        data.features()?.forEach { feature ->
+            val geometry = feature.geometry()?.toJson() ?: return@forEach
+            val point = Point.fromJson(geometry) ?: return@forEach
+            val latLng = LatLng(point.latitude(), point.longitude())
+            bounds.add(latLng)
+
+            // Contents in InfoWindow of each marker
+            val title = feature.getStringProperty("title")
+            val epochTime = feature.getNumberProperty("time")
+            val dateString = SimpleDateFormat("yyyy/MM/dd HH:mm", Locale.TAIWAN).format(epochTime)
+
+            // If magnitude > 6.0, show marker with red icon. If not, show blue icon instead
+            val mag = feature.getNumberProperty("mag")
+            val icon = IconFactory.getInstance(this)
+                .fromBitmap(if (mag.toFloat() > 6.0) bitmapRed else bitmapBlue)
+
+            // Use MarkerOptions and addMarker() to add a new marker in map
+            val markerOptions = MarkerOptions()
+                .position(latLng)
+                .title(dateString)
+                .snippet(title)
+                .icon(icon)
+            maplibreMap.addMarker(markerOptions)
+        }
+
+        // Move camera to newly added annotations
+        maplibreMap.getCameraForLatLngBounds(LatLngBounds.fromLatLngs(bounds))?.let {
+            val newCameraPosition = CameraPosition.Builder()
+                .target(it.target)
+                .zoom(it.zoom - 0.5)
+                .build()
+            maplibreMap.cameraPosition = newCameraPosition
+        }
+    }
+    /* ANCHOR_END: addMarkers */
+
+    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 onLowMemory() {
+        super.onLowMemory()
+        mapView.onLowMemory()
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        mapView.onDestroy()
+    }
+
+    override fun onSaveInstanceState(outState: Bundle) {
+        super.onSaveInstanceState(outState)
+        mapView.onSaveInstanceState(outState)
+    }
+}

platform/android/MapboxGLAndroidSDKTestApp/src/main/res/layout/activity_json_api.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<RelativeLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent">
+
+    <org.maplibre.android.maps.MapView
+        android:id="@id/mapView"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"/>
+
+</RelativeLayout>

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

@@ -8,6 +8,7 @@
     <string name="description_map_fragment_backstack">Showcase using a Map Fragment with a fragment backstack</string>
     <string name="description_multimap">Activity with multiple maps on screen</string>
     <string name="description_press_for_marker">Add marker to map on long press</string>
+    <string name="description_add_makers_by_json_api">Use JSON API to add markers</string>
     <string name="description_camera_zoom">Different types of zoom methods</string>
     <string name="description_minmax_zoom">Configure a max and min zoomlevel</string>
     <string name="description_info_window">Learn how to handle the InfoWindow</string>

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

@@ -11,6 +11,7 @@
     <string name="activity_polygon">Polygon</string>
     <string name="activity_press_for_marker">Press Map For Marker</string>
     <string name="activity_add_remove_markers">Zoom function with SymbolLayer</string>
+    <string name="activity_json_api">Add Markers From JSON API</string>
     <string name="activity_info_window">Standard InfoWindow</string>
     <string name="activity_infowindow_adapter">Custom InfoWindow</string>
     <string name="activity_dynamic_infowindow_adapter">Custom Dynamic InfoWindow</string>