diff options
Diffstat (limited to 'platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java')
| -rw-r--r-- | platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java | 205 |
1 files changed, 159 insertions, 46 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..6edae8b944 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 @@ -96,6 +96,9 @@ public final class MapboxMap { setStyleUrl(options); } + /** + * Called when the hosting Activity/Fragment onStart() method is called. + */ void onStart() { nativeMapView.update(); trackingSettings.onStart(); @@ -105,10 +108,18 @@ public final class MapboxMap { } } + /** + * Called when the hosting Activity/Fragment onStop() method is called. + */ void onStop() { trackingSettings.onStop(); } + /** + * Called when the hosting Activity/Fragment is going to be destroyed and map state needs to be saved. + * + * @param outState the bundle to save the state to. + */ void onSaveInstanceState(Bundle outState) { outState.putParcelable(MapboxConstants.STATE_CAMERA_POSITION, transform.getCameraPosition()); outState.putBoolean(MapboxConstants.STATE_DEBUG_ACTIVE, nativeMapView.getDebug()); @@ -117,6 +128,11 @@ public final class MapboxMap { uiSettings.onSaveInstanceState(outState); } + /** + * Called when the hosting Activity/Fragment is recreated and map state needs to be restored. + * + * @param savedInstanceState the bundle containing the saved state + */ void onRestoreInstanceState(Bundle savedInstanceState) { final CameraPosition cameraPosition = savedInstanceState.getParcelable(MapboxConstants.STATE_CAMERA_POSITION); if (cameraPosition != null) { @@ -153,16 +169,23 @@ public final class MapboxMap { } /** - * Called when the user + * Called when the region is changing or has changed. */ - void onUpdate() { - CameraPosition cameraPosition = transform.invalidateCameraPosition(); - uiSettings.update(cameraPosition); - // FIXME introduce update method with camera position + void onUpdateRegionChange() { trackingSettings.update(); annotationManager.update(); } + /** + * Called when the map frame is fully rendered. + */ + void onUpdateFullyRendered() { + CameraPosition cameraPosition = transform.invalidateCameraPosition(); + if (cameraPosition != null) { + uiSettings.update(cameraPosition); + } + } + // Style /** @@ -815,10 +838,20 @@ public final class MapboxMap { transform.setBearing(bearing, focalX, focalY, duration); } + /** + * Returns the measured height of the Map. + * + * @return the height of the map + */ public float getHeight() { return nativeMapView.getHeight(); } + /** + * Returns the measured width of the Map. + * + * @return the width of the map + */ public float getWidth() { return nativeMapView.getWidth(); } @@ -881,35 +914,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 +996,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 +1006,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 +1013,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 +1036,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. + * @return The URL of the map style */ @UiThread - @NonNull + @Nullable public String getStyleUrl() { return nativeMapView.getStyleUrl(); } @@ -971,8 +1062,8 @@ public final class MapboxMap { * The marker's icon is rendered on the map at the location {@code Marker.position}. * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet. * - * @param markerOptions A marker options object that defines how to render the marker. - * @return The {@code Marker} that was added to the map. + * @param markerOptions A marker options object that defines how to render the marker + * @return The {@code Marker} that was added to the map */ @UiThread @NonNull @@ -987,8 +1078,8 @@ public final class MapboxMap { * The marker's icon is rendered on the map at the location {@code Marker.position}. * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet. * - * @param markerOptions A marker options object that defines how to render the marker. - * @return The {@code Marker} that was added to the map. + * @param markerOptions A marker options object that defines how to render the marker + * @return The {@code Marker} that was added to the map */ @UiThread @NonNull @@ -1003,8 +1094,8 @@ public final class MapboxMap { * The marker's icon is rendered on the map at the location {@code Marker.position}. * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet. * - * @param markerOptions A marker options object that defines how to render the marker. - * @return The {@code Marker} that was added to the map. + * @param markerOptions A marker options object that defines how to render the marker + * @return The {@code Marker} that was added to the map */ @UiThread @NonNull @@ -1012,7 +1103,6 @@ public final class MapboxMap { return annotationManager.addMarker(markerOptions, this, null); } - /** * <p> * Adds a marker to this map. @@ -1020,9 +1110,9 @@ public final class MapboxMap { * The marker's icon is rendered on the map at the location {@code Marker.position}. * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet. * - * @param markerOptions A marker options object that defines how to render the marker. - * @param onMarkerViewAddedListener Callback invoked when the View has been added to the map. - * @return The {@code Marker} that was added to the map. + * @param markerOptions A marker options object that defines how to render the marker + * @param onMarkerViewAddedListener Callback invoked when the View has been added to the map + * @return The {@code Marker} that was added to the map */ @UiThread @NonNull @@ -1032,7 +1122,14 @@ public final class MapboxMap { } /** - * FIXME javadoc + * Adds multiple markersViews to this map. + * <p> + * The marker's icon is rendered on the map at the location {@code Marker.position}. + * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet. + * </p> + * + * @param markerViewOptions A list of markerView options objects that defines how to render the markers + * @return A list of the {@code MarkerView}s that were added to the map */ @UiThread @NonNull @@ -1042,7 +1139,10 @@ public final class MapboxMap { } /** - * FIXME javadoc + * Returns markerViews found inside of a rectangle on this map. + * + * @param rect the rectangular area on the map to query for markerViews + * @return A list of the markerViews that were found in the rectangle */ @UiThread @NonNull @@ -1057,8 +1157,8 @@ public final class MapboxMap { * The marker's icon is rendered on the map at the location {@code Marker.position}. * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet. * - * @param markerOptionsList A list of marker options objects that defines how to render the markers. - * @return A list of the {@code Marker}s that were added to the map. + * @param markerOptionsList A list of marker options objects that defines how to render the markers + * @return A list of the {@code Marker}s that were added to the map */ @UiThread @NonNull @@ -1072,7 +1172,7 @@ public final class MapboxMap { * Updates a marker on this map. Does nothing if the marker isn't already added. * </p> * - * @param updatedMarker An updated marker object. + * @param updatedMarker An updated marker object */ @UiThread public void updateMarker(@NonNull Marker updatedMarker) { @@ -1082,8 +1182,8 @@ public final class MapboxMap { /** * Adds a polyline to this map. * - * @param polylineOptions A polyline options object that defines how to render the polyline. - * @return The {@code Polyine} that was added to the map. + * @param polylineOptions A polyline options object that defines how to render the polyline + * @return The {@code Polyine} that was added to the map */ @UiThread @NonNull @@ -1128,8 +1228,8 @@ public final class MapboxMap { /** * Adds multiple polygons to this map. * - * @param polygonOptionsList A list of polygon options objects that defines how to render the polygons. - * @return A list of the {@code Polygon}s that were added to the map. + * @param polygonOptionsList A list of polygon options objects that defines how to render the polygons + * @return A list of the {@code Polygon}s that were added to the map */ @UiThread @NonNull @@ -1137,11 +1237,10 @@ public final class MapboxMap { return annotationManager.addPolygons(polygonOptionsList, this); } - /** * Update a polygon on this map. * - * @param polygon An updated polygon object. + * @param polygon An updated polygon object */ @UiThread public void updatePolygon(Polygon polygon) { @@ -1152,7 +1251,7 @@ public final class MapboxMap { * <p> * Convenience method for removing a Marker from the map. * </p> - * Calls removeAnnotation() internally + * Calls removeAnnotation() internally. * * @param marker Marker to remove */ @@ -1165,7 +1264,7 @@ public final class MapboxMap { * <p> * Convenience method for removing a Polyline from the map. * </p> - * Calls removeAnnotation() internally + * Calls removeAnnotation() internally. * * @param polyline Polyline to remove */ @@ -1178,7 +1277,7 @@ public final class MapboxMap { * <p> * Convenience method for removing a Polygon from the map. * </p> - * Calls removeAnnotation() internally + * Calls removeAnnotation() internally. * * @param polygon Polygon to remove */ @@ -1558,6 +1657,11 @@ public final class MapboxMap { return annotationManager.getInfoWindowManager().getOnInfoWindowLongClickListener(); } + /** + * Set an callback to be invoked when an InfoWindow closes. + * + * @param listener callback invoked when an InfoWindow closes + */ public void setOnInfoWindowCloseListener(@Nullable OnInfoWindowCloseListener listener) { annotationManager.getInfoWindowManager().setOnInfoWindowCloseListener(listener); } @@ -1657,7 +1761,6 @@ public final class MapboxMap { * Takes a snapshot of the map. * * @param callback Callback method invoked when the snapshot is taken. - * @param bitmap A pre-allocated bitmap. */ @UiThread public void snapshot(@NonNull SnapshotReadyCallback callback) { @@ -2104,6 +2207,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 // |