diff options
author | Tobrun Van Nuland <tobrun.van.nuland@gmail.com> | 2016-05-27 08:36:41 +0200 |
---|---|---|
committer | Brad Leege <bleege@gmail.com> | 2016-05-27 10:25:55 -0500 |
commit | d5cd1e1f9de83894a0d1928cad61a5902a715abb (patch) | |
tree | 6a389425712b81b657082385ab67cf2315bf4257 /platform | |
parent | f75b4f15dd33be3bcd30ec0138f06b1441469987 (diff) | |
download | qtlocation-mapboxgl-d5cd1e1f9de83894a0d1928cad61a5902a715abb.tar.gz |
[android] #5113 - added javadoc to the MarkerView API
Diffstat (limited to 'platform')
5 files changed, 388 insertions, 7 deletions
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java index 892eee1806..0cd54fc0f0 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerViewOptions.java @@ -10,9 +10,10 @@ import com.mapbox.mapboxsdk.geometry.LatLng; * Abstract builder class for composing custom MarkerView objects. * <p> * Extending this class requires implementing Parceable interface. + * </p> * * @param <U> Type of the marker view to be composed - * @param <T> Type of the builder to be used for composing a custom Marker + * @param <T> Type of the builder to be used for composing */ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends BaseMarkerViewOptions<U, T>> implements Parcelable { @@ -30,120 +31,265 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base protected int rotation; protected boolean visible = true; + /** + * Default constructor + */ public BaseMarkerViewOptions() { } + /** + * Set the geographical location of the MarkerView. + * + * @param position the location to position the MarkerView + * @return the object for which the method was called + */ public T position(@NonNull LatLng position) { this.position = position; return getThis(); } + /** + * Set the snippet of the MarkerView. + * + * @param snippet the snippet of the MarkerView + * @return the object for which the method was called + */ public T snippet(String snippet) { this.snippet = snippet; return getThis(); } + /** + * Set the title of the MarkerView. + * + * @param title the title of the MarkerView + * @return the object for which the method was called + */ public T title(String title) { this.title = title; return getThis(); } + /** + * Set the icon of the MarkerView. + * + * @param icon the icon of the MarkerView + * @return the object for which the method was called + */ public T icon(Icon icon) { this.icon = icon; return getThis(); } + /** + * Set the flat state of the MarkerView. + * + * @param flat the flat state of the MarkerView + * @return the object for which the method was called + */ public T flat(boolean flat) { this.flat = flat; return getThis(); } + /** + * Set the anchor of the MarkerView. + * + * @param u the u-value + * @param v the v-value + * @return the object for which the method was called + */ public T anchor(float u, float v) { this.anchorU = u; this.anchorV = v; return getThis(); } + /** + * Set the InfoWindow anchor of the MarkerView. + * + * @param u the u-value + * @param v the v-values + * @return the object for which the method was called + */ public T infoWindowAnchor(float u, float v) { this.infoWindowAnchorU = u; this.infoWindowAnchorV = v; return getThis(); } + /** + * Set the animator resource to be used when an MarkerView is selected. + * + * @param selectAnimRes the used animator resource + * @return the object for which the method was called + */ public T selectAnimatorResource(@AnimatorRes int selectAnimRes) { this.selectAnimRes = selectAnimRes; return getThis(); } + /** + * Set the animator resource to be used when an MarkerView is deselected. + * + * @param deselectAnimRes the used animator resource + * @return the object for which the method was called + */ public T deselectAnimatorResource(@AnimatorRes int deselectAnimRes) { this.deselectAnimRes = deselectAnimRes; return getThis(); } + /** + * Set the rotation of the MarkerView. + * + * @param rotation the rotation value + * @return the object for which the method was called + */ public T rotation(int rotation) { this.rotation = rotation; return getThis(); } - public T visible(boolean visible){ + /** + * Set the visibility state of the MarkerView. + * + * @param visible the visible state + * @return the object for which the method was calleds + */ + public T visible(boolean visible) { this.visible = visible; return getThis(); } + /** + * Get the geographical location of the MarkerView. + * + * @return the geographical location + */ public LatLng getPosition() { return position; } + /** + * Get the snippet of the MarkerView. + * + * @return the snippet + */ public String getSnippet() { return snippet; } + /** + * Get the title of the MarkerView. + * + * @return the title + */ public String getTitle() { return title; } + /** + * Get the icon of the MarkerView. + * + * @return the icon + */ public Icon getIcon() { return icon; } + /** + * Get the flat state of the MarkerView. + * + * @return the flat state + */ public boolean isFlat() { return flat; } + /** + * Get the u-value of the MarkerView anchor. + * + * @return the u-value + */ public float getAnchorU() { return anchorU; } + /** + * Get the v-value of the MarkerView anchor. + * + * @return the v-value + */ public float getAnchorV() { return anchorV; } + /** + * Get the u-value of the MarkerView InfoWindow anchor. + * + * @return the u-value + */ public float getInfoWindowAnchorU() { return infoWindowAnchorU; } + /** + * Get the v-value of the MarkerView InfoWindow anchor. + * + * @return the v-value + */ public float getInfoWindowAnchorV() { return infoWindowAnchorV; } + /** + * Get the animator resource used for selecting the MarkerView. + * + * @return the animator resource + */ public int getSelectAnimRes() { return selectAnimRes; } + /** + * Get the animator resource used for deselecting the MarkerView. + * + * @return the animator resource + */ public int getDeselectAnimRes() { return deselectAnimRes; } + /** + * Get the rotation of the MarkerView. + * + * @return the rotation value + */ public int getRotation() { return rotation; } + /** + * Get the visibility state of the MarkerView. + * + * @return the visibility state + */ public boolean isVisible() { return visible; } + /** + * Get the instance of the object for which this method was called. + * + * @return the object for which the this method was called + */ public abstract T getThis(); + /** + * Get the MarkerView. + * + * @return the MarkerView created from this builder + */ public abstract U getMarker(); - } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java index 87209e3f01..3e51044643 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerView.java @@ -2,6 +2,16 @@ package com.mapbox.mapboxsdk.annotations; import com.mapbox.mapboxsdk.maps.MapboxMap; +/** + * MarkerView is an annotation that shows an View at a geographical location. + * <p> + * This class uses {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter} to adapt a + * MarkerView model to an Android SDK {@link android.view.View} object. + * </p> + * <p> + * An {@link InfoWindow} can be shown when a MarkerView is pressed + * </p> + */ public class MarkerView extends Marker { private MarkerViewManager markerViewManager; @@ -25,9 +35,17 @@ public class MarkerView extends Marker { private float rotation; private float alpha = 1; + /** + * Publicly hidden default constructor + */ MarkerView() { } + /** + * Creates a instance of MarkerView using the builder of MarkerView + * + * @param baseMarkerViewOptions the builder used to construct the MarkerView + */ public MarkerView(BaseMarkerViewOptions baseMarkerViewOptions) { super(baseMarkerViewOptions); this.anchorU = baseMarkerViewOptions.getAnchorU(); @@ -43,80 +61,194 @@ public class MarkerView extends Marker { this.anchorV = baseMarkerViewOptions.anchorV; } + /** + * Specifies the anchor being set on a particular point point of the MarkerView. + * <p> + * The anchor point is specified in the continuous space [0.0, 1.0] x [0.0, 1.0], where (0, 0) + * is the top-left corner of the image, and (1, 1) is the bottom-right corner. + * </p> + * + * @param u u-coordinate of the anchor, as a ratio of the image width (in the range [0, 1]) + * @param v v-coordinate of the anchor, as a ratio of the image height (in the range [0, 1]) + */ public void setAnchor(float u, float v) { this.anchorU = u; this.anchorV = v; } + /** + * Get the horizontal distance, normalized to [0, 1], of the anchor from the left edge. + * + * @return the u-value of the anchor + */ public float getAnchorU() { return anchorU; } + /** + * Get the vertical distance, normalized to [0, 1], of the anchor from the top edge. + * + * @return the v-value of the anchor + */ public float getAnchorV() { return anchorV; } - void setOffsetX(float x){ + /** + * Internal method to set the horizontal calculated offset. + * <p> + * These are calculated based on the View bounds and the provided anchor. + * </p> + * + * @param x the x-value of the offset + */ + void setOffsetX(float x) { offsetX = x; } - void setOffsetY(float y){ + /** + * Internal method to set the vertical calculated offset. + * <p> + * These are calculated based on the View bounds and the provided anchor. + * </p> + * + * @param y the y-value of the offset + */ + void setOffsetY(float y) { offsetY = y; } + /** + * Internal method to get the horizontal calculated offset + * + * @return the calculated horizontal offset + */ float getOffsetX() { return offsetX; } + /** + * Internal method to get the vertical calculated offset + * + * @return the calculated vertical offset + */ float getOffsetY() { return offsetY; } + /** + * Specifies the anchor point of the info window on the View of the MarkerView. + * <p> + * This is specified in the same coordinate system as the anchor. + * </p> + * <p> + * The default is the top middle of the View. + * </p> + * + * @param u u-coordinate of the info window anchor, as a ratio of the image width (in the range [0, 1]) + * @param v v-coordinate of the info window anchor, as a ratio of the image height (in the range [0, 1]) + * @see #setAnchor(float, float) for more details. + */ public void setInfoWindowAnchor(float u, float v) { this.infoWindowAnchorU = u; this.infoWindowAnchorV = v; } + /** + * Get the horizontal distance, normalized to [0, 1], of the info window anchor from the left edge. + * + * @return the u value of the InfoWindow anchor. + */ public float getInfoWindowAnchorU() { return infoWindowAnchorU; } + /** + * Get the vertical distance, normalized to [0, 1], of the info window anchor from the top edge. + * + * @return the v value of the InfoWindow anchor. + */ public float getInfoWindowAnchorV() { return infoWindowAnchorV; } + /** + * Get the flat state of a MarkerView. + * + * @return true is the MarkerView is flat; false is the MarkerView is billboard + */ public boolean isFlat() { return flat; } + /** + * Sets whether this marker should be flat against the map true or a billboard facing the camera false. + * + * @param flat the flat state of the MarkerView + */ public void setFlat(boolean flat) { this.flat = flat; } + /** + * Get the animator resource used to animate to the selected state of a MarkerView. + * + * @return the animator resource used + */ public int getSelectAnimRes() { return selectAnimRes; } + /** + * Set the animator resource used to animate to the deselected state of a MarkerView. + * + * @param selectAnimRes the animator resource used + */ public void setSelectAnimRes(int selectAnimRes) { this.selectAnimRes = selectAnimRes; } + /** + * Get the animator resource used to animate to the deslected state of a MarkerView. + * + * @return the animator resource used + */ public int getDeselectAnimRes() { return deselectAnimRes; } + /** + * Set the animator resource used to animate to the selected state of a MarkerView. + * + * @param deselectAnimRes the animator resource used + */ public void setDeselectAnimRes(int deselectAnimRes) { this.deselectAnimRes = deselectAnimRes; } + /** + * Internal method to get the current tilted value of a MarkerView. + * + * @return the tilted value + */ float getTilt() { return tiltValue; } + /** + * Internal method to set the current titled value of a MarkerView. + * + * @param tiltValue the tilted value to set + */ void setTilt(float tiltValue) { this.tiltValue = tiltValue; } + /** + * Set the visible state of a MarkerView. + * + * @param visible true will make the MarkerView visible, false will hide the MarkerViews + */ public void setVisible(boolean visible) { this.visible = visible; if (markerViewManager != null) { @@ -124,10 +256,24 @@ public class MarkerView extends Marker { } } + /** + * Returns the visible state of the MarkerView. + * + * @return the visible state + */ public boolean isVisible() { return visible; } + /** + * Set the rotation value of the MarkerView. + * <p> + * This will result in animating the rotation of the MarkerView using an rotation animator + * from current value to the provided parameter value. + * </p> + * + * @param rotation the rotation value to animate to + */ public void setRotation(float rotation) { this.rotation = rotation; if (markerViewManager != null) { @@ -135,14 +281,33 @@ public class MarkerView extends Marker { } } + /** + * Get the rotation value of the MarkerView. + * + * @return the rotation value + */ public float getRotation() { return rotation; } + /** + * Get the alpha value of the MarkerView. + * + * @return the alpha value + */ public float getAlpha() { return alpha; } + /** + * Set the alpha value of the MarkerView. + * <p> + * This will result in animating the alpha of the MarkerView using an alpha animator + * from current value to the provided parameter value. + * </p> + * + * @param alpha the alpha value to animate to + */ public void setAlpha(float alpha) { this.alpha = alpha; if (markerViewManager != null) { @@ -150,12 +315,25 @@ public class MarkerView extends Marker { } } + /** + * Set the MapboxMap associated tot the MapView containing the MarkerView. + * <p> + * This method is used to instantiate the MarkerView and provide an instance of {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter} + * </p> + * + * @param mapboxMap the MapboxMap instances + */ @Override public void setMapboxMap(MapboxMap mapboxMap) { super.setMapboxMap(mapboxMap); markerViewManager = mapboxMap.getMarkerViewManager(); } + /** + * Get the String representation of a MarkerView. + * + * @return the String representation + */ @Override public String toString() { return "MarkerView [position[" + getPosition() + "]]"; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java index 03d554656a..d9fc9e62ae 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java @@ -37,7 +37,7 @@ public class MarkerViewManager { * Creates an instance of MarkerViewManager. * * @param mapboxMap the MapboxMap associated with the MarkerViewManager - * @param mapView the MapView associarted with the MarkerViewManager + * @param mapView the MapView associated with the MarkerViewManager */ public MarkerViewManager(@NonNull MapboxMap mapboxMap, @NonNull MapView mapView) { this.mapboxMap = mapboxMap; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java index a688a8b1a9..0c9faed355 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewOptions.java @@ -6,6 +6,12 @@ import android.os.Parcelable; import com.mapbox.mapboxsdk.geometry.LatLng; +/** + * builder class for composing MarkerView objects. + * <p> + * Do not extend this class directly but extend BaseMarkerViewOptions instead. + * </p> + */ public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerViewOptions> { private MarkerView marker; 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 19cd2aebc8..a19588b8c4 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 @@ -1214,6 +1214,11 @@ public class MapboxMap { return marker; } + /** + * Get the MarkerViewManager associated to the MapView. + * + * @return the associated MarkerViewManager + */ public MarkerViewManager getMarkerViewManager() { return mMarkerViewManager; } @@ -1803,12 +1808,22 @@ public class MapboxMap { View getInfoWindow(@NonNull Marker marker); } + /** + * Interface definition for a callback to be invoked when an MarkerView will be shown. + * + * @param <U> the instance type of MarkerView + */ public static abstract class MarkerViewAdapter<U extends MarkerView> { private Context context; private final Class<U> persistentClass; private final Pools.SimplePool<View> mViewReusePool; + /** + * Create an instance of MarkerViewAdapter. + * + * @param context the context associated to a MapView + */ @SuppressWarnings("unchecked") public MarkerViewAdapter(Context context) { this.context = context; @@ -1816,24 +1831,60 @@ public class MapboxMap { mViewReusePool = new Pools.SimplePool<>(20); } + /** + * Called when an MarkerView will be added to the MapView. + * + * @param marker the model representing the MarkerView + * @param convertView the reusable view + * @param parent the parent ViewGroup of the convertview + * @return the View that is adapted to the contents of MarkerView + */ @Nullable public abstract View getView(@NonNull U marker, @NonNull View convertView, @NonNull ViewGroup parent); + /** + * Returns the generic type of the used MarkerView. + * + * @return the generic type + */ public Class<U> getMarkerClass() { return persistentClass; } + /** + * Returns the pool used to store reusable Views. + * + * @return the pool associated to this adapter + */ public Pools.SimplePool<View> getViewReusePool() { return mViewReusePool; } + /** + * Returns the context associated to the hosting MapView. + * + * @return the context used + */ public Context getContext() { return context; } } + /** + * Interface definition for a callback to be invoked when the user clicks on a MarkerView. + * + * @see MarkerViewManager#setOnMarkerViewClickListener(OnMarkerViewClickListener) + */ public interface OnMarkerViewClickListener { + /** + * Called when the user clicks on a MarkerView. + * + * @param marker the MarkerView associated to the clicked View + * @param view the clicked View + * @param adapter the adapter used to adapt the MarkerView to the View + * @return If true the listener has consumed the event and the info window will not be shown + */ boolean onMarkerClick(@NonNull Marker marker, @NonNull View view, @NonNull MarkerViewAdapter adapter); } @@ -1905,7 +1956,7 @@ public class MapboxMap { public interface SnapshotReadyCallback { /** * Invoked when the snapshot has been taken. - **/ + */ void onSnapshotReady(Bitmap snapshot); } |