com.mapbox.mapboxsdk.plugins.locationlayer

Class LocationLayerPlugin

java.lang.Object

com.mapbox.mapboxsdk.plugins.locationlayer.LocationLayerPlugin

All Implemented Interfaces:

android.arch.lifecycle.LifecycleObserver

public final class LocationLayerPlugin
extends java.lang.Object
implements android.arch.lifecycle.LifecycleObserver

The Location layer plugin provides location awareness to your mobile application. Enabling this plugin provides a contextual experience to your users by showing an icon representing the users current location. A few different modes are offered to provide the right context to your users at the correct time. RenderMode.NORMAL simply shows the users location on the map represented as a dot. RenderMode.COMPASS mode allows you to display an arrow icon (by default) that points in the direction the device is pointing in. RenderMode.GPS can be used in conjunction with our Navigation SDK to display a larger icon (customized with LocationLayerOptions.gpsDrawable()) we call the user puck.

This plugin also offers the ability to set a map camera behavior for tracking the user location. These different CameraModes will track, stop tracking the location based on the mode set with setCameraMode(int).

Lastly, setLocationLayerEnabled(boolean) can be used to disable the Location Layer but keep the instance around till the activity is destroyed.

Using this plugin requires you to request permission beforehand manually or using com.mapbox.android.core.permissions.PermissionsManager. Either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permissions can be requested and this plugin work as expected.

Since:

0.1.0

Constructor Summary

Constructors

Constructor and Description
LocationLayerPlugin(com.mapbox.mapboxsdk.maps.MapView mapView, com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap, com.mapbox.android.core.location.LocationEngine locationEngine) Construct a LocationLayerPlugin
LocationLayerPlugin(com.mapbox.mapboxsdk.maps.MapView mapView, com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap, com.mapbox.android.core.location.LocationEngine locationEngine, int styleRes) Construct a LocationLayerPlugin
LocationLayerPlugin(com.mapbox.mapboxsdk.maps.MapView mapView, com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap, com.mapbox.android.core.location.LocationEngine locationEngine, LocationLayerOptions options) Construct a LocationLayerPlugin

Method Summary

Modifier and Type	Method and Description
void	addCompassListener(CompassListener compassListener) Add a compass listener to get heading updates every second.
void	addOnCameraTrackingChangedListener(OnCameraTrackingChangedListener listener) Adds a listener that gets invoked when camera tracking state changes.
void	addOnLocationClickListener(OnLocationLayerClickListener listener) Adds a listener that gets invoked when the user clicks the location layer.
void	addOnLocationLongClickListener(OnLocationLayerLongClickListener listener) Adds a listener that gets invoked when the user long clicks the location layer.
void	addOnLocationStaleListener(OnLocationStaleListener listener) Adds the passed listener that gets invoked when user updates have stopped long enough for the last update to be considered stale.
void	applyStyle(int styleRes) Apply a new LocationLayer style with a style resource.
void	applyStyle(LocationLayerOptions options) Apply a new LocationLayer style with location layer options.
void	forceLocationUpdate(android.location.Location location) Use to either force a location update or to manually control when the user location gets updated.
int	getCameraMode() Provides the current camera mode being used to track the location or compass updates.
android.location.Location	getLastKnownLocation() Get the last know location of the location layer plugin.
com.mapbox.android.core.location.LocationEngine	getLocationEngine() Returns the current LocationEngine being used for updating the user location layer.
LocationLayerOptions	getLocationLayerOptions() Returns the current location options being used.
int	getRenderMode() Provides the current render mode being used to show the location and/or compass updates on the map.
void	onStart() Required to place inside your activities onStart method.
void	onStop() Required to place inside your activities onStop method.
void	removeCompassListener(CompassListener compassListener) Remove a compass listener.
void	removeOnCameraTrackingChangedListener(OnCameraTrackingChangedListener listener) Removes a listener that gets invoked when camera tracking state changes.
void	removeOnLocationClickListener(OnLocationLayerClickListener listener) Removes the passed listener from the current list of location click listeners.
void	removeOnLocationLongClickListener(OnLocationLayerLongClickListener listener) Removes the passed listener from the current list of location long click listeners.
void	removeOnLocationStaleListener(OnLocationStaleListener listener) Removes the passed listener from the current list of stale listeners.
void	setCameraMode(int cameraMode) Sets the camera mode, which determines how the map camera will track the rendered location.
void	setLocationEngine(com.mapbox.android.core.location.LocationEngine locationEngine) Set the location engine to update the current user location.
void	setLocationLayerEnabled(boolean isEnabled) This method will show or hide the location icon and enable or disable the camera tracking the location.
void	setRenderMode(int renderMode) Sets the render mode, which determines how the location updates will be rendered on the map.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LocationLayerPlugin

public LocationLayerPlugin(@NonNull
                           com.mapbox.mapboxsdk.maps.MapView mapView,
                           @NonNull
                           com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap,
                           @Nullable
                           com.mapbox.android.core.location.LocationEngine locationEngine)

Construct a LocationLayerPlugin

Parameters:

mapView - the MapView to apply the LocationLayerPlugin to

mapboxMap - the MapboxMap to apply the LocationLayerPlugin with

locationEngine - the LocationEngine this plugin should use to update

Since:

0.1.0

LocationLayerPlugin

public LocationLayerPlugin(@NonNull
                           com.mapbox.mapboxsdk.maps.MapView mapView,
                           @NonNull
                           com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap,
                           @Nullable
                           com.mapbox.android.core.location.LocationEngine locationEngine,
                           @StyleRes
                           int styleRes)

Construct a LocationLayerPlugin

Parameters:

mapView - the MapView to apply the LocationLayerPlugin to

mapboxMap - the MapboxMap to apply the LocationLayerPlugin with

locationEngine - the LocationEngine this plugin should use to update

styleRes - customize the user location icons inside your apps style.xml

Since:

0.1.0

LocationLayerPlugin

public LocationLayerPlugin(@NonNull
                           com.mapbox.mapboxsdk.maps.MapView mapView,
                           @NonNull
                           com.mapbox.mapboxsdk.maps.MapboxMap mapboxMap,
                           @Nullable
                           com.mapbox.android.core.location.LocationEngine locationEngine,
                           LocationLayerOptions options)

Construct a LocationLayerPlugin

Parameters:

mapView - the MapView to apply the LocationLayerPlugin to

mapboxMap - the MapboxMap to apply the LocationLayerPlugin with

locationEngine - the LocationEngine this plugin should use to update

options - to customize the user location icons inside your apps

Since:

0.3.0

Method Detail

setLocationLayerEnabled

public void setLocationLayerEnabled(boolean isEnabled)

This method will show or hide the location icon and enable or disable the camera tracking the location.

Parameters:

isEnabled - true to show layers and enable camera, false otherwise

Since:

0.5.0

setCameraMode

public void setCameraMode(int cameraMode)

Sets the camera mode, which determines how the map camera will track the rendered location.

• CameraMode.NONE: No camera tracking
• CameraMode.NONE_COMPASS: Camera does not track location, but does track compass bearing
• CameraMode.NONE_GPS: Camera does not track location, but does track GPS bearing
• CameraMode.TRACKING: Camera tracks the user location
• CameraMode.TRACKING_COMPASS: Camera tracks the user location, with bearing provided by a compass
• CameraMode.TRACKING_GPS: Camera tracks the user location, with normalized bearing
• CameraMode.TRACKING_GPS_NORTH: Camera tracks the user location, with bearing always set to north

Parameters:

cameraMode - one of the modes found in CameraMode

Since:

0.5.0

getCameraMode

public int getCameraMode()

Provides the current camera mode being used to track the location or compass updates.

Returns:

the current camera mode

Since:

0.5.0

setRenderMode

public void setRenderMode(int renderMode)

Sets the render mode, which determines how the location updates will be rendered on the map.

• RenderMode.NORMAL: Shows user location, bearing ignored
• RenderMode.COMPASS: Shows user location with bearing considered from compass
• RenderMode.GPS: Shows user location with bearing considered from location

Parameters:

renderMode - one of the modes found in RenderMode

Since:

0.5.0

getRenderMode

public int getRenderMode()

Provides the current render mode being used to show the location and/or compass updates on the map.

Returns:

the current render mode

Since:

0.5.0

getLocationLayerOptions

public LocationLayerOptions getLocationLayerOptions()

Returns the current location options being used.

Returns:

the current LocationLayerOptions

Since:

0.4.0

applyStyle

public void applyStyle(@StyleRes
                       int styleRes)

Apply a new LocationLayer style with a style resource.

Parameters:

styleRes - a XML style overriding some or all the options

Since:

0.4.0

applyStyle

public void applyStyle(LocationLayerOptions options)

Apply a new LocationLayer style with location layer options.

Parameters:

options - to update the current style

Since:

0.4.0

forceLocationUpdate

public void forceLocationUpdate(@Nullable
                                android.location.Location location)

Use to either force a location update or to manually control when the user location gets updated.

Parameters:

location - where the location icon is placed on the map

Since:

0.1.0

setLocationEngine

public void setLocationEngine(@Nullable
                              com.mapbox.android.core.location.LocationEngine locationEngine)

Set the location engine to update the current user location.

If null is passed in, all updates will occur through the forceLocationUpdate(Location) method.

Parameters:

locationEngine - a LocationEngine this plugin should use to handle updates

Since:

0.1.0

getLocationEngine

@Nullable
public com.mapbox.android.core.location.LocationEngine getLocationEngine()

Returns the current LocationEngine being used for updating the user location layer.

Returns:

the LocationEngine being used to update the user location layer

Since:

0.1.0

getLastKnownLocation

@Nullable
public android.location.Location getLastKnownLocation()

Get the last know location of the location layer plugin.

Returns:

the last known location

Since:

0.1.0

addCompassListener

public void addCompassListener(@NonNull
                               CompassListener compassListener)

Add a compass listener to get heading updates every second. Once the first listener gets added, the sensor gets initiated and starts returning values.

Parameters:

compassListener - a CompassListener for listening into compass heading and accuracy changes

Since:

0.2.0

removeCompassListener

public void removeCompassListener(@NonNull
                                  CompassListener compassListener)

Remove a compass listener.

Parameters:

compassListener - the CompassListener which you'd like to remove from the listener list.

addOnLocationClickListener

public void addOnLocationClickListener(@NonNull
                                       OnLocationLayerClickListener listener)

Adds a listener that gets invoked when the user clicks the location layer.

Parameters:

listener - The location layer click listener that is invoked when the location layer is clicked

Since:

0.3.0

removeOnLocationClickListener

public void removeOnLocationClickListener(@NonNull
                                          OnLocationLayerClickListener listener)

Removes the passed listener from the current list of location click listeners.

Parameters:

listener - to be removed

Since:

0.3.0

addOnLocationLongClickListener

public void addOnLocationLongClickListener(@NonNull
                                           OnLocationLayerLongClickListener listener)

Adds a listener that gets invoked when the user long clicks the location layer.

Parameters:

listener - The location layer click listener that is invoked when the location layer is clicked

Since:

0.5.0

removeOnLocationLongClickListener

public void removeOnLocationLongClickListener(@NonNull
                                              OnLocationLayerLongClickListener listener)

Removes the passed listener from the current list of location long click listeners.

Parameters:

listener - to be removed

Since:

0.5.0

addOnCameraTrackingChangedListener

public void addOnCameraTrackingChangedListener(@NonNull
                                               OnCameraTrackingChangedListener listener)

Adds a listener that gets invoked when camera tracking state changes.

Parameters:

listener - Listener that gets invoked when camera tracking state changes.

Since:

0.5.0

removeOnCameraTrackingChangedListener

public void removeOnCameraTrackingChangedListener(@NonNull
                                                  OnCameraTrackingChangedListener listener)

Removes a listener that gets invoked when camera tracking state changes.

Parameters:

listener - Listener that gets invoked when camera tracking state changes.

Since:

0.5.0

addOnLocationStaleListener

public void addOnLocationStaleListener(@NonNull
                                       OnLocationStaleListener listener)

Adds the passed listener that gets invoked when user updates have stopped long enough for the last update to be considered stale.

This timeout is set by LocationLayerOptions.staleStateTimeout().

Parameters:

listener - invoked when last update is considered stale

Since:

0.5.0

removeOnLocationStaleListener

public void removeOnLocationStaleListener(@NonNull
                                          OnLocationStaleListener listener)

Removes the passed listener from the current list of stale listeners.

Parameters:

listener - to be removed from the list

Since:

0.5.0

onStart

public void onStart()

Required to place inside your activities onStart method. You'll also most likely want to check that this Location Layer plugin instance inside your activity is null or not.

Since:

0.1.0

onStop

public void onStop()

Required to place inside your activities onStop method.

Since:

0.1.0