com.mapbox.mapboxsdk.location

Class LocationComponentOptions

java.lang.Object

com.mapbox.mapboxsdk.location.LocationComponentOptions

All Implemented Interfaces:

android.os.Parcelable

public class LocationComponentOptions
extends java.lang.Object
implements android.os.Parcelable

This class exposes options for the Location Component. The options can be set by defining a style in your apps style.xml file and passing in directly into the LocationComponent class. Alternatively, if properties need to be changed at runtime depending on a specific state, you can build an instance of this class, setting the values you desire, and then passing it into either the LocationComponent activation method (if it isn't initialized yet) or LocationComponent.applyStyle(LocationComponentOptions).

When the createFromAttributes(Context, int) methods called, any attributes not found inside the style will revert back to using their default set values. Likewise, when building a new LocationComponentOptions class using the builder, any options neglecting to be set will reset to their default values.

If you would like to keep your custom style changes while modifying a single attribute, you can get the currently used options object using LocationComponent.getLocationComponentOptions() and it's toBuilder method to modify a single entry while also maintaining the other settings. Once your modifications have been made, you'll need to pass it back into the location component using LocationComponent.applyStyle(LocationComponentOptions).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocationComponentOptions.Builder Builder class for constructing a new instance of LocationComponentOptions.

Nested classes/interfaces inherited from interface android.os.Parcelable

android.os.Parcelable.ClassLoaderCreator<T>, android.os.Parcelable.Creator<T>

Field Summary

Fields

Modifier and Type	Field and Description
static float	CIRCLE_PULSING_MAX_RADIUS_DEFAULT Default maximum radius of the LocationComponent circle when it's pulsing.
static android.os.Parcelable.Creator<LocationComponentOptions>	CREATOR

Fields inherited from interface android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

Constructor Summary

Constructors

Modifier	Constructor and Description
	LocationComponentOptions(float accuracyAlpha, int accuracyColor, int backgroundDrawableStale, java.lang.String backgroundStaleName, int foregroundDrawableStale, java.lang.String foregroundStaleName, int gpsDrawable, java.lang.String gpsName, int foregroundDrawable, java.lang.String foregroundName, int backgroundDrawable, java.lang.String backgroundName, int bearingDrawable, java.lang.String bearingName, java.lang.Integer bearingTintColor, java.lang.Integer foregroundTintColor, java.lang.Integer backgroundTintColor, java.lang.Integer foregroundStaleTintColor, java.lang.Integer backgroundStaleTintColor, float elevation, boolean enableStaleState, long staleStateTimeout, int[] padding, float maxZoomIconScale, float minZoomIconScale, boolean trackingGesturesManagement, float trackingInitialMoveThreshold, float trackingMultiFingerMoveThreshold, android.graphics.RectF trackingMultiFingerProtectedMoveArea, java.lang.String layerAbove, java.lang.String layerBelow, float trackingAnimationDurationMultiplier, boolean compassAnimationEnabled, boolean accuracyAnimationEnabled, java.lang.Boolean pulseEnabled, java.lang.Boolean pulseFadeEnabled, java.lang.Integer pulseColor, float pulseSingleDuration, float pulseMaxRadius, float pulseAlpha, android.view.animation.Interpolator pulseInterpolator)
protected	LocationComponentOptions(android.os.Parcel in)

Method Summary

Modifier and Type	Method and Description
float	accuracyAlpha() Set the opacity of the accuracy view to a value from 0 to 1, where 0 means the accuracy view is completely transparent and 1 means the view is completely opaque.
boolean	accuracyAnimationEnabled() Enable or disable smooth animation of the accuracy circle around the user's position.
int	accuracyColor() Solid color to use as the accuracy view color property.
int	backgroundDrawable() Defines the drawable used for the background state icon.
int	backgroundDrawableStale() Defines the drawable used for the stale background icon.
java.lang.String	backgroundName() String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_backgroundDrawable.
java.lang.String	backgroundStaleName() String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will use this image in place of the provided or default mapbox_foregroundDrawableStale.
java.lang.Integer	backgroundStaleTintColor() Defines the background stale color as an integer.
java.lang.Integer	backgroundTintColor() Defines the background color as an integer.
int	bearingDrawable() Defines the drawable used for the bearing icon.
java.lang.String	bearingName() String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_bearingDrawable.
java.lang.Integer	bearingTintColor() Defines the bearing icon color as an integer.
static LocationComponentOptions.Builder	builder(android.content.Context context) Build a new instance of the LocationComponentOptions class with all the attributes set automatically to their defined defaults in this library.
boolean	compassAnimationEnabled() Enable or disable smooth animation of compass values for CameraMode and RenderMode.
static LocationComponentOptions	createFromAttributes(android.content.Context context, int styleRes) Construct a new Location Component Options class using the attributes found within a style resource.
int	describeContents()
float	elevation() Sets the base elevation of this view, in pixels.
boolean	enableStaleState() Enable or disable to stale state mode.
boolean	equals(java.lang.Object o)
int	foregroundDrawable() Supply a Drawable that is to be rendered on top of all of the content in the Location LayerComponent layer stack.
int	foregroundDrawableStale() Defines the drawable used for the stale foreground icon.
java.lang.String	foregroundName() String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_foregroundDrawable.
java.lang.String	foregroundStaleName() String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_foregroundDrawableStale.
java.lang.Integer	foregroundStaleTintColor() Defines the foreground stale color as an integer.
java.lang.Integer	foregroundTintColor() Defines the foreground color as an integer.
int	gpsDrawable() Defines the drawable used for the navigation state icon.
java.lang.String	gpsName() String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_gpsDrawable.
int	hashCode()
java.lang.String	layerAbove() Gets the id of the layer that's referenced when placing the component on the map using Style.addLayerAbove(Layer, String).
java.lang.String	layerBelow() Gets the id of the layer that's referenced when placing the component on the map using Style.addLayerBelow(Layer, String).
float	maxZoomIconScale() The scale factor of the location icon when the map is zoomed in.
float	minZoomIconScale() The scale factor of the location icon when the map is zoomed out.
int[]	padding() Sets the distance from the edges of the map view’s frame to the edges of the map view’s logical viewport.
float	pulseAlpha() The opacity of the LocationComponent's circle as it pulses.
java.lang.Integer	pulseColor() Color of the LocationComponent's pulsing circle as it pulses.
java.lang.Boolean	pulseEnabled() Enable or disable the LocationComponent's pulsing circle.
java.lang.Boolean	pulseFadeEnabled() Enable or disable fading of the LocationComponent's pulsing circle.
android.view.animation.Interpolator	pulseInterpolator() The interpolator type of animation for the movement of the LocationComponent's circle
float	pulseMaxRadius() The maximum radius that a single pulse should expand the LocationComponent's pulsing circle to.
float	pulseSingleDuration() The number of milliseconds it takes for a single pulse of the LocationComponent's pulsing circle.
long	staleStateTimeout() Set the delay before the location icon becomes stale.
LocationComponentOptions.Builder	toBuilder() Takes the currently constructed LocationComponentOptions object and provides it's builder with all the values set matching the values in this instance.
java.lang.String	toString()
float	trackingAnimationDurationMultiplier() Get the tracking animation duration multiplier.
boolean	trackingGesturesManagement() Returns whether gesture threshold should be adjusted when camera is in one of the tracking modes.
float	trackingInitialMoveThreshold() Minimum single pointer movement in pixels required to break camera tracking.
float	trackingMultiFingerMoveThreshold() Minimum multi pointer movement in pixels required to break camera tracking (for example during scale gesture).
android.graphics.RectF	trackingMultiFingerProtectedMoveArea() Protected multi pointer gesture area.
void	writeToParcel(android.os.Parcel dest, int flags)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

CIRCLE_PULSING_MAX_RADIUS_DEFAULT

public static final float CIRCLE_PULSING_MAX_RADIUS_DEFAULT

Default maximum radius of the LocationComponent circle when it's pulsing.

See Also:

Constant Field Values

CREATOR

public static final android.os.Parcelable.Creator<LocationComponentOptions> CREATOR

Constructor Detail

LocationComponentOptions

public LocationComponentOptions(float accuracyAlpha,
                                int accuracyColor,
                                int backgroundDrawableStale,
                                @Nullable
                                java.lang.String backgroundStaleName,
                                int foregroundDrawableStale,
                                @Nullable
                                java.lang.String foregroundStaleName,
                                int gpsDrawable,
                                @Nullable
                                java.lang.String gpsName,
                                int foregroundDrawable,
                                @Nullable
                                java.lang.String foregroundName,
                                int backgroundDrawable,
                                @Nullable
                                java.lang.String backgroundName,
                                int bearingDrawable,
                                @Nullable
                                java.lang.String bearingName,
                                @Nullable
                                java.lang.Integer bearingTintColor,
                                @Nullable
                                java.lang.Integer foregroundTintColor,
                                @Nullable
                                java.lang.Integer backgroundTintColor,
                                @Nullable
                                java.lang.Integer foregroundStaleTintColor,
                                @Nullable
                                java.lang.Integer backgroundStaleTintColor,
                                float elevation,
                                boolean enableStaleState,
                                long staleStateTimeout,
                                @Nullable
                                int[] padding,
                                float maxZoomIconScale,
                                float minZoomIconScale,
                                boolean trackingGesturesManagement,
                                float trackingInitialMoveThreshold,
                                float trackingMultiFingerMoveThreshold,
                                android.graphics.RectF trackingMultiFingerProtectedMoveArea,
                                java.lang.String layerAbove,
                                java.lang.String layerBelow,
                                float trackingAnimationDurationMultiplier,
                                boolean compassAnimationEnabled,
                                boolean accuracyAnimationEnabled,
                                java.lang.Boolean pulseEnabled,
                                java.lang.Boolean pulseFadeEnabled,
                                java.lang.Integer pulseColor,
                                float pulseSingleDuration,
                                float pulseMaxRadius,
                                float pulseAlpha,
                                @Nullable
                                android.view.animation.Interpolator pulseInterpolator)

LocationComponentOptions

protected LocationComponentOptions(android.os.Parcel in)

Method Detail

createFromAttributes

@NonNull
public static LocationComponentOptions createFromAttributes(@NonNull
                                                                     android.content.Context context,
                                                                     @StyleRes
                                                                     int styleRes)

Construct a new Location Component Options class using the attributes found within a style resource. It's important to note that you only need to define the attributes you plan to change and can safely ignore the other attributes which will be set to their default value.

Parameters:

context - your activity's context used for acquiring resources

styleRes - the style id where your custom attributes are defined

Returns:

a new LocationComponentOptions object with the settings you defined in your style resource

toBuilder

@NonNull
public LocationComponentOptions.Builder toBuilder()

Takes the currently constructed LocationComponentOptions object and provides it's builder with all the values set matching the values in this instance. This allows you to modify a single attribute and then rebuild the object.

Returns:

the builder which contains the values defined in this current instance as defaults.

builder

@NonNull
public static LocationComponentOptions.Builder builder(@NonNull
                                                                android.content.Context context)

Build a new instance of the LocationComponentOptions class with all the attributes set automatically to their defined defaults in this library. This allows you to adjust a few attributes while leaving the rest alone and maintaining their default behavior.

Parameters:

context - your activities context used to acquire the style resource

Returns:

the builder which contains the default values defined by the style resource

accuracyAlpha

public float accuracyAlpha()

Set the opacity of the accuracy view to a value from 0 to 1, where 0 means the accuracy view is completely transparent and 1 means the view is completely opaque. References style attribute R.styleable#LocationComponent_accuracyAlpha

Returns:

the opacity of the accuracy view

accuracyColor

@ColorInt
public int accuracyColor()

Solid color to use as the accuracy view color property. References style attribute R.styleable#LocationComponent_accuracyColor

Returns:

the color of the accuracy view

backgroundDrawableStale

@DrawableRes
public int backgroundDrawableStale()

Defines the drawable used for the stale background icon. References style attribute R.styleable#LocationComponent_backgroundDrawableStale

Returns:

the drawable resource ID

backgroundStaleName

@Nullable
public java.lang.String backgroundStaleName()

String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will use this image in place of the provided or default mapbox_foregroundDrawableStale.

A maki-icon name (example: "circle-15") may also be provided. These are images that can be loaded with certain styles. Note, this will fail if the provided icon name is not provided by the loaded map style.

Returns:

String icon or maki-icon name

foregroundDrawableStale

@DrawableRes
public int foregroundDrawableStale()

Defines the drawable used for the stale foreground icon. References style attribute R.styleable#LocationComponent_foregroundDrawableStale

Returns:

the drawable resource ID

foregroundStaleName

@Nullable
public java.lang.String foregroundStaleName()

String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_foregroundDrawableStale.

A maki-icon name (example: "circle-15") may also be provided. These are images that can be loaded with certain styles. Note, this will fail if the provided icon name is not provided by the loaded map style.

Returns:

String icon or maki-icon name

gpsDrawable

@DrawableRes
public int gpsDrawable()

Defines the drawable used for the navigation state icon. References style attribute R.styleable#LocationComponent_gpsDrawable

Returns:

the drawable resource ID

gpsName

@Nullable
public java.lang.String gpsName()

String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_gpsDrawable.

A maki-icon name (example: "circle-15") may also be provided. These are images that can be loaded with certain styles. Note, this will fail if the provided icon name is not provided by the loaded map style.

Returns:

String icon or maki-icon name

foregroundDrawable

@DrawableRes
public int foregroundDrawable()

Supply a Drawable that is to be rendered on top of all of the content in the Location LayerComponent layer stack. References style attribute R.styleable#LocationComponent_foregroundDrawable

Returns:

the drawable resource used for the foreground layer

foregroundName

@Nullable
public java.lang.String foregroundName()

String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_foregroundDrawable.

A maki-icon name (example: "circle-15") may also be provided. These are images that can be loaded with certain styles. Note, this will fail if the provided icon name is not provided by the loaded map style.

Returns:

String icon or maki-icon name

backgroundDrawable

@DrawableRes
public int backgroundDrawable()

Defines the drawable used for the background state icon. References style attribute R.styleable#LocationComponent_backgroundDrawable

Returns:

the drawable resource ID

backgroundName

@Nullable
public java.lang.String backgroundName()

String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_backgroundDrawable.

A maki-icon name (example: "circle-15") may also be provided. These are images that can be loaded with certain styles. Note, this will fail if the provided icon name is not provided by the loaded map style.

Returns:

String icon or maki-icon name

bearingDrawable

@DrawableRes
public int bearingDrawable()

Defines the drawable used for the bearing icon. References style attribute R.styleable#LocationComponent_bearingDrawable

Returns:

the drawable resource ID

bearingName

@Nullable
public java.lang.String bearingName()

String image name, identical to one used in the first parameter of Style.addImage(String, Bitmap), the component, will used this image in place of the provided or default mapbox_bearingDrawable.

A maki-icon name (example: "circle-15") may also be provided. These are images that can be loaded with certain styles. Note, this will fail if the provided icon name is not provided by the loaded map style.

Returns:

String icon or maki-icon name

bearingTintColor

@ColorInt
 @Nullable
public java.lang.Integer bearingTintColor()

Defines the bearing icon color as an integer. References style attribute R.styleable#LocationComponent_bearingTintColor

Returns:

the color integer resource

foregroundTintColor

@ColorInt
 @Nullable
public java.lang.Integer foregroundTintColor()

Defines the foreground color as an integer. References style attribute R.styleable#LocationComponent_foregroundTintColor

Returns:

the color integer resource

backgroundTintColor

@ColorInt
 @Nullable
public java.lang.Integer backgroundTintColor()

Defines the background color as an integer. References style attribute R.styleable#LocationComponent_backgroundTintColor

Returns:

the color integer resource

foregroundStaleTintColor

@ColorInt
 @Nullable
public java.lang.Integer foregroundStaleTintColor()

Defines the foreground stale color as an integer. References style attribute R.styleable#LocationComponent_foregroundStaleTintColor

Returns:

the color integer resource

backgroundStaleTintColor

@ColorInt
 @Nullable
public java.lang.Integer backgroundStaleTintColor()

Defines the background stale color as an integer. References style attribute R.styleable#LocationComponent_backgroundStaleTintColor

Returns:

the color integer resource

elevation

@Dimension
public float elevation()

Sets the base elevation of this view, in pixels. To turn off the shadow that appears under the location icon, set the elevation to 0. References style attribute R.styleable#LocationComponent_elevation

Returns:

the elevation currently set for the location component icon

enableStaleState

public boolean enableStaleState()

Enable or disable to stale state mode. This mode indicates to the user that the location being displayed on the map hasn't been updated in a specific amount of time. References style attribute R.styleable#LocationComponent_enableStaleState

Returns:

whether the stale state mode is enabled or not

staleStateTimeout

public long staleStateTimeout()

Set the delay before the location icon becomes stale. The timer begins approximately when a new location update comes in and using this defined time, if an update hasn't occured by the end, the location is considered stale. References style attribute R.styleable#LocationComponent_staleStateDelay

Returns:

the duration in milliseconds which it should take before the location is considered stale

padding

@Nullable
public int[] padding()

Sets the distance from the edges of the map view’s frame to the edges of the map view’s logical viewport.

When the value of this property is equal to {0,0,0,0}, viewport properties such as `centerCoordinate` assume a viewport that matches the map view’s frame. Otherwise, those properties are inset, excluding part of the frame from the viewport. For instance, if the only the top edge is inset, the map center is effectively shifted downward.

Returns:

integer array of padding values

maxZoomIconScale

public float maxZoomIconScale()

The scale factor of the location icon when the map is zoomed in. Scaling is linear.

Returns:

icon scale factor

minZoomIconScale

public float minZoomIconScale()

The scale factor of the location icon when the map is zoomed out. Scaling is linear.

Returns:

icon scale factor

trackingGesturesManagement

public boolean trackingGesturesManagement()

Returns whether gesture threshold should be adjusted when camera is in one of the tracking modes. This will adjust the focal point and increase thresholds to enable camera manipulation, like zooming in and out, without breaking tracking.

Note: If set to true, this can overwrite some of the gesture thresholds and the custom AndroidGesturesManager that was set with MapboxMap.setGesturesManager(AndroidGesturesManager, boolean, boolean).

Returns:

true if gestures are adjusted when in one of the camera tracking modes, false otherwise

See Also:

LocationComponentOptions.Builder.trackingInitialMoveThreshold(float), LocationComponentOptions.Builder.trackingMultiFingerMoveThreshold(float), LocationComponentOptions.Builder.trackingMultiFingerProtectedMoveArea(RectF)

trackingInitialMoveThreshold

public float trackingInitialMoveThreshold()

Minimum single pointer movement in pixels required to break camera tracking.

Returns:

the minimum movement

trackingMultiFingerMoveThreshold

public float trackingMultiFingerMoveThreshold()

Minimum multi pointer movement in pixels required to break camera tracking (for example during scale gesture).

Returns:

the minimum movement

trackingMultiFingerProtectedMoveArea

@Nullable
public android.graphics.RectF trackingMultiFingerProtectedMoveArea()

Protected multi pointer gesture area. When the camera is in a tracking mode, any multi finger gesture with focal point inside the provided screen coordinate rectangle is not going to break the tracking.

Best paired with the LocationComponentOptions.Builder.trackingMultiFingerMoveThreshold(float) set to 0 or a relatively small value to not interfere with gestures outside of the defined rectangle.

Returns:

the protected multi finger area while camera is tracking

layerAbove

public java.lang.String layerAbove()

Gets the id of the layer that's referenced when placing the component on the map using Style.addLayerAbove(Layer, String).

The component is going to placed directly above this layer.

Returns:

layerAbove the id of the layer the component is going to placed directly above.

layerBelow

public java.lang.String layerBelow()

Gets the id of the layer that's referenced when placing the component on the map using Style.addLayerBelow(Layer, String).

The component is going to placed directly below this layer.

Returns:

layerBelow the id of the layer the component is going to placed directly below.

trackingAnimationDurationMultiplier

public float trackingAnimationDurationMultiplier()

Get the tracking animation duration multiplier.

Returns:

tracking animation duration multiplier

compassAnimationEnabled

public boolean compassAnimationEnabled()

Enable or disable smooth animation of compass values for CameraMode and RenderMode.

Returns:

whether smooth compass animation is enabled

accuracyAnimationEnabled

public boolean accuracyAnimationEnabled()

Enable or disable smooth animation of the accuracy circle around the user's position.

Returns:

whether smooth animation of the accuracy circle is enabled

pulseEnabled

public java.lang.Boolean pulseEnabled()

Enable or disable the LocationComponent's pulsing circle.

Returns:

whether the LocationComponent's pulsing circle is enabled

pulseFadeEnabled

public java.lang.Boolean pulseFadeEnabled()

Enable or disable fading of the LocationComponent's pulsing circle. If it fades, the circle's opacity decreases as its radius increases.

Returns:

whether fading of the LocationComponent's pulsing circle is enabled

pulseColor

public java.lang.Integer pulseColor()

Color of the LocationComponent's pulsing circle as it pulses.

Returns:

the current set color of the circle

pulseSingleDuration

public float pulseSingleDuration()

The number of milliseconds it takes for a single pulse of the LocationComponent's pulsing circle.

Returns:

the current set length of time for a single pulse

pulseMaxRadius

public float pulseMaxRadius()

The maximum radius that a single pulse should expand the LocationComponent's pulsing circle to.

Returns:

the maximum radius that the pulsing circle will expand to.

pulseAlpha

public float pulseAlpha()

The opacity of the LocationComponent's circle as it pulses. The expected range is 0 to 1. An opacity of 1 makes the layer fully visible.

Returns:

the current opacity of the LocationComponent's pulsing circle

pulseInterpolator

@Nullable
public android.view.animation.Interpolator pulseInterpolator()

The interpolator type of animation for the movement of the LocationComponent's circle

Returns:

the current set type of animation interpolator for the pulsing circle

toString

@NonNull
public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

describeContents

public int describeContents()

Specified by:

describeContents in interface android.os.Parcelable

writeToParcel

public void writeToParcel(android.os.Parcel dest,
                          int flags)

Specified by:

writeToParcel in interface android.os.Parcelable