[android] - add style loading callback (#8291)

* [android] - add style loading callback that is invoked when a style finishes loading.

* fixup language + add support for adding a callback when invoking setStyle with the default styles.

3 files changed, 106 insertions, 17 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
index 46c5e269c0..2af2c2ef0f 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
@@ -881,35 +881,80 @@ public final class MapboxMap {
 
   /**
    * <p>
-   * Loads a new map style from the specified URL.
+   * Loads a new map style asynchronous from the specified URL.
    * </p>
    * {@code url} can take the following forms:
    * <ul>
    * <li>{@code Style.*}: load one of the bundled styles in {@link Style}.</li>
    * <li>{@code mapbox://styles/<user>/<style>}:
-   * retrieves the style from a <a href="https://www.mapbox.com/account/">Mapbox account.</a>
+   * loads the style from a <a href="https://www.mapbox.com/account/">Mapbox account.</a>
    * {@code user} is your username. {@code style} is the ID of your custom
    * style created in <a href="https://www.mapbox.com/studio">Mapbox Studio</a>.</li>
    * <li>{@code http://...} or {@code https://...}:
-   * retrieves the style over the Internet from any web server.</li>
+   * loads the style over the Internet from any web server.</li>
    * <li>{@code asset://...}:
-   * reads the style from the APK {@code assets/} directory.
+   * loads the style from the APK {@code assets/} directory.
    * This is used to load a style bundled with your app.</li>
    * <li>{@code null}: loads the default {@link Style#MAPBOX_STREETS} style.</li>
    * </ul>
    * <p>
-   * This method is asynchronous and will return immediately before the style finishes loading.
-   * If you wish to wait for the map to finish loading listen for the {@link MapView#DID_FINISH_LOADING_MAP} event.
+   * This method is asynchronous and will return before the style finishes loading.
+   * If you wish to wait for the map to finish loading, listen for the {@link MapView#DID_FINISH_LOADING_MAP} event
+   * or use the {@link #setStyleUrl(String, OnStyleLoadedListener)} method instead.
    * </p>
    * If the style fails to load or an invalid style URL is set, the map view will become blank.
    * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be
-   * sent.
+   * emitted.
    *
    * @param url The URL of the map style
    * @see Style
    */
   @UiThread
   public void setStyleUrl(@NonNull String url) {
+    setStyleUrl(url, null);
+  }
+
+  /**
+   * <p>
+   * Loads a new map style asynchronous from the specified URL.
+   * </p>
+   * {@code url} can take the following forms:
+   * <ul>
+   * <li>{@code Style.*}: load one of the bundled styles in {@link Style}.</li>
+   * <li>{@code mapbox://styles/<user>/<style>}:
+   * loads the style from a <a href="https://www.mapbox.com/account/">Mapbox account.</a>
+   * {@code user} is your username. {@code style} is the ID of your custom
+   * style created in <a href="https://www.mapbox.com/studio">Mapbox Studio</a>.</li>
+   * <li>{@code http://...} or {@code https://...}:
+   * loads the style over the Internet from any web server.</li>
+   * <li>{@code asset://...}:
+   * loads the style from the APK {@code assets/} directory.
+   * This is used to load a style bundled with your app.</li>
+   * <li>{@code null}: loads the default {@link Style#MAPBOX_STREETS} style.</li>
+   * </ul>
+   * <p>
+   * If the style fails to load or an invalid style URL is set, the map view will become blank.
+   * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be
+   * emitted.
+   * <p>
+   *
+   * @param url      The URL of the map style
+   * @param callback The callback that is invoked when the style has loaded.
+   * @see Style
+   */
+  @UiThread
+  public void setStyleUrl(@NonNull final String url, @Nullable final OnStyleLoadedListener callback) {
+    if (callback != null) {
+      nativeMapView.addOnMapChangedListener(new MapView.OnMapChangedListener() {
+        @Override
+        public void onMapChanged(@MapView.MapChange int change) {
+          if (change == MapView.DID_FINISH_LOADING_STYLE) {
+            callback.onStyleLoaded(url);
+            nativeMapView.removeOnMapChangedListener(this);
+          }
+        }
+      });
+    }
     nativeMapView.setStyleUrl(url);
   }
 
@@ -918,8 +963,9 @@ public final class MapboxMap {
    * Loads a new map style from the specified bundled style.
    * </p>
    * <p>
-   * This method is asynchronous and will return immediately before the style finishes loading.
-   * If you wish to wait for the map to finish loading listen for the {@link MapView#DID_FINISH_LOADING_MAP} event.
+   * This method is asynchronous and will return before the style finishes loading.
+   * If you wish to wait for the map to finish loading, listen for the {@link MapView#DID_FINISH_LOADING_MAP} event
+   * or use the {@link #setStyle(String, OnStyleLoadedListener)} method instead.
    * </p>
    * If the style fails to load or an invalid style URL is set, the map view will become blank.
    * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be
@@ -927,7 +973,6 @@ public final class MapboxMap {
    *
    * @param style The bundled style. Accepts one of the values from {@link Style}.
    * @see Style
-   * @deprecated use {@link #setStyleUrl(String)} instead with versioned url methods from {@link Style}
    */
   @UiThread
   public void setStyle(@Style.StyleUrl String style) {
@@ -935,6 +980,22 @@ public final class MapboxMap {
   }
 
   /**
+   * <p>
+   * Loads a new map style from the specified bundled style.
+   * </p>
+   * If the style fails to load or an invalid style URL is set, the map view will become blank.
+   * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be
+   * sent.
+   *
+   * @param style The bundled style. Accepts one of the values from {@link Style}.
+   * @see Style
+   */
+  @UiThread
+  public void setStyle(@Style.StyleUrl String style, @Nullable OnStyleLoadedListener callback) {
+    setStyleUrl(style, callback);
+  }
+
+  /**
    * Loads a new map style from MapboxMapOptions if available.
    *
    * @param options the object containing the style url
@@ -942,20 +1003,17 @@ public final class MapboxMap {
   private void setStyleUrl(@NonNull MapboxMapOptions options) {
     String style = options.getStyle();
     if (!TextUtils.isEmpty(style)) {
-      setStyleUrl(style);
+      setStyleUrl(style, null);
     }
   }
 
   /**
-   * <p>
    * Returns the map style currently displayed in the map view.
-   * </p>
-   * If the default style is currently displayed, a URL will be returned instead of null.
    *
    * @return The URL of the map style.
    */
   @UiThread
-  @NonNull
+  @Nullable
   public String getStyleUrl() {
     return nativeMapView.getStyleUrl();
   }
@@ -2104,6 +2162,16 @@ public final class MapboxMap {
     void onSnapshotReady(Bitmap snapshot);
   }
 
+  /**
+   * Interface definintion for a callback to be invoked when the style has finished loading.
+   */
+  public interface OnStyleLoadedListener {
+    /**
+     * Invoked when the style has finished loading.
+     */
+    void onStyleLoaded(String style);
+  }
+
   //
   // Used for instrumentation testing
   //
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/camera/MaxMinZoomActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/camera/MaxMinZoomActivity.java
index 86d5b47275..014743df96 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/camera/MaxMinZoomActivity.java
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/camera/MaxMinZoomActivity.java
@@ -1,13 +1,18 @@
 package com.mapbox.mapboxsdk.testapp.activity.camera;
 
 import android.os.Bundle;
+import android.support.annotation.NonNull;
 import android.support.v7.app.AppCompatActivity;
 
+import com.mapbox.mapboxsdk.constants.Style;
+import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.maps.MapView;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 import com.mapbox.mapboxsdk.maps.OnMapReadyCallback;
 import com.mapbox.mapboxsdk.testapp.R;
 
+import timber.log.Timber;
+
 public class MaxMinZoomActivity extends AppCompatActivity implements OnMapReadyCallback {
 
   private MapView mapView;
@@ -25,10 +30,21 @@ public class MaxMinZoomActivity extends AppCompatActivity implements OnMapReadyC
   }
 
   @Override
-  public void onMapReady(MapboxMap map) {
+  public void onMapReady(final MapboxMap map) {
     mapboxMap = map;
     mapboxMap.setMinZoomPreference(3);
     mapboxMap.setMaxZoomPreference(5);
+    mapboxMap.setOnMapClickListener(new MapboxMap.OnMapClickListener() {
+      @Override
+      public void onMapClick(@NonNull LatLng point) {
+        map.setStyle(Style.OUTDOORS, new MapboxMap.OnStyleLoadedListener() {
+          @Override
+          public void onStyleLoaded(String style) {
+            Timber.d("Style Loaded %s", style);
+          }
+        });
+      }
+    });
   }
 
   @Override
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/maplayout/DebugModeActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/maplayout/DebugModeActivity.java
index 6ec0ccc11f..12fafb4d3a 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/maplayout/DebugModeActivity.java
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/maplayout/DebugModeActivity.java
@@ -70,7 +70,12 @@ public class DebugModeActivity extends AppCompatActivity {
           if (currentStyleIndex == STYLES.length) {
             currentStyleIndex = 0;
           }
-          mapboxMap.setStyleUrl(STYLES[currentStyleIndex]);
+          mapboxMap.setStyleUrl(STYLES[currentStyleIndex], new MapboxMap.OnStyleLoadedListener() {
+            @Override
+            public void onStyleLoaded(String style) {
+              Timber.d("Style loaded %s", style);
+            }
+          });
         }
       }
     });