diff options
Diffstat (limited to 'platform')
19 files changed, 782 insertions, 203 deletions
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java index d7df692e17..40b330b8c2 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java @@ -35,12 +35,15 @@ public abstract class Annotation implements Comparable<Annotation> { * This ID is unique for a MapView instance and is suitable for associating your own extra * data with. * - * @return the assigned id + * @return the assigned id. */ public long getId() { return id; } + /** + * Do not use this method, used internally by the SDK. + */ public void remove() { if (mapboxMap == null) { return; @@ -49,7 +52,7 @@ public abstract class Annotation implements Comparable<Annotation> { } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. * * @param id the assigned id */ @@ -58,7 +61,7 @@ public abstract class Annotation implements Comparable<Annotation> { } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. * * @param mapboxMap the hosting mapbox map */ @@ -76,7 +79,7 @@ public abstract class Annotation implements Comparable<Annotation> { } /** - * Don not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. * * @param mapView the hosting map view */ @@ -103,6 +106,14 @@ public abstract class Annotation implements Comparable<Annotation> { return 0; } + /** + * Compares this {@link PolylineOptions} object with another {@link PolylineOptions} and + * determines if their color, alpha, width, and vertices match. + * + * @param o Another {@link PolylineOptions} to compare with this object. + * @return True if color, alpha, width, and vertices match this {@link PolylineOptions} object. + * Else, false. + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -111,6 +122,14 @@ public abstract class Annotation implements Comparable<Annotation> { return id == that.getId(); } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { return (int) (getId() ^ (getId() >>> 32)); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerOptions.java index 3adeb52ea7..4e56531a7f 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BaseMarkerOptions.java @@ -19,44 +19,102 @@ public abstract class BaseMarkerOptions<U extends Marker, T extends BaseMarkerOp protected String title; protected Icon icon; + /** + * Set the geographical location of the Marker. + * + * @param position the location to position the {@link Marker}. + * @return the object for which the method was called. + */ public T position(LatLng position) { this.position = position; return getThis(); } + /** + * Set the snippet of the Marker. + * + * @param snippet the snippet of the {@link Marker}. + * @return the object for which the method was called. + */ public T snippet(String snippet) { this.snippet = snippet; return getThis(); } + /** + * Set the title of the Marker. + * + * @param title the title of the {@link Marker}. + * @return the object for which the method was called. + */ public T title(String title) { this.title = title; return getThis(); } + /** + * Set the icon of the Marker. + * + * @param icon the icon of the {@link Marker}. + * @return the object for which the method was called. + */ public T icon(Icon icon) { this.icon = icon; return getThis(); } + /** + * Set the icon of the Marker. + * + * @param icon the icon of the {@link Marker}. + * @return the object for which the method was called. + */ public T setIcon(Icon icon) { return icon(icon); } + /** + * Set the geographical location of the Marker. + * + * @param position the location to position the {@link Marker}. + * @return the object for which the method was called. + */ public T setPosition(LatLng position) { return position(position); } + /** + * Set the snippet of the Marker. + * + * @param snippet the snippet of the {@link Marker}. + * @return the object for which the method was called. + */ public T setSnippet(String snippet) { return snippet(snippet); } + /** + * Set the title of the Marker. + * + * @param title the title of the {@link Marker}. + * @return the object for which the method was called. + */ public T setTitle(String title) { return title(title); } + /** + * 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 Marker. + * + * @return the Marker created from this builder. + */ public abstract U getMarker(); } 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 d4eb390ab2..e93f2c801d 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 @@ -12,8 +12,8 @@ import com.mapbox.mapboxsdk.geometry.LatLng; * 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 + * @param <U> Type of the marker view to be composed. + * @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 { @@ -40,8 +40,8 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Set the geographical location of the MarkerView. * - * @param position the location to position the MarkerView - * @return the object for which the method was called + * @param position the location to position the {@link MarkerView}. + * @return the object for which the method was called. */ public T position(@NonNull LatLng position) { this.position = position; @@ -51,8 +51,8 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Set the snippet of the MarkerView. * - * @param snippet the snippet of the MarkerView - * @return the object for which the method was called + * @param snippet the snippet of the {@link MarkerView}. + * @return the object for which the method was called. */ public T snippet(String snippet) { this.snippet = snippet; @@ -62,8 +62,8 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Set the title of the MarkerView. * - * @param title the title of the MarkerView - * @return the object for which the method was called + * @param title the title of the {@link MarkerView}. + * @return the object for which the method was called. */ public T title(String title) { this.title = title; @@ -73,8 +73,8 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Set the icon of the MarkerView. * - * @param icon the icon of the MarkerView - * @return the object for which the method was called + * @param icon the icon of the {@link MarkerView}. + * @return the object for which the method was called. */ public T icon(Icon icon) { this.icon = icon; @@ -84,8 +84,8 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Set the flat state of the MarkerView. * - * @param flat the flat state of the MarkerView - * @return the object for which the method was called + * @param flat the flat state of the {@link MarkerView}. + * @return the object for which the method was called. */ public T flat(boolean flat) { this.flat = flat; @@ -93,11 +93,11 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base } /** - * Set the anchor of the MarkerView. + * Set the anchor of the {@link MarkerView}. * - * @param u the u-value - * @param v the v-value - * @return the object for which the method was called + * @param u the u-value. + * @param v the v-value. + * @return the object for which the method was called. */ public T anchor(@FloatRange(from = 0.0, to = 1.0) float u, @FloatRange(from = 0.0, to = 1.0) float v) { this.anchorU = u; @@ -106,11 +106,11 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base } /** - * Set the InfoWindow anchor of the MarkerView. + * Set the InfoWindow anchor of the {@link MarkerView}. * - * @param u the u-value - * @param v the v-values - * @return the object for which the method was called + * @param u the u-value. + * @param v the v-values. + * @return the object for which the method was called. */ public T infoWindowAnchor(@FloatRange(from = 0.0, to = 1.0) float u, @FloatRange(from = 0.0, to = 1.0) float v) { this.infoWindowAnchorU = u; @@ -119,10 +119,10 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base } /** - * Set the rotation of the MarkerView. + * Set the rotation of the {@link MarkerView}. * - * @param rotation the rotation value - * @return the object for which the method was called + * @param rotation the rotation value. + * @return the object for which the method was called. */ public T rotation(float rotation) { this.rotation = rotation; @@ -136,10 +136,10 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base } /** - * Set the visibility state of the MarkerView. + * Set the visibility state of the {@link MarkerView}. * - * @param visible the visible state - * @return the object for which the method was called + * @param visible the visible state. + * @return the object for which the method was called. */ public T visible(boolean visible) { this.visible = visible; @@ -147,10 +147,10 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base } /** - * Set the alpha of the MarkerView. + * Set the alpha of the {@link MarkerView}. * - * @param alpha the alpha value - * @return the object for which the method was called + * @param alpha the alpha value. + * @return the object for which the method was called. */ public T alpha(float alpha) { this.alpha = alpha; @@ -158,63 +158,63 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base } /** - * Get the geographical location of the MarkerView. + * Get the geographical location of the {@link MarkerView}. * - * @return the geographical location + * @return the geographical location. */ public LatLng getPosition() { return position; } /** - * Get the snippet of the MarkerView. + * Get the snippet of the {@link MarkerView}. * - * @return the snippet + * @return the snippet. */ public String getSnippet() { return snippet; } /** - * Get the title of the MarkerView. + * Get the title of the {@link MarkerView}. * - * @return the title + * @return the title. */ public String getTitle() { return title; } /** - * Get the icon of the MarkerView. + * Get the icon of the {@link MarkerView}. * - * @return the icon + * @return the icon. */ public Icon getIcon() { return icon; } /** - * Get the flat state of the MarkerView. + * Get the flat state of the {@link MarkerView}. * - * @return the flat state + * @return the flat state. */ public boolean isFlat() { return flat; } /** - * Get the u-value of the MarkerView anchor. + * Get the u-value of the {@link MarkerView} anchor. * - * @return the u-value + * @return the u-value. */ public float getAnchorU() { return anchorU; } /** - * Get the v-value of the MarkerView anchor. + * Get the v-value of the {@link MarkerView} anchor. * - * @return the v-value + * @return the v-value. */ public float getAnchorV() { return anchorV; @@ -223,7 +223,7 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Get the u-value of the MarkerView InfoWindow anchor. * - * @return the u-value + * @return the u-value. */ public float getInfoWindowAnchorU() { return infoWindowAnchorU; @@ -232,7 +232,7 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Get the v-value of the MarkerView InfoWindow anchor. * - * @return the v-value + * @return the v-value. */ public float getInfoWindowAnchorV() { return infoWindowAnchorV; @@ -241,7 +241,7 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Get the rotation of the MarkerView. * - * @return the rotation value + * @return the rotation value. */ public float getRotation() { return rotation; @@ -250,7 +250,7 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Get the visibility state of the MarkerView. * - * @return the visibility state + * @return the visibility state. */ public boolean isVisible() { return visible; @@ -259,7 +259,7 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Get the alpha of the MarkerView. * - * @return the alpha value + * @return the alpha value. */ public float getAlpha() { return alpha; @@ -268,14 +268,14 @@ public abstract class BaseMarkerViewOptions<U extends MarkerView, T extends Base /** * Get the instance of the object for which this method was called. * - * @return the object for which the 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 + * @return the MarkerView created from this builder. */ public abstract U getMarker(); } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java index fceeb52713..ae7cf6eb8c 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java @@ -18,14 +18,31 @@ public class Icon { mBitmap = bitmap; } + /** + * {@link String} identifier for this {@link Icon}. + * + * @return {@link String} identifier for this {@link Icon}. + */ public String getId() { return mId; } + /** + * Get the {@link Bitmap} being used for this {@link Icon}. + * + * @return The {@link Bitmap} being used for the {@link Icon}. + */ public Bitmap getBitmap() { return mBitmap; } + /** + * Compares this {@link Icon} object with another {@link Icon} and determines if they match. + * + * @param o Another {@link Icon} to compare with this object. + * @return True if the {@link Icon} being passed in matches this {@link Icon} object. Else, + * false. + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -35,9 +52,16 @@ public class Icon { if (!mBitmap.equals(icon.mBitmap)) return false; return mId.equals(icon.mId); - } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { int result = 0; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java index 2e502545d0..9427501bb8 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java @@ -69,6 +69,12 @@ public final class IconFactory { } } + /** + * Creates an {@link Icon} from a given Bitmap image. + * + * @param bitmap image used for creating the Icon. + * @return The {@link Icon} using the given Bitmap image. + */ public Icon fromBitmap(@NonNull Bitmap bitmap) { if (mNextId < 0) { throw new TooManyIconsException(); @@ -77,12 +83,26 @@ public final class IconFactory { return new Icon(id, bitmap); } + /** + * Create an {@link Icon} from a given {@link Drawable}. + * + * @param drawable A {@link Drawable} object used for creating the {@link Icon}. + * @return {@link Icon} with the provided {@link Drawable}. + */ public Icon fromDrawable(@NonNull Drawable drawable) { int width = drawable.getIntrinsicWidth(); int height = drawable.getIntrinsicHeight(); return fromDrawable(drawable, width, height); } + /** + * Create an {@link Icon} from a given {@link Drawable}. + * + * @param drawable A {@link Drawable} object used for creating the {@link Icon}. + * @param width An integer greater then zero defining the {@link Icon} width. + * @param height An integer greater then zero defining the {@link Icon} height. + * @return {@link Icon} with the provided {@link Drawable}. + */ public Icon fromDrawable(@NonNull Drawable drawable, int width, int height) { if ((width < 0) || (height < 0)) { return null; @@ -98,6 +118,12 @@ public final class IconFactory { return fromBitmap(bitmap); } + /** + * Create an {@link Icon} using the resource ID of a Bitmap image. + * + * @param resourceId The resource ID of a Bitmap image. + * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load. + */ public Icon fromResource(@DrawableRes int resourceId) { Drawable drawable = ContextCompat.getDrawable(mContext, resourceId); Bitmap bitmap; @@ -118,6 +144,11 @@ public final class IconFactory { return fromBitmap(bitmap); } + /** + * Provides an {@link Icon} using the default marker icon used for {@link Marker}. + * + * @return An {@link Icon} with the default {@link Marker} icon. + */ public Icon defaultMarker() { if (mDefaultMarker == null) { mDefaultMarker = fromResource(R.drawable.mapbox_marker_icon_default); @@ -125,6 +156,11 @@ public final class IconFactory { return mDefaultMarker; } + /** + * Provides an {@link Icon} using the default marker icon used for {@link MarkerView}. + * + * @return An {@link Icon} with the default {@link MarkerView} icon. + */ public Icon defaultMarkerView() { if (mDefaultMarkerView == null) { mDefaultMarkerView = fromResource(R.drawable.mapbox_markerview_icon_default); @@ -137,6 +173,12 @@ public final class IconFactory { return fromBitmap(bitmap); } + /** + * Creates an {@link Icon} using the name of a Bitmap image in the assets directory. + * + * @param assetName The name of a Bitmap image in the assets directory. + * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load. + */ public Icon fromAsset(@NonNull String assetName) { InputStream is; try { @@ -147,11 +189,26 @@ public final class IconFactory { return fromInputStream(is); } + /** + * Creates an {@link Icon} using the absolute file path of a Bitmap image. + * + * @param absolutePath The absolute path of the Bitmap image. + * @return The {@link Icon} that was loaded from the absolute path or {@code null} if failed to + * load. + */ public Icon fromPath(@NonNull String absolutePath) { Bitmap bitmap = BitmapFactory.decodeFile(absolutePath, mOptions); return fromBitmap(bitmap); } + /** + * Create an {@link Icon} using the name of a Bitmap image file located in the internal storage. + * In particular, this calls {@link Context#openFileInput(String)}. + * + * @param fileName The name of the Bitmap image file. + * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load. + * @see <a href="https://developer.android.com/guide/topics/data/data-storage.html#filesInternal">Using the Internal Storage</a> + */ public Icon fromFile(@NonNull String fileName) { FileInputStream is; try { @@ -162,6 +219,14 @@ public final class IconFactory { return fromInputStream(is); } + /** + * Create an {@link Icon} using a previously created icon identifier along with a provided + * Bitmap. + * + * @param iconId The {@link Icon} identifier you'd like to recreate. + * @param bitmap a Bitmap used to replace the current one. + * @return The {@link Icon} using the new Bitmap. + */ public static Icon recreate(@NonNull String iconId, @NonNull Bitmap bitmap) { return new Icon(iconId, bitmap); } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java index b902a1b3bc..b33d489da2 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java @@ -17,11 +17,16 @@ import com.mapbox.mapboxsdk.maps.MapboxMap; import java.lang.ref.WeakReference; /** + * {@code InfoWindow} is a tooltip shown when a {@link Marker} or {@link MarkerView} is tapped. Only + * one info window is displayed at a time. When the user clicks on a marker, the currently open info + * window will be closed and the new info window will be displayed. If the user clicks the same + * marker while its info window is currently open, the info window will be closed. * <p> - * InfoWindow is a tooltip shown when a {@link Marker} is tapped. - * </p> - * <p> - * This is a UI element placed over a map at a specific geographic location. + * The info window is drawn oriented against the device's screen, centered above its associated + * marker by default. The info window anchoring can be adjusted using + * {@link MarkerView#setInfoWindowAnchor(float, float)} for {@link MarkerView}. The default info + * window contains the title in bold and snippet text below the title. While either the title and + * snippet are optional, at least one is required to open the info window. * </p> */ public class InfoWindow { @@ -90,13 +95,15 @@ public class InfoWindow { /** - * open the window at the specified position. + * Open the info window at the specified position. * - * @param boundMarker the marker on which is hooked the view - * @param position to place the window on the map - * @param offsetX (&offsetY) the offset of the view to the position, in pixels. - * This allows to offset the view from the object position. - * @return this infowindow + * @param boundMarker The marker on which is hooked the view. + * @param position to place the window on the map. + * @param offsetX The offset of the view to the position, in pixels. This allows to offset + * the view from the object position. + * @param offsetY The offset of the view to the position, in pixels. This allows to offset + * the view from the object position. + * @return this {@link InfoWindow}. */ InfoWindow open(MapView mapView, Marker boundMarker, LatLng position, int offsetX, int offsetY) { setBoundMarker(boundMarker); @@ -190,9 +197,9 @@ public class InfoWindow { } /** - * Close this InfoWindow if it is visible, otherwise don't do anything. + * Close this {@link InfoWindow} if it is visible, otherwise calling this will do nothing. * - * @return this info window + * @return This {@link InfoWindow} */ InfoWindow close() { MapboxMap mapboxMap = mMapboxMap.get(); @@ -215,8 +222,8 @@ public class InfoWindow { } /** - * Constructs the view that is displayed when the InfoWindow opens. - * This retrieves data from overlayItem and shows it in the tooltip. + * Constructs the view that is displayed when the InfoWindow opens. This retrieves data from + * overlayItem and shows it in the tooltip. * * @param overlayItem the tapped overlay item */ @@ -258,6 +265,9 @@ public class InfoWindow { return mBoundMarker.get(); } + /** + * Will result in getting this {@link InfoWindow} and updating the view being displayed. + */ public void update() { MapboxMap mapboxMap = mMapboxMap.get(); Marker marker = mBoundMarker.get(); @@ -274,6 +284,11 @@ public class InfoWindow { } } + /** + * Retrieve this {@link InfoWindow}'s current view being used. + * + * @return This {@link InfoWindow}'s current View. + */ public View getView() { return mView != null ? mView.get() : null; } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java index ae0f9200ab..c4d1090194 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java @@ -10,9 +10,19 @@ import com.mapbox.mapboxsdk.maps.MapView; import com.mapbox.mapboxsdk.maps.MapboxMap; /** - * Marker is an annotation that shows an icon image at a geographical location. + * Marker is an annotation that shows an icon image at a geographical location. The default marker + * uses a provided icon. This icon can be customized using {@link IconFactory} to generate an + * {@link Icon} using a provided image. Markers are added to the map by first giving a + * {@link LatLng} and using {@link MapboxMap#addMarker(MarkerOptions)}. The marker icon will be + * centered at this position so it is common to add padding to the icon image before usage. * <p> - * An {@link InfoWindow} can be shown when a Marker is pressed + * If more customization is needed, we offer {@link MarkerView} which places a {@link View} on top + * of the map at a geographical location. + * </p> + * <p> + * Markers are designed to be interactive. They receive click events by default, and are often used + * with event listeners to bring up info windows. An {@link InfoWindow} is displayed by default when + * either a title or snippet is provided. * </p> */ public class Marker extends Annotation { @@ -35,6 +45,11 @@ public class Marker extends Annotation { super(); } + /** + * Creates a instance of {@link Marker} using the builder of Marker. + * + * @param baseMarkerOptions The builder used to construct the Marker. + */ public Marker(BaseMarkerOptions baseMarkerOptions) { position = baseMarkerOptions.position; snippet = baseMarkerOptions.snippet; @@ -56,20 +71,35 @@ public class Marker extends Annotation { this.snippet = snippet; } + /** + * Returns the position of the marker. + * + * @return A {@link LatLng} object specifying the marker's current position. + */ public LatLng getPosition() { return position; } + /** + * Gets the snippet of the marker. + * + * @return A string containing the marker's snippet. + */ public String getSnippet() { return snippet; } + /** + * Gets the snippet of the marker. + * + * @return A string containing the marker's snippet. + */ public String getTitle() { return title; } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. */ public void hideInfoWindow() { if (infoWindow != null) { @@ -79,7 +109,7 @@ public class Marker extends Annotation { } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. * * @return true if the infoWindow is shown */ @@ -88,9 +118,9 @@ public class Marker extends Annotation { } /** - * Sets the position. + * Sets the location of the marker. * - * @param position new position + * @param position A {@link LatLng} defining the marker position. */ public void setPosition(LatLng position) { this.position = position; @@ -100,15 +130,21 @@ public class Marker extends Annotation { } } + /** + * Sets the snippet of the marker. + * + * @param snippet A String used in the marker info window. If {@code null}, the snippet is + * cleared. + */ public void setSnippet(String snippet) { this.snippet = snippet; refreshInfoWindowContent(); } /** - * Sets the icon. + * Sets the icon of the marker. * - * @param icon The icon to be used as Marker image + * @param icon The {@link Icon} to be used as Marker image */ public void setIcon(@Nullable Icon icon) { this.icon = icon; @@ -118,15 +154,33 @@ public class Marker extends Annotation { } } + /** + * Gets the {@link Icon} currently used for the marker. If no Icon was set for the marker, the + * default icon will be returned. + * + * @return The {@link Icon} the marker is using. + */ public Icon getIcon() { return icon; } + /** + * Sets the title of the marker. + * + * @param title A String used in the marker info window. If {@code null}, the title is + * cleared. + */ public void setTitle(String title) { this.title = title; refreshInfoWindowContent(); } + /** + * Gets the {@link InfoWindow} the marker is using. If the marker hasn't had an info window + * defined, this will return {@code null}. + * + * @return + */ @Nullable public InfoWindow getInfoWindow() { return infoWindow; @@ -150,11 +204,12 @@ public class Marker extends Annotation { } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. Use {@link MapboxMap#selectMarker(Marker)} + * if you want to programmatically display the markers info window. * - * @param mapboxMap the hosting mapbox map - * @param mapView the hosting map view - * @return the info window that was shown + * @param mapboxMap The hosting mapbox map. + * @param mapView The hosting map view. + * @return The info window that was shown. */ public InfoWindow showInfoWindow(@NonNull MapboxMap mapboxMap, @NonNull MapView mapView) { setMapboxMap(mapboxMap); @@ -191,7 +246,7 @@ public class Marker extends Annotation { } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. * * @param topOffsetPixels the top offset pixels. */ @@ -200,7 +255,7 @@ public class Marker extends Annotation { } /** - * Do not use this method. Used internally by the SDK. + * Do not use this method, used internally by the SDK. * * @param rightOffsetPixels the right offset pixels. */ @@ -208,6 +263,11 @@ public class Marker extends Annotation { this.rightOffsetPixels = rightOffsetPixels; } + /** + * Returns a String with the marker position. + * + * @return A String with the marker position. + */ @Override public String toString() { return "Marker [position[" + getPosition() + "]]"; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java index 328ee1894c..282da6407e 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java @@ -7,14 +7,13 @@ import android.os.Parcelable; import com.mapbox.mapboxsdk.exceptions.InvalidMarkerPositionException; import com.mapbox.mapboxsdk.geometry.LatLng; - /** * <p> - * Builder for composing {@link com.mapbox.mapboxsdk.annotations.Marker} objects. + * Builder for composing {@link Marker} objects. See {@link Marker} for additional information. * </p> * <h3>Example</h3> * <pre> - * mMapView.addMarker(new MarkerOptions() + * mapView.addMarker(new MarkerOptions() * .title("Intersection") * .snippet("H St NW with 15th St NW") * .position(new LatLng(38.9002073, -77.03364419))); @@ -22,6 +21,9 @@ import com.mapbox.mapboxsdk.geometry.LatLng; */ public final class MarkerOptions extends BaseMarkerOptions<Marker, MarkerOptions> implements Parcelable { + /** + * Defines options for a Marker. + */ public MarkerOptions() { } @@ -43,11 +45,24 @@ public final class MarkerOptions extends BaseMarkerOptions<Marker, MarkerOptions return this; } + /** + * Describe the kinds of special objects contained in this Parcelable's + * marshalled representation. + * + * @return integer 0. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written. May be 0 or + * {@link #PARCELABLE_WRITE_RETURN_VALUE}. + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeParcelable(getPosition(), flags); @@ -74,18 +89,39 @@ public final class MarkerOptions extends BaseMarkerOptions<Marker, MarkerOptions return new Marker(position, icon, title, snippet); } + /** + * Returns the position set for this {@link MarkerOptions} object. + * + * @return A {@link LatLng} object specifying the marker's current position. + */ public LatLng getPosition() { return position; } + /** + * Gets the snippet set for this {@link MarkerOptions} object. + * + * @return A string containing the marker's snippet. + */ public String getSnippet() { return snippet; } + /** + * Gets the title set for this {@link MarkerOptions} object. + * + * @return A string containing the marker's title. + */ public String getTitle() { return title; } + /** + * Gets the custom icon set for this {@link MarkerOptions} object. + * + * @return A {@link Icon} object that the marker is using. If the icon wasn't set, default icon + * will return. + */ public Icon getIcon() { return icon; } @@ -101,6 +137,14 @@ public final class MarkerOptions extends BaseMarkerOptions<Marker, MarkerOptions } }; + /** + * Compares this {@link MarkerOptions} object with another {@link MarkerOptions} and + * determines if their properties match. + * + * @param o Another {@link MarkerOptions} to compare with this object. + * @return True if marker properties match this {@link MarkerOptions} object. + * Else, false. + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -117,6 +161,14 @@ public final class MarkerOptions extends BaseMarkerOptions<Marker, MarkerOptions return !(getTitle() != null ? !getTitle().equals(marker.getTitle()) : marker.getTitle() != null); } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { int result = 1; 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 72037c2565..a32186b52e 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 @@ -8,13 +8,20 @@ import com.mapbox.mapboxsdk.geometry.LatLng; import com.mapbox.mapboxsdk.maps.MapboxMap; /** - * MarkerView is an annotation that shows an View at a geographical location. + * MarkerView is an annotation that shows a {@link android.view.View} at a geographical location. The + * default marker uses a provided icon. This icon can be customized using {@link IconFactory} to + * generate an {@link Icon} using a provided image. MarkerViews are added to the map by first giving + * a {@link LatLng} and using {@link MapboxMap#addMarker(BaseMarkerViewOptions)}. The marker view icon + * by default is anchored at the center bottom. * <p> - * This class uses {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter} to adapt a + * If many markers are needed to be displayed on the map at once we suggest using {@link Marker} + * instead. 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 + * MarkerViews are designed to be interactive. They receive click events by default, and are often + * used with event listeners to bring up info windows. An {@link InfoWindow} is displayed by default + * when either a title or snippet is provided. * </p> */ public class MarkerView extends Marker { @@ -85,14 +92,14 @@ public class MarkerView extends Marker { } /** - * Specifies the anchor being set on a particular point point of the MarkerView. + * Specifies the anchor being set on a particular 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]) + * @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(@FloatRange(from = 0.0, to = 1.0) float u, @FloatRange(from = 0.0, to = 1.0) float v) { this.anchorU = u; @@ -103,7 +110,7 @@ public class MarkerView extends Marker { /** * Get the horizontal distance, normalized to [0, 1], of the anchor from the left edge. * - * @return the u-value of the anchor + * @return The u-value of the anchor. */ public float getAnchorU() { return anchorU; @@ -112,7 +119,7 @@ public class MarkerView extends Marker { /** * Get the vertical distance, normalized to [0, 1], of the anchor from the top edge. * - * @return the v-value of the anchor + * @return the v-value of the anchor. */ public float getAnchorV() { return anchorV; @@ -124,8 +131,8 @@ public class MarkerView extends Marker { * These are calculated based on the View bounds and the provided anchor. * </p> * - * @param x the x-value of the offset - * @param y the y-value of the offset + * @param x the x-value of the offset. + * @param y the y-value of the offset. */ void setOffset(float x, float y) { offsetX = x; @@ -133,18 +140,18 @@ public class MarkerView extends Marker { } /** - * Internal method to get the horizontal calculated offset + * Internal method to get the horizontal calculated offset. * - * @return the calculated horizontal offset + * @return the calculated horizontal offset. */ float getOffsetX() { return offsetX; } /** - * Internal method to get the vertical calculated offset + * Internal method to get the vertical calculated offset. * - * @return the calculated vertical offset + * @return the calculated vertical offset. */ float getOffsetY() { return offsetY; @@ -153,14 +160,15 @@ public class MarkerView extends Marker { /** * 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. + * 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> * <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]) + * @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(@FloatRange(from = 0.0, to = 1.0) float u, @FloatRange(from = 0.0, to = 1.0) float v) { @@ -189,16 +197,17 @@ public class MarkerView extends Marker { /** * Get the flat state of a MarkerView. * - * @return true is the MarkerView is flat; false is the MarkerView is billboard + * @return true if the MarkerView is flat; false if 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. + * Sets whether this MarkerView should be flat against the map (true) or a billboard facing the + * camera (false). * - * @param flat the flat state of the MarkerView + * @param flat the flat state of the MarkerView. */ public void setFlat(boolean flat) { this.flat = flat; @@ -207,7 +216,7 @@ public class MarkerView extends Marker { /** * Internal method to get the current tilted value of a MarkerView. * - * @return the tilted value + * @return the tilted value. */ float getTilt() { return tiltValue; @@ -216,7 +225,7 @@ public class MarkerView extends Marker { /** * Internal method to set the current titled value of a MarkerView. * - * @param tiltValue the tilted value to set + * @param tiltValue the tilted value to set. */ void setTilt(@FloatRange(from = 0.0, to = MapboxConstants.MAXIMUM_TILT) float tiltValue) { this.tiltValue = tiltValue; @@ -225,7 +234,7 @@ public class MarkerView extends Marker { /** * Set the visible state of a MarkerView. * - * @param visible true will make the MarkerView visible, false will hide the MarkerViews + * @param visible true will make the MarkerView visible, false will hide the MarkerView. */ public void setVisible(boolean visible) { this.visible = visible; @@ -237,7 +246,7 @@ public class MarkerView extends Marker { /** * Returns the visible state of the MarkerView. * - * @return the visible state + * @return the visible state. */ public boolean isVisible() { return visible; @@ -246,14 +255,14 @@ public class MarkerView extends Marker { /** * Set the rotation value of the MarkerView in degrees. * <p> - * Input will be limited to 0 - 360 degrees + * Input will be limited to 0 - 360 degrees. * </p> * <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 + * @param rotation the rotation value to animate to. */ public void setRotation(float rotation) { // limit to 0 - 360 degrees @@ -274,7 +283,7 @@ public class MarkerView extends Marker { /** * Get the rotation value of the MarkerView. * - * @return the rotation value + * @return the rotation value. */ public float getRotation() { return rotation; @@ -283,7 +292,7 @@ public class MarkerView extends Marker { /** * Get the alpha value of the MarkerView. * - * @return the alpha value + * @return the alpha value. */ public float getAlpha() { return alpha; @@ -296,7 +305,7 @@ public class MarkerView extends Marker { * from current value to the provided parameter value. * </p> * - * @param alpha the alpha value to animate to + * @param alpha the alpha value to animate to. */ public void setAlpha(@FloatRange(from = 0.0, to = 255.0) float alpha) { this.alpha = alpha; @@ -308,7 +317,7 @@ public class MarkerView extends Marker { /** * Set the icon of the MarkerView. * - * @param icon the icon to be used as Marker image + * @param icon the {@link Icon} to be used as Marker image. */ @Override public void setIcon(@Nullable Icon icon) { @@ -323,6 +332,11 @@ public class MarkerView extends Marker { super.setIcon(transparentIcon); } + /** + * Sets the location of the marker. + * + * @param position A {@link LatLng} defining the marker position. + */ @Override public void setPosition(LatLng position) { super.setPosition(position); @@ -331,6 +345,11 @@ public class MarkerView extends Marker { } } + /** + * Determine if the {@link MarkerView} is selected or not. + * + * @return True if the MarkerView's selected, else false. + */ public boolean isSelected() { return selected; } @@ -345,7 +364,7 @@ public class MarkerView extends Marker { /** * Get the icon of the MarkerView. * - * @return the icon use as Marker image + * @return the icon use as Marker image. */ @Override public Icon getIcon() { @@ -361,12 +380,12 @@ public class MarkerView extends Marker { * This method is used to notify that a MarkerView is no longer active by setting a null value. * </p> * - * @param mapboxMap the MapboxMap instances + * @param mapboxMap the MapboxMap instances. */ @Override public void setMapboxMap(MapboxMap mapboxMap) { super.setMapboxMap(mapboxMap); - if(mapboxMap!=null) { + if (mapboxMap != null) { if (isFlat()) { // initial tilt value if MapboxMap is started with a tilt attribute tiltValue = (float) mapboxMap.getCameraPosition().tilt; @@ -379,7 +398,7 @@ public class MarkerView extends Marker { /** * Get the String representation of a MarkerView. * - * @return the String representation + * @return the String representation. */ @Override public String toString() { 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 0f0f263d3a..1073818ca4 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 @@ -60,8 +60,8 @@ public class MarkerViewManager { * 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 + * @param marker the MarkerView to rotate. + * @param rotation the rotation value. */ public void animateRotation(@NonNull MarkerView marker, float rotation) { View convertView = markerViewMap.get(marker); @@ -73,8 +73,8 @@ public class MarkerViewManager { /** * Animate a MarkerView with a given rotation. * - * @param marker the MarkerView to rotate by - * @param rotation the rotation by value, limited to 0 - 360 degrees + * @param marker the MarkerView to rotate by. + * @param rotation the rotation by value, limited to 0 - 360 degrees. */ public void animateRotationBy(@NonNull MarkerView marker, float rotation) { View convertView = markerViewMap.get(marker); @@ -97,8 +97,8 @@ public class MarkerViewManager { * 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 + * @param marker the MarkerView to change its alpha value. + * @param alpha the alpha value. */ public void animateAlpha(@NonNull MarkerView marker, float alpha) { View convertView = markerViewMap.get(marker); @@ -127,8 +127,8 @@ 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. + * 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() { @@ -166,7 +166,7 @@ public class MarkerViewManager { /** * Set tilt on every non flat MarkerView currently shown in the Viewport. * - * @param tilt the tilt value + * @param tilt the tilt value. */ public void setTilt(float tilt) { View convertView; @@ -184,7 +184,7 @@ public class MarkerViewManager { /** * Update and invalidate the MarkerView icon. * - * @param markerView the marker view to updates + * @param markerView the marker view to updates. */ public void updateIcon(@NonNull MarkerView markerView) { View convertView = markerViewMap.get(markerView); @@ -196,10 +196,11 @@ public class MarkerViewManager { /** * Animate a MarkerView to a deselected state. * <p> - * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onDeselect(MarkerView, View)} will be called to execute an animation. + * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onDeselect(MarkerView, View)} + * will be called to execute an animation. * </p> * - * @param marker the MarkerView to deselect + * @param marker the MarkerView to deselect. */ public void deselect(@NonNull MarkerView marker) { deselect(marker, true); @@ -208,11 +209,12 @@ public class MarkerViewManager { /** * Animate a MarkerView to a deselected state. * <p> - * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onDeselect(MarkerView, View)} will be called to execute an animation. + * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onDeselect(MarkerView, View)} + * will be called to execute an animation. * </p> * - * @param marker the MarkerView to deselect - * @param callbackToMap indicates if deselect marker must be called on MapboxMap + * @param marker the MarkerView to deselect. + * @param callbackToMap indicates if deselect marker must be called on MapboxMap. */ public void deselect(@NonNull MarkerView marker, boolean callbackToMap) { final View convertView = markerViewMap.get(marker); @@ -232,7 +234,7 @@ public class MarkerViewManager { /** * Animate a MarkerView to a selected state. * - * @param marker the MarkerView object to select + * @param marker the MarkerView object to select. */ public void select(@NonNull MarkerView marker) { select(marker, true); @@ -241,8 +243,8 @@ public class MarkerViewManager { /** * Animate a MarkerView to a selected state. * - * @param marker the MarkerView object to select - * @param callbackToMap indicates if select marker must be called on MapboxMap + * @param marker the MarkerView object to select. + * @param callbackToMap indicates if select marker must be called on {@link MapboxMap}. */ public void select(@NonNull MarkerView marker, boolean callbackToMap) { final View convertView = markerViewMap.get(marker); @@ -256,12 +258,13 @@ public class MarkerViewManager { /** * Animate a MarkerView to a selected state. * <p> - * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onSelect(MarkerView, View, boolean)} will be called to execute an animation. + * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onSelect(MarkerView, View, boolean)} + * will be called to execute an animation. * </p> * - * @param marker the MarkerView object to select - * @param convertView the View presentation of the MarkerView - * @param adapter the adapter used to adapt the marker to the convertView + * @param marker the MarkerView object to select. + * @param convertView the View presentation of the MarkerView. + * @param adapter the adapter used to adapt the marker to the convertView. */ public void select(@NonNull MarkerView marker, View convertView, MapboxMap.MarkerViewAdapter adapter) { select(marker, convertView, adapter, true); @@ -271,13 +274,14 @@ public class MarkerViewManager { /** * Animate a MarkerView to a selected state. * <p> - * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onSelect(MarkerView, View, boolean)} will be called to execute an animation. + * The {@link com.mapbox.mapboxsdk.maps.MapboxMap.MarkerViewAdapter#onSelect(MarkerView, View, boolean)} + * will be called to execute an animation. * </p> * - * @param marker the MarkerView object to select - * @param convertView the View presentation of the MarkerView - * @param adapter the adapter used to adapt the marker to the convertView - * @param callbackToMap indicates if select marker must be called on MapboxMap + * @param marker the MarkerView object to select. + * @param convertView the View presentation of the MarkerView. + * @param adapter the adapter used to adapt the marker to the convertView. + * @param callbackToMap indicates if select marker must be called on MapboxMap. */ public void select(@NonNull MarkerView marker, View convertView, MapboxMap.MarkerViewAdapter adapter, boolean callbackToMap) { if (convertView != null) { @@ -292,19 +296,23 @@ public class MarkerViewManager { } /** - * Get view representation from a MarkerView. - * <p> - * If marker is not found in current viewport, null is returned. - * </p> + * Get view representation from a MarkerView. If marker is not found in current viewport, + * {@code null} is returned. * - * @param marker the marker to get the view for - * @return the android SDK View object + * @param marker the marker to get the view. + * @return the Android SDK View object. */ @Nullable public View getView(MarkerView marker) { return markerViewMap.get(marker); } + /** + * Get the view adapter for a marker. + * + * @param markerView the marker to get the view adapter. + * @return the MarkerView adapter. + */ @Nullable public MapboxMap.MarkerViewAdapter getViewAdapter(MarkerView markerView) { MapboxMap.MarkerViewAdapter adapter = null; @@ -325,7 +333,7 @@ public class MarkerViewManager { * the {@link MarkerView} from the underlying collection if needed. * </p> * - * @param marker the MarkerView to remove + * @param marker the MarkerView to remove. */ public void removeMarkerView(MarkerView marker) { final View viewHolder = markerViewMap.get(marker); @@ -347,10 +355,10 @@ public class MarkerViewManager { /** * Add a MarkerViewAdapter to the MarkerViewManager. * <p> - * The provided MarkerViewAdapter must use supply a generic subclass of MarkerView. + * The provided MarkerViewAdapter must supply a generic subclass of MarkerView. * </p> * - * @param markerViewAdapter the MarkerViewAdapter to add + * @param markerViewAdapter the MarkerViewAdapter to add. */ public void addMarkerViewAdapter(MapboxMap.MarkerViewAdapter markerViewAdapter) { if (markerViewAdapter.getMarkerClass().equals(MarkerView.class)) { @@ -366,7 +374,7 @@ public class MarkerViewManager { /** * Get all MarkerViewAdapters associated with this MarkerViewManager. * - * @return a List of MarkerViewAdapters + * @return a List of MarkerViewAdapters. */ public List<MapboxMap.MarkerViewAdapter> getMarkerViewAdapters() { return markerViewAdapters; @@ -375,7 +383,7 @@ public class MarkerViewManager { /** * Register a callback to be invoked when this view is clicked. * - * @param listener the callback to be invoked + * @param listener the callback to be invoked. */ public void setOnMarkerViewClickListener(@Nullable MapboxMap.OnMarkerViewClickListener listener) { onMarkerViewClickListener = listener; @@ -402,7 +410,7 @@ 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 + * This method will remove any markers that aren't in the viewport anymore and will add new * ones for each found Marker in the changed viewport. * </p> */ @@ -468,6 +476,12 @@ public class MarkerViewManager { update(); } + /** + * When the provided {@link MarkerView} is clicked on by a user, we check if a custom click + * event has been created and if not, display a {@link InfoWindow}. + * + * @param markerView that the click event occurred. + */ public void onClickMarkerView(MarkerView markerView) { boolean clickHandled = false; @@ -488,7 +502,11 @@ public class MarkerViewManager { } } - //TODO: This whole method is a stopgap for: https://github.com/mapbox/mapbox-gl-native/issues/5384 + /** + * Handles the {@link MarkerView}'s info window offset. + * + * @param marker that we are ensuring info window offset. + */ public void ensureInfoWindowOffset(MarkerView marker) { View view = null; if (markerViewMap.containsKey(marker)) { @@ -529,7 +547,8 @@ public class MarkerViewManager { } /** - * Default MarkerViewAdapter used for base class of MarkerView to adapt a MarkerView to an ImageView + * Default MarkerViewAdapter used for base class of {@link MarkerView} to adapt a MarkerView to + * an ImageView. */ public static class ImageMarkerViewAdapter extends MapboxMap.MarkerViewAdapter<MarkerView> { 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 86ad873347..1a763a72a1 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 @@ -10,13 +10,17 @@ import com.mapbox.mapboxsdk.geometry.LatLng; /** * builder class for composing MarkerView objects. * <p> - * Do not extend this class directly but extend BaseMarkerViewOptions instead. + * Do not extend this class directly but extend {@link BaseMarkerViewOptions} instead. * </p> */ public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerViewOptions> { private MarkerView marker; + /** + * Defines default options for a MarkerView. Extend {@link BaseMarkerViewOptions} if you need + * more customization. + */ public MarkerViewOptions() { marker = new MarkerView(); } @@ -41,16 +45,34 @@ public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerV } } + /** + * Get the instance of the object for which this method was called. + * + * @return the object for which this method was called. + */ @Override public MarkerViewOptions getThis() { return this; } + /** + * Describe the kinds of special objects contained in this Parcelable's + * marshalled representation. + * + * @return integer 0. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written. May be 0 or + * {@link #PARCELABLE_WRITE_RETURN_VALUE}. + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeParcelable(getPosition(), flags); @@ -72,12 +94,17 @@ public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerV } } + /** + * Get the {@link MarkerView}. + * + * @return {@link MarkerView}. + */ @Override public MarkerView getMarker() { if (position == null) { throw new InvalidMarkerPositionException(); } - + marker.setPosition(position); marker.setSnippet(snippet); marker.setTitle(title); @@ -102,6 +129,14 @@ public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerV } }; + /** + * Compares this {@link MarkerViewOptions} object with another {@link MarkerViewOptions} and + * determines if they match. + * + * @param o Another {@link MarkerViewOptions} to compare with this object. + * @return True if the {@link MarkerViewOptions} being passed in matches this + * {@link PolylineOptions} object. Else, false. + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -110,6 +145,14 @@ public class MarkerViewOptions extends BaseMarkerViewOptions<MarkerView, MarkerV return marker != null ? marker.equals(that.marker) : that.marker == null; } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { return marker != null ? marker.hashCode() : 0; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java index a76238fdcb..78d21db2e9 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java @@ -21,33 +21,47 @@ public abstract class MultiPoint extends Annotation { /** * Returns a copy of the points. * - * @return points - as a copy + * @return A {@link List} of points. */ public List<LatLng> getPoints() { return new ArrayList<>(points); } /** - * Sets the points of this polyline. This method will take a copy - * of the points, so further mutations to points will have no effect - * on this polyline. + * Sets the points of this polyline. This method will take a copy of the points, so further + * mutations to points will have no effect on this polyline. * - * @param points the points of the polyline + * @param points A {@link List} of {@link LatLng} points making up the polyline. */ public void setPoints(List<LatLng> points) { this.points = new ArrayList<>(points); update(); } + /** + * Add a point to the polyline. + * + * @param point A {@link LatLng} point to be added. + */ public void addPoint(LatLng point) { points.add(point); update(); } + /** + * Value between 0 and 1 defining the polyline alpha. + * + * @return float value between 0 and 1. + */ public float getAlpha() { return alpha; } + /** + * Set this {@link MultiPoint}s alpha. + * + * @param alpha float value between 0 and 1. + */ public void setAlpha(float alpha) { this.alpha = alpha; update(); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polygon.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polygon.java index 78e3a99e96..a06938e3cb 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polygon.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polygon.java @@ -19,7 +19,7 @@ public final class Polygon extends MultiPoint { /** * Get the color of the fill region of the polygon. * - * @return the color of the fill + * @return The color of the fill. */ public int getFillColor() { return fillColor; @@ -28,7 +28,7 @@ public final class Polygon extends MultiPoint { /** * Get the color fo the stroke of the polygon. * - * @return the color of the stroke + * @return The color of the stroke. */ public int getStrokeColor() { return strokeColor; @@ -37,7 +37,7 @@ public final class Polygon extends MultiPoint { /** * Sets the color of the fill region of the polygon. * - * @param color - the color in ARGB format + * @param color The color in ARGB format. */ public void setFillColor(int color) { fillColor = color; @@ -47,7 +47,7 @@ public final class Polygon extends MultiPoint { /** * Sets the color of the stroke of the polygon. * - * @param color - the color in ARGB format + * @param color The color in ARGB format. */ public void setStrokeColor(int color) { strokeColor = color; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java index 30847807b9..53a4e0995b 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java @@ -35,11 +35,24 @@ public final class PolygonOptions implements Parcelable { strokeColor(in.readInt()); } + /** + * Describe the kinds of special objects contained in this Parcelable's + * marshalled representation. + * + * @return integer 0. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written. May be 0 or + * {@link #PARCELABLE_WRITE_RETURN_VALUE}. + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeList(getPoints()); @@ -50,15 +63,30 @@ public final class PolygonOptions implements Parcelable { private Polygon polygon; + /** + * Defines options for a polygon. + */ public PolygonOptions() { polygon = new Polygon(); } + /** + * Adds a vertex to the outline of the polygon being built. + * + * @param point {@link LatLng} point to be added to polygon geometry. + * @return This {@link PolygonOptions} object with the given point added to the outline. + */ public PolygonOptions add(LatLng point) { polygon.addPoint(point); return this; } + /** + * Adds vertices to the outline of the polygon being built. + * + * @param points {@link LatLng} points to be added to polygon geometry. + * @return This {@link PolygonOptions} object with the given points added to the outline. + */ public PolygonOptions add(LatLng... points) { for (LatLng point : points) { add(point); @@ -66,6 +94,13 @@ public final class PolygonOptions implements Parcelable { return this; } + /** + * Adds vertices to the outline of the polygon being built. + * + * @param points {@link Iterable} list made up of {@link LatLng} points defining the polygon + * geometry + * @return This {@link PolygonOptions} object with the given points added to the outline. + */ public PolygonOptions addAll(Iterable<LatLng> points) { for (LatLng point : points) { add(point); @@ -73,26 +108,42 @@ public final class PolygonOptions implements Parcelable { return this; } + /** + * Set the alpha value of the polyline. + * + * @param alpha float value between 0 (not visible) and 1. + * @return This {@link PolygonOptions} object with the given polygon alpha value. + */ public PolygonOptions alpha(float alpha) { polygon.setAlpha(alpha); return this; } + /** + * Gets the alpha set for this {@link PolygonOptions} object. + * + * @return float value between 0 and 1 defining the alpha. + */ public float getAlpha() { return polygon.getAlpha(); } /** - * Sets the color of the polygon. + * Specifies the polygon's fill color, as 32-bit ARGB. The default color is black. * - * @param color - the color in ARGB format - * @return PolygonOptions - the options object + * @param color 32-bit ARGB color. + * @return This {@link PolylineOptions} object with a new color set. */ public PolygonOptions fillColor(int color) { polygon.setFillColor(color); return this; } + /** + * Gets the fill color set for this {@link PolygonOptions} object. + * + * @return The fill color of the polygon in ARGB format. + */ public int getFillColor() { return polygon.getFillColor(); } @@ -107,16 +158,21 @@ public final class PolygonOptions implements Parcelable { } /** - * Sets the color of the stroke of the polygon. + * Specifies the polygon's stroke color, as 32-bit ARGB. The default color is black. * - * @param color - the color in ARGB format - * @return PolygonOptions - the options object + * @param color 32-bit ARGB color. + * @return This {@link PolygonOptions} object with a new stroke color set. */ public PolygonOptions strokeColor(int color) { polygon.setStrokeColor(color); return this; } + /** + * Gets the stroke color set for this {@link PolygonOptions} object. + * + * @return The stroke color of the polygon in ARGB format. + */ public int getStrokeColor() { return polygon.getStrokeColor(); } @@ -126,6 +182,14 @@ public final class PolygonOptions implements Parcelable { return polygon.getPoints(); } + /** + * Compares this {@link PolygonOptions} object with another {@link PolygonOptions} and + * determines if their color, alpha, stroke color, and vertices match. + * + * @param o Another {@link PolygonOptions} to compare with this object. + * @return True if color, alpha, stroke color, and vertices match this {@link PolygonOptions} + * object. Else, false. + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -139,6 +203,14 @@ public final class PolygonOptions implements Parcelable { return !(getPoints() != null ? !getPoints().equals(polygon.getPoints()) : polygon.getPoints() != null); } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { int result = 1; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polyline.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polyline.java index 4bf3242d57..49d8d5d6e8 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polyline.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polyline.java @@ -17,18 +17,18 @@ public final class Polyline extends MultiPoint { } /** - * Returns the Polyline tint color. + * Gets the color of this polyline. * - * @return the tint color + * @return The color in ARGB format. */ public int getColor() { return color; } /** - * Returns the Polyline width. + * Gets the width of this polyline. * - * @return the width + * @return The width in screen pixels. */ public float getWidth() { return width; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java index 1e625c10fc..c74f6d196f 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java @@ -35,11 +35,24 @@ public final class PolylineOptions implements Parcelable { width(in.readFloat()); } + /** + * Describe the kinds of special objects contained in this Parcelable's + * marshalled representation. + * + * @return integer 0. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written. May be 0 or + * {@link #PARCELABLE_WRITE_RETURN_VALUE}. + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeList(getPoints()); @@ -50,15 +63,30 @@ public final class PolylineOptions implements Parcelable { private Polyline polyline; + /** + * Defines options for a polyline. + */ public PolylineOptions() { polyline = new Polyline(); } + /** + * Adds a vertex to the end of the polyline being built. + * + * @param point {@link LatLng} point to be added to polyline geometry. + * @return This {@link PolylineOptions} object with the given point on the end. + */ public PolylineOptions add(LatLng point) { polyline.addPoint(point); return this; } + /** + * Adds vertices to the end of the polyline being built. + * + * @param points {@link LatLng} points defining the polyline geometry. + * @return This {@link PolylineOptions} object with the given point on the end. + */ public PolylineOptions add(LatLng... points) { for (LatLng point : points) { add(point); @@ -66,6 +94,13 @@ public final class PolylineOptions implements Parcelable { return this; } + /** + * Adds vertices to the end of the polyline being built. + * + * @param points {@link Iterable} list made up of {@link LatLng} points defining the polyline + * geometry + * @return This {@link PolylineOptions} object with the given points on the end. + */ public PolylineOptions addAll(Iterable<LatLng> points) { for (LatLng point : points) { add(point); @@ -73,58 +108,93 @@ public final class PolylineOptions implements Parcelable { return this; } + /** + * Set the alpha value of the polyline. + * + * @param alpha float value between 0 (not visible) and 1. + * @return This {@link PolylineOptions} object with the given polyline alpha value. + */ public PolylineOptions alpha(float alpha) { polyline.setAlpha(alpha); return this; } + /** + * Gets the alpha set for this {@link PolylineOptions} object. + * + * @return float value between 0 and 1 defining the alpha. + */ public float getAlpha() { return polyline.getAlpha(); } /** - * Sets the color of the polyline. + * Sets the color of the polyline as a 32-bit ARGB color. The default color is black. * - * @param color - the color in ARGB format - * @return PolyLineOptions The builder used to build a Polyline + * @param color 32-bit ARGB color. + * @return This {@link PolylineOptions} object with a new color set. */ public PolylineOptions color(int color) { polyline.setColor(color); return this; } + /** + * Gets the color set for this {@link PolylineOptions} object. + * + * @return The color of the polyline in ARGB format. + */ public int getColor() { return polyline.getColor(); } /** * Do not use this method. Used internally by the SDK. + * * @return PolyLine The polyline build by this class. */ public Polyline getPolyline() { return polyline; } + /** + * Gets the width set for this {@link PolylineOptions} object. + * + * @return The width of the polyline in screen pixels. + */ public float getWidth() { return polyline.getWidth(); } /** - * Sets the width of the polyline. + * Sets the width of the polyline in screen pixels. The default is 10. * - * @param width in pixels - * @return a new PolylineOptions + * @param width float value defining width of polyline using unit pixels. + * @return This {@link PolylineOptions} object with a new width set. */ public PolylineOptions width(float width) { polyline.setWidth(width); return this; } + /** + * Gets the points set for this {@link PolylineOptions} object. + * + * @return a {@link List} of {@link LatLng}s specifying the vertices of the polyline. + */ public List<LatLng> getPoints() { // the getter gives us a copy, which is the safe thing to do... return polyline.getPoints(); } + /** + * Compares this {@link PolylineOptions} object with another {@link PolylineOptions} and + * determines if their color, alpha, width, and vertices match. + * + * @param o Another {@link PolylineOptions} to compare with this object. + * @return True if color, alpha, width, and vertices match this {@link PolylineOptions} object. + * Else, false. + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -138,6 +208,14 @@ public final class PolylineOptions implements Parcelable { return !(getPoints() != null ? !getPoints().equals(polyline.getPoints()) : polyline.getPoints() != null); } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { int result = 1; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java index 070d17bca2..40e447debe 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java @@ -44,12 +44,14 @@ public final class CameraPosition implements Parcelable { public final LatLng target; /** - * The angle, in degrees, of the camera angle from the nadir (directly facing the Earth). See tilt(double) for details of restrictions on the range of values. + * The angle, in degrees, of the camera angle from the nadir (directly facing the Earth). + * See tilt(float) for details of restrictions on the range of values. */ public final double tilt; /** - * Zoom level near the center of the screen. See zoom(double) for the definition of the camera's zoom level. + * Zoom level near the center of the screen. See zoom(float) for the definition of the camera's + * zoom level. */ public final double zoom; @@ -57,9 +59,12 @@ public final class CameraPosition implements Parcelable { * Constructs a CameraPosition. * * @param target The target location to align with the center of the screen. - * @param zoom Zoom level at target. See zoom(double) for details of restrictions. - * @param tilt The camera angle, in degrees, from the nadir (directly down). See tilt(double) for details of restrictions. - * @param bearing Direction that the camera is pointing in, in degrees clockwise from north. This value will be normalized to be within 0 degrees inclusive and 360 degrees exclusive. + * @param zoom Zoom level at target. See zoom(float) for details of restrictions. + * @param tilt The camera angle, in degrees, from the nadir (directly down). See tilt(float) + * for details of restrictions. + * @param bearing Direction that the camera is pointing in, in degrees clockwise from north. + * This value will be normalized to be within 0 degrees inclusive and 360 degrees + * exclusive. * @throws NullPointerException if target is null * @throws IllegalArgumentException if tilt is outside the range of 0 to 90 degrees inclusive. */ @@ -70,11 +75,24 @@ public final class CameraPosition implements Parcelable { this.zoom = zoom; } + /** + * Describe the kinds of special objects contained in this Parcelable's + * marshalled representation. + * + * @return integer 0. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written. May be 0 or + * {@link #PARCELABLE_WRITE_RETURN_VALUE}. + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeDouble(bearing); @@ -83,11 +101,24 @@ public final class CameraPosition implements Parcelable { out.writeDouble(zoom); } + /** + * Returns a String with the camera target, zoom, bearing and tilt. + * + * @return A String with CameraPosition information. + */ @Override public String toString() { return "Target: " + target + ", Zoom:" + zoom + ", Bearing:" + bearing + ", Tilt:" + tilt; } + /** + * Compares this {@link CameraPosition} object with another {@link CameraPosition} and + * determines if their target, zoom, tilt, and bearing match. + * + * @param o Another {@link CameraPosition} to compare with this object. + * @return True if target, zoom, tilt, and bearing match this {@link CameraPosition} object. + * Else, false. + */ @Override public boolean equals(Object o) { if (this == o) { @@ -111,6 +142,14 @@ public final class CameraPosition implements Parcelable { return true; } + /** + * Gives an integer which can be used as the bucket number for storing elements of the set/map. + * This bucket number is the address of the element inside the set/map. There's no guarantee + * that this hash value will be consistent between different Java implementations, or even + * between different execution runs of the same program. + * + * @return integer value you can use for storing element. + */ @Override public int hashCode() { int result = 1; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java index 637dbad654..9c96450a4c 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java @@ -43,8 +43,8 @@ public final class CameraUpdateFactory { } /** - * Returns a CameraUpdate that transforms the camera such that the specified latitude/longitude - * bounds are centered on screen at the greatest possible zoom level. + * Returns a {@link CameraUpdate} that transforms the camera such that the specified + * latitude/longitude bounds are centered on screen at the greatest possible zoom level. * You can specify padding, in order to inset the bounding box from the map view's edges. * The returned CameraUpdate has a bearing of 0 and a tilt of 0. * @@ -57,8 +57,8 @@ public final class CameraUpdateFactory { } /** - * Returns a CameraUpdate that transforms the camera such that the specified latitude/longitude - * bounds are centered on screen at the greatest possible zoom level. + * Returns a {@link CameraUpdate} that transforms the camera such that the specified + * latitude/longitude bounds are centered on screen at the greatest possible zoom level. * You can specify padding, in order to inset the bounding box from the map view's edges. * The returned CameraUpdate has a bearing of 0 and a tilt of 0. * @@ -74,8 +74,8 @@ public final class CameraUpdateFactory { } /** - * Returns a CameraUpdate that moves the center of the screen to a latitude and longitude specified by a LatLng object, - * and moves to the given zoom level. + * Returns a CameraUpdate that moves the center of the screen to a latitude and longitude + * specified by a LatLng object, and moves to the given zoom level. * * @param latLng Target location to change to * @param zoom Zoom level to change to @@ -119,7 +119,8 @@ public final class CameraUpdateFactory { } /** - * Returns a CameraUpdate that zooms in on the map by moving the viewpoint's height closer to the Earth's surface. The zoom increment is 1.0. + * Returns a CameraUpdate that zooms in on the map by moving the viewpoint's height closer to + * the Earth's surface. The zoom increment is 1.0. * * @return CameraUpdate Final Camera Position */ @@ -128,7 +129,8 @@ public final class CameraUpdateFactory { } /** - * Returns a CameraUpdate that zooms out on the map by moving the viewpoint's height farther away from the Earth's surface. The zoom increment is -1.0. + * Returns a CameraUpdate that zooms out on the map by moving the viewpoint's height farther + * away from the Earth's surface. The zoom increment is -1.0. * * @return CameraUpdate Final Camera Position */ diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TrackingSettings.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TrackingSettings.java index 7f655fbeef..ac620ca7ba 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TrackingSettings.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/TrackingSettings.java @@ -67,8 +67,8 @@ public class TrackingSettings { * </p> * Shows the direction the user is heading. * <p> - * When location tracking is disabled the direction of {@link MyLocationView} is rotated - * When location tracking is enabled the {@link MapView} is rotated based on bearing value. + * When location tracking is disabled the direction of {@link MyLocationView} is rotated. When + * location tracking is enabled the {@link MapView} is rotated based on the bearing value. * </p> * See {@link MyBearingTracking} for different values. * |