From 623fec368718608c76c457197b2ddf69f7837fba Mon Sep 17 00:00:00 2001 From: Leith Bade Date: Fri, 2 Oct 2015 08:55:25 +1000 Subject: [PATCH] [android] JavaDoc quest in MapView part 2 For #2002 --- .../gesturedetectors/package-info.java | 4 + .../mapbox/mapboxsdk/views/CompassView.java | 2 +- .../mapbox/mapboxsdk/views/InfoWindow.java | 2 +- .../mapboxsdk/views/InfoWindowTipView.java | 2 +- .../com/mapbox/mapboxsdk/views/MapView.java | 342 +++++++++++++++--- .../mapbox/mapboxsdk/views/NativeMapView.java | 2 +- .../mapboxsdk/testapp/MainActivity.java | 10 +- .../mapboxsdk/testapp/SecondMapActivity.java | 2 +- .../src/main/res/values/strings.xml | 6 - 9 files changed, 312 insertions(+), 60 deletions(-) create mode 100644 android/java/MapboxGLAndroidSDK/src/main/java/com/almeros/android/multitouch/gesturedetectors/package-info.java diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/almeros/android/multitouch/gesturedetectors/package-info.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/almeros/android/multitouch/gesturedetectors/package-info.java new file mode 100644 index 000000000..7f6245e88 --- /dev/null +++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/almeros/android/multitouch/gesturedetectors/package-info.java @@ -0,0 +1,4 @@ +/** + * Do not use this package. + */ +package com.almeros.android.multitouch.gesturedetectors; diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java index 423db4c9e..76cf7ed65 100644 --- a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java +++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/CompassView.java @@ -16,7 +16,7 @@ import com.mapbox.mapboxgl.views.R; import java.lang.ref.WeakReference; -public class CompassView extends ImageView implements SensorEventListener { +final class CompassView extends ImageView implements SensorEventListener { private CompassDelegate mCompassDelegate; diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindow.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindow.java index 3d612b6bd..385e37244 100644 --- a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindow.java +++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindow.java @@ -14,7 +14,7 @@ import com.mapbox.mapboxsdk.geometry.LatLng; /** * A tooltip view */ -public class InfoWindow { +public final class InfoWindow { private Marker boundMarker; private MapView mMapView; diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindowTipView.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindowTipView.java index 7c06643b6..a12587dd8 100644 --- a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindowTipView.java +++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InfoWindowTipView.java @@ -8,7 +8,7 @@ import android.graphics.Path; import android.util.AttributeSet; import android.view.View; -public class InfoWindowTipView extends View { +public final class InfoWindowTipView extends View { private Paint mPaint; private Path mPath; diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java index a9be93a8c..0755c9277 100644 --- a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java +++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java @@ -74,18 +74,20 @@ import java.util.List; /** - *

A {@link MapView} provides an embeddable map interface, similar to the one provided by Google's Google Maps API. + * A {@link MapView} provides an embeddable map interface, similar to the one provided by the Google Maps API. * You use this class to display map information and to manipulate the map contents from your application. * You can center the map on a given coordinate, specify the size of the area you want to display, - * and style the features of the map to fit your application’s use case.

+ * and style the features of the map to fit your application's use case. *

- *

Use of {@link MapView} requires a Mapbox API access token. - * Obtain an access token on the Mapbox account page.

+ * Use of {@link MapView} requires a Mapbox API access token. + * Obtain an access token on the Mapbox account page. *

- *

Warning: Please note that you are responsible for getting permission to use the map data, - * and for ensuring your use adheres to the relevant terms of use.

+ * Warning: Please note that you are responsible for getting permission to use the map data, + * and for ensuring your use adheres to the relevant terms of use. + * + * @see MapView#setAccessToken(String) */ -public class MapView extends FrameLayout implements LocationListener, CompassView.CompassDelegate { +public final class MapView extends FrameLayout implements LocationListener, CompassView.CompassDelegate { // // Static members @@ -210,18 +212,56 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie private String mStyleUrl; private boolean mIsMyLocationEnabled = false; + // + // Inner classes + // + + // These provide easy access to the bundled styles + + /** + * StyleUrls provides URLs to several professional styles designed by Mapbox. + *

+ * These styles are all ready to go in your app. To load one, pass it into {@link MapView#setStyleUrl(String)} + * + * @see MapView#setStyleUrl(String) + */ + public static final class StyleUrls { + private StyleUrls() { + } + + /** + * Mapbox Streets: Our signature style. + */ + public static final String MAPBOX_STREETS = "asset://styles/streets-v8.json"; + /** + * Emerald: Great for transportation and outdoor terrain. + */ + public static final String EMERALD = "asset://styles/emerald-v8.json"; + /** + * Light: Light-colored style that is great for data overlay. + */ + public static final String LIGHT = "asset://styles/light-v8.json"; + /** + * Dark: Dark-colored style that is great for data overlay. + */ + public static final String DARK = "asset://styles/dark-v8.json"; + /** + * Satellite: The best-looking, most accurate, and most up-to-date satellite imagery available anywhere. + */ + public static final String SATELLITE = "asset://styles/satellite-v8.json"; + } + // // Enums // /** - * Map change event types received by - * {@link com.mapbox.mapboxsdk.views.MapView.OnMapChangedListener#onMapChanged(MapChange)} + * Map change event types. + * + * @see MapView.OnMapChangedListener#onMapChanged(MapChange) */ public enum MapChange { - /** - * TODO pull descriptions from C++ - */ + // TODO pull descriptions from C++ RegionWillChange, RegionWillChangeAnimated, RegionIsChanging, @@ -280,6 +320,8 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie /** * Interface definition for a callback to be invoked when the map is flinged. + * + * @see MapView#setOnFlingListener(OnFlingListener) */ public interface OnFlingListener { /** @@ -290,6 +332,8 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie /** * Interface definition for a callback to be invoked when the map is scrolled. + * + * @see MapView#setOnScrollListener(OnScrollListener) */ public interface OnScrollListener { /** @@ -298,6 +342,35 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie void onScroll(); } + /** + * Interface definition for a callback to be invoked on every frame rendered to the map view. + * + * @see MapView#setOnFpsChangedListener(OnFpsChangedListener) + */ + public interface OnFpsChangedListener { + /** + * Called for every frame rendered to the map view. + * + * @param fps The average number of frames rendered over the last second. + */ + void onFpsChanged(double fps); + } + + /** + * Interface definition for a callback to be invoked when the displayed map view changes. + * + * @see MapView#addOnMapChangedListener(OnMapChangedListener) + * @see MapView.MapChange + */ + public interface OnMapChangedListener { + /** + * Called when the displayed map view changes. + * + * @param change The type of map change event. + */ + void onMapChanged(MapChange change); + } + // // Constructors // @@ -318,6 +391,7 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie } initialize(context, null); setAccessToken(accessToken); + setStyleUrl(null); } /** @@ -326,7 +400,8 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie * @param context The {@link Context} of the {@link android.app.Activity} * or {@link android.app.Fragment} the {@link MapView} is running in. * @param accessToken Your public Mapbox access token. Used to load map styles and tiles. - * @param styleUrl A URL to the map style initially displayed. + * @param styleUrl A URL to the map style initially displayed. See {@link MapView#setStyleUrl(String)} for possible values. + * @see MapView#setStyleUrl(String) */ @UiThread public MapView(@NonNull Context context, @NonNull String accessToken, @NonNull String styleUrl) { @@ -762,10 +837,14 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie } /** - *

Centers the map on a new coordinate immediately without changing the zoom level.

- *

If you want to animate the change, use {@link MapView#setCenterCoordinate(LatLng, boolean)}.

+ * Centers the map on a new coordinate immediately without changing the zoom level. + *

+ * The initial coordinate is (0, 0). + *

+ * If you want to animate the change, use {@link MapView#setCenterCoordinate(LatLng, boolean)}. * * @param centerCoordinate The new coordinate. + * @see MapView#setCenterCoordinate(LatLng, boolean) */ @UiThread public void setCenterCoordinate(@NonNull LatLng centerCoordinate) { @@ -774,6 +853,8 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie /** * Centers the map on a new coordinate without changing the zoom level and optionally animates the change. + *

+ * The initial coordinate is (0, 0). * * @param centerCoordinate The new coordinate. * @param animated If true, animates the change. If false, immediately changes the map. @@ -790,18 +871,34 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie /** - *

Centers the map on a new coordinate immediately while changing the current zoom level.

- *

If you want to animate the change, use {@link MapView#setCenterCoordinate(LatLngZoom, boolean)}.

+ * Centers the map on a new coordinate immediately while changing the current zoom level. + *

+ * The initial value is a center coordinate of (0, 0) and a zoom level of 0. + *

+ * If you want to animate the change, use {@link MapView#setCenterCoordinate(LatLngZoom, boolean)}. * * @param centerCoordinate The new coordinate and zoom level. + * @see MapView#setCenterCoordinate(LatLngZoom, boolean) */ @UiThread public void setCenterCoordinate(@NonNull LatLngZoom centerCoordinate) { setCenterCoordinate(centerCoordinate, false); } + /** + * Resets the map to the minimum zoom level, a center coordinate of (0, 0), a true north heading, + * and animates the change. + */ + @UiThread + public void resetPosition() { + mNativeMapView.cancelTransitions(); + mNativeMapView.resetPosition(); + } + /** * Centers the map on a new coordinate while changing the zoom level and optionally animates the change. + *

+ * The initial value is a center coordinate of (0, 0) and a zoom level of 0. * * @param centerCoordinate The new coordinate and zoom level. * @param animated If true, animates the change. If false, immediately changes the map. @@ -820,7 +917,7 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie /** * Returns whether the user may scroll around the map. * - * @return If true, scrolling is enabled. If false, scrolling is disabled. + * @return If true, scrolling is enabled. */ @UiThread public boolean isScrollEnabled() { @@ -828,11 +925,14 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie } /** - *

Changes whether the user may scroll around the map.

- *

This setting controls only user interactions with the map. If you set the value to false, - * you may still change the map location programmatically.

+ * Changes whether the user may scroll around the map. + *

+ * This setting controls only user interactions with the map. If you set the value to false, + * you may still change the map location programmatically. + *

+ * The default value is true. * - * @param scrollEnabled If true, scrolling is enabled. If false, scrolling is disabled. + * @param scrollEnabled If true, scrolling is enabled. */ @UiThread public void setScrollEnabled(boolean scrollEnabled) { @@ -843,6 +943,12 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie // Rotation // + /** + * Returns the current heading of the map relative to true north. + * + * @return The current heading measured in degrees. + */ + @UiThread public double getDirection() { double direction = -mNativeMapView.getBearing(); @@ -856,30 +962,76 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie return direction; } + /** + * Rotates the map to a new heading relative to true north immediately. + *

+ * The value 0 means that the top edge of the map view will correspond to true north.
+ * The value 90 means the top of the map will point due east.
+ * The value 180 means the top of the map will point due south.
+ * The value 270 means the top of the map will point due west. + *

+ * The initial heading is 0. + *

+ * If you want to animate the change, use {@link MapView#setDirection(double, boolean)}. + * + * @param direction The new heading measured in degrees. + * @see MapView#setDirection(double, boolean) + */ + @UiThread public void setDirection(double direction) { setDirection(direction, false); } + /** + * Rotates the map to a new heading relative to true north and optionally animates the change. + *

+ * The value 0 means that the top edge of the map view will correspond to true north.
+ * The value 90 means the top of the map will point due east.
+ * The value 180 means the top of the map will point due south.
+ * The value 270 means the top of the map will point due west + *

+ * The initial heading is 0. + * + * @param direction The new heading measured in degrees from true north. + * @param animated If true, animates the change. If false, immediately changes the map. + */ + @UiThread public void setDirection(double direction, boolean animated) { long duration = animated ? ANIMATION_DURATION : 0; mNativeMapView.cancelTransitions(); mNativeMapView.setBearing(-direction, duration); } - public void resetPosition() { - mNativeMapView.cancelTransitions(); - mNativeMapView.resetPosition(); - } - + /** + * Resets the map heading to true north and animates the change. + */ + @UiThread public void resetNorth() { mNativeMapView.cancelTransitions(); mNativeMapView.resetNorth(); } + /** + * Returns whether the user may rotate the map. + * + * @return If true, rotating is enabled. + */ + @UiThread public boolean isRotateEnabled() { return mRotateEnabled; } + /** + * Changes whether the user may rotate the map. + *

+ * This setting controls only user interactions with the map. If you set the value to false, + * you may still change the map location programmatically. + *

+ * The default value is true. + * + * @param rotateEnabled If true, rotating is enabled. + */ + @UiThread public void setRotateEnabled(boolean rotateEnabled) { this.mRotateEnabled = rotateEnabled; } @@ -888,24 +1040,75 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie // Scale // + /** + * Returns the current zoom level of the map view. + * + * @return The current zoom level. + */ + @UiThread public double getZoomLevel() { return mNativeMapView.getZoom(); } + /** + * Zooms the map to a new zoom level immediately without changing the center coordinate. + *

+ * At zoom level 0, tiles cover the entire world map; + * at zoom level 1, tiles cover ¼ of the world; + * at zoom level 2, tiles cover 1/16 of the world, and so on. + *

+ * The initial zoom level is 0. + *

+ * If you want to animate the change, use {@link MapView#setZoomLevel(double, boolean)}. + * + * @param zoomLevel The new coordinate. + * @see MapView#setZoomLevel(double, boolean) + */ + @UiThread public void setZoomLevel(double zoomLevel) { setZoomLevel(zoomLevel, false); } + /** + * Zooms the map to a new zoom level and optionally animates the change without changing the center coordinate. + *

+ * At zoom level 0, tiles cover the entire world map; + * at zoom level 1, tiles cover ¼ of the world; + * at zoom level 2, tiles cover 1/16 of the world, and so on. + *

+ * The initial zoom level is 0. + * + * @param zoomLevel The new coordinate. + * @param animated If true, animates the change. If false, immediately changes the map. + */ + @UiThread public void setZoomLevel(double zoomLevel, boolean animated) { long duration = animated ? ANIMATION_DURATION : 0; mNativeMapView.cancelTransitions(); mNativeMapView.setZoom(zoomLevel, duration); } + /** + * Returns whether the user may zoom the map. + * + * @return If true, zooming is enabled. + */ + @UiThread public boolean isZoomEnabled() { return mZoomEnabled; } + /** + * Changes whether the user may zoom the map. + *

+ * This setting controls only user interactions with the map. If you set the value to false, + * you may still change the map location programmatically. + *

+ * The default value is true. + * + * @param zoomEnabled If true, zooming is enabled. + */ + @UiThread public void setZoomEnabled(boolean zoomEnabled) { this.mZoomEnabled = zoomEnabled; @@ -926,7 +1129,6 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie if (zoomIn) { mNativeMapView.scaleBy(2.0, x / mScreenDensity, y / mScreenDensity, ANIMATION_DURATION); } else { - // TODO two finger tap zoom out mNativeMapView.scaleBy(0.5, x / mScreenDensity, y / mScreenDensity, ANIMATION_DURATION); } } @@ -935,21 +1137,44 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie // Debug // + /** + * Returns whether the map debug information is currently shown. + * + * @return If true, map debug information is currently shown. + */ + @UiThread public boolean isDebugActive() { return mNativeMapView.getDebug() || mNativeMapView.getCollisionDebug(); } + /** + * Changes whether the map debug information is shown. + *

+ * The default value is false. + * + * @param debugActive If true, map debug information is shown. + */ + @UiThread public void setDebugActive(boolean debugActive) { mNativeMapView.setDebug(debugActive); mNativeMapView.setCollisionDebug(debugActive); } + /** + * Toggles whether the map debug information is shown. + *

+ * The value of {@link MapView#isDebugActive()} is toggled. + * + * @see MapView#isDebugActive() + */ + @UiThread public void toggleDebug() { mNativeMapView.toggleDebug(); mNativeMapView.toggleCollisionDebug(); } - public boolean isFullyLoaded() { + // True if map has finished loading the view + private boolean isFullyLoaded() { return mNativeMapView.isFullyLoaded(); } @@ -957,11 +1182,51 @@ public class MapView extends FrameLayout implements LocationListener, CompassVie // Styling // - public void setStyleUrl(String url) { + /** + * Loads a new map style from the specified URL. + *

+ * {@code url} can take the following forms: + *