[android] #5113 - added javadoc for MarkerViewManager

2 files changed, 112 insertions, 7 deletions

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 fcb7894d1b..03d554656a 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
@@ -18,6 +18,12 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Interface for interacting with ViewMarkers objects inside of a MapView.
+ * <p>
+ * This class is responsible for managing a {@link MarkerView} item.
+ * </p>
+ */
 public class MarkerViewManager {
 
     private Map<MarkerView, View> mMarkerViewMap;
@@ -27,6 +33,12 @@ public class MarkerViewManager {
     private long mViewMarkerBoundsUpdateTime;
     private MapboxMap.OnMarkerViewClickListener onMarkerViewClickListener;
 
+    /**
+     * Creates an instance of MarkerViewManager.
+     *
+     * @param mapboxMap the MapboxMap associated with the MarkerViewManager
+     * @param mapView   the MapView associarted with the MarkerViewManager
+     */
     public MarkerViewManager(@NonNull MapboxMap mapboxMap, @NonNull MapView mapView) {
         this.mapboxMap = mapboxMap;
         this.markerViewAdapters = new ArrayList<>();
@@ -34,6 +46,15 @@ public class MarkerViewManager {
         mMarkerViewMap = new HashMap<>();
     }
 
+    /**
+     * Animate a MarkerView to a given rotation.
+     * <p>
+     * The {@link MarkerView} will be rotated from its current rotation to the given rotation.
+     * </p>
+     *
+     * @param marker   the MarkerView to rotate
+     * @param rotation the rotation value
+     */
     public void animateRotation(@NonNull MarkerView marker, float rotation) {
         View convertView = mMarkerViewMap.get(marker);
         if (convertView != null) {
@@ -41,6 +62,15 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Animate a MarkerView to a given alpha value.
+     * <p>
+     * The {@link MarkerView} will be transformed from its current alpha value to the given value.
+     * </p>
+     *
+     * @param marker the MarkerView to change its alpha value
+     * @param alpha  the alpha value
+     */
     public void animateAlpha(@NonNull MarkerView marker, float alpha) {
         View convertView = mMarkerViewMap.get(marker);
         if (convertView != null) {
@@ -48,6 +78,15 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Animate a MarkerVIew to be visible or invisible
+     * <p>
+     * The {@link MarkerView} will be made {@link View#VISIBLE} or {@link View#GONE}.
+     * </p>
+     *
+     * @param marker  the MarkerView to change its visibility
+     * @param visible the flag indicating if MarkerView is visible
+     */
     public void animateVisible(@NonNull MarkerView marker, boolean visible) {
         View convertView = mMarkerViewMap.get(marker);
         if (convertView != null) {
@@ -55,6 +94,14 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Updates the position of MarkerViews currently found in the viewport.
+     * <p>
+     * The collection of {@link MarkerView} will be iterated and each item position will be updated.
+     * If an item is View state is not visible and its related flag is set to visible,
+     * The {@link MarkerView} will be animated to visible using alpha animation.
+     * </p>
+     */
     public void update() {
         View convertView;
         for (MarkerView marker : mMarkerViewMap.keySet()) {
@@ -63,8 +110,10 @@ public class MarkerViewManager {
                 PointF point = mapboxMap.getProjection().toScreenLocation(marker.getPosition());
                 int x = (int) (marker.getAnchorU() * convertView.getMeasuredWidth());
                 int y = (int) (marker.getAnchorV() * convertView.getMeasuredHeight());
+
                 marker.setOffsetX(x);
                 marker.setOffsetY(y);
+
                 convertView.setX(point.x - x);
                 convertView.setY(point.y - y);
 
@@ -77,6 +126,11 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Set tilt on every non flat MarkerView currently shown in the Viewport.
+     *
+     * @param tilt the tilt value
+     */
     public void setTilt(float tilt) {
         View convertView;
         for (MarkerView markerView : mMarkerViewMap.keySet()) {
@@ -90,6 +144,15 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Animate a MarkerView to a deselected state.
+     * <p>
+     * The {@link MarkerView#getDeselectAnimRes()} will be called to get the related animation.
+     * If non are provided, no animation will be started.
+     * </p>
+     *
+     * @param marker the MarkerView to deselect
+     */
     public void deselect(@NonNull MarkerView marker) {
         final View convertView = mMarkerViewMap.get(marker);
         if (convertView != null) {
@@ -100,6 +163,18 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Remove a MarkerView from a map.
+     * <p>
+     * The {@link MarkerView} will be removed using an alpha animation and related {@link View}
+     * will be released to the {@link android.support.v4.util.Pools.SimplePool} from the related
+     * {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter}. It's possible to remove
+     * the {@link MarkerView} from the underlying collection if needed.
+     * </p>
+     *
+     * @param marker        the MarkerView to remove
+     * @param removeFromMap flag indicating if a MarkerView will be removed from the collection.
+     */
     public void removeMarkerView(MarkerView marker, boolean removeFromMap) {
         final View viewHolder = mMarkerViewMap.get(marker);
         if (viewHolder != null && marker != null) {
@@ -127,6 +202,11 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Add a MarkerViewAdapter.
+     *
+     * @param markerViewAdapter the MarkerViewAdapter to add
+     */
     public void addMarkerViewAdapter(@Nullable MapboxMap.MarkerViewAdapter markerViewAdapter) {
         if (!markerViewAdapters.contains(markerViewAdapter)) {
             markerViewAdapters.add(markerViewAdapter);
@@ -134,15 +214,33 @@ public class MarkerViewManager {
         }
     }
 
-    public void setOnMarkerViewClickListener(@Nullable MapboxMap.OnMarkerViewClickListener listener) {
-        onMarkerViewClickListener = listener;
-    }
-
+    /**
+     * Get all MarkerViewAdapters associated with this MarkerViewManager.
+     *
+     * @return a List of MarkerViewAdapters
+     */
     public List<MapboxMap.MarkerViewAdapter> getMarkerViewAdapters() {
         return markerViewAdapters;
     }
 
-    public void invalidateViewMarkers() {
+
+    /**
+     * Register a callback to be invoked when this view is clicked.
+     *
+     * @param listener the callback to be invoked
+     */
+    public void setOnMarkerViewClickListener(@Nullable MapboxMap.OnMarkerViewClickListener listener) {
+        onMarkerViewClickListener = listener;
+    }
+
+    /**
+     * Schedule that ViewMarkers found in the viewport are invalidated.
+     * <p>
+     * This method is rate limited, and {@link #invalidateViewMarkersInBounds} will only be called
+     * once each 250 ms.
+     * </p>
+     */
+    public void scheduleViewMarkerInvalidation() {
         if (!markerViewAdapters.isEmpty()) {
             long currentTime = SystemClock.elapsedRealtime();
             if (currentTime < mViewMarkerBoundsUpdateTime) {
@@ -153,6 +251,13 @@ public class MarkerViewManager {
         }
     }
 
+    /**
+     * Invalidate the ViewMarkers found in the viewport.
+     * <p>
+     * This method will remove any markers that aren't in the viewport any more and will add new
+     * ones for each found Marker in the changed viewport.
+     * </p>
+     */
     public void invalidateViewMarkersInBounds() {
         Projection projection = mapboxMap.getProjection();
         List<MarkerView> markers = mapView.getMarkerViewsInBounds(projection.getVisibleRegion().latLngBounds);
@@ -216,7 +321,7 @@ public class MarkerViewManager {
                                     if (!clickHandled) {
                                         // InfoWindow offset
                                         int infoWindowOffsetX = (int) ((adaptedView.getWidth() * marker.getInfoWindowAnchorU()) - marker.getOffsetX());
-                                        int infoWindowOffsetY = (int) ((adaptedView.getHeight() * marker.getInfoWindowAnchorV()) -marker.getOffsetY());
+                                        int infoWindowOffsetY = (int) ((adaptedView.getHeight() * marker.getInfoWindowAnchorV()) - marker.getOffsetY());
                                         marker.setTopOffsetPixels(infoWindowOffsetY);
                                         marker.setRightOffsetPixels(infoWindowOffsetX);
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
index 36ecece61e..3f8dd863f3 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
@@ -447,7 +447,7 @@ public class MapView extends FrameLayout {
                         }
                     }
                 } else if (change == REGION_IS_CHANGING || change == REGION_DID_CHANGE || change == DID_FINISH_LOADING_MAP) {
-                    mMapboxMap.getMarkerViewManager().invalidateViewMarkers();
+                    mMapboxMap.getMarkerViewManager().scheduleViewMarkerInvalidation();
                 }
             }
         });