com.dingi.dingisdk.location

Class LocationComponent

java.lang.Object

com.dingi.dingisdk.location.LocationComponent

public final class LocationComponent
extends java.lang.Object

The Location Component provides location awareness to your mobile application. Enabling this component 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 LocationComponentOptions.gpsDrawable()) we call the user puck.

This component 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).

To get the component object use DingiMap.getLocationComponent() and activate it with activateLocationComponent(Context) or one of the overloads. Then, manage its visibility with setLocationComponentEnabled(boolean).

Using this component requires you to request permission beforehand manually

This component offers a default, built-in LocationEngine with some of the activation methods. for more precise location updates, simply add the Google Play Location Services dependency in your build script. When activating the component for the first time, the map's max/min zoom levels will be set to LocationComponentOptions.MAX_ZOOM_DEFAULT and LocationComponentOptions.MIN_ZOOM_DEFAULT respectively. You can adjust the zoom range with LocationComponentOptions.maxZoom() and LocationComponentOptions.minZoom().

Location Component doesn't support state saving out-of-the-box.

Constructor Summary

Constructors

Constructor and Description
LocationComponent(DingiMap dingiMap) Internal use.

Method Summary

Modifier and Type	Method and Description
void	activateLocationComponent(android.content.Context context) This method initializes the component and needs to be called before any other operations are performed.
void	activateLocationComponent(android.content.Context context, boolean useDefaultLocationEngine) This method initializes the component and needs to be called before any other operations are performed.
void	activateLocationComponent(android.content.Context context, int styleRes) This method initializes the component and needs to be called before any other operations are performed.
void	activateLocationComponent(android.content.Context context, LocationComponentOptions options) This method initializes the component and needs to be called before any other operations are performed.
void	activateLocationComponent(android.content.Context context, com.mapbox.android.core.location.LocationEngine locationEngine) This method will show the location icon and enable the camera tracking the location.
void	activateLocationComponent(android.content.Context context, com.mapbox.android.core.location.LocationEngine locationEngine, int styleRes) This method initializes the component and needs to be called before any other operations are performed.
void	activateLocationComponent(android.content.Context context, com.mapbox.android.core.location.LocationEngine locationEngine, LocationComponentOptions options) This method initializes the component and needs to be called before any other operations are performed.
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(OnLocationClickListener listener) Adds a listener that gets invoked when the user clicks the displayed location.
void	addOnLocationLongClickListener(OnLocationLongClickListener listener) Adds a listener that gets invoked when the user long clicks the displayed location.
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(android.content.Context context, int styleRes) Apply a new component style with a style resource.
void	applyStyle(LocationComponentOptions options) Apply a new component style with location component options.
void	cancelTiltWhileTrackingAnimation() Cancels animation started by tiltWhileTracking(double, long, DingiMap.CancelableCallback).
void	cancelZoomWhileTrackingAnimation() Cancels animation started by zoomWhileTracking(double, long, DingiMap.CancelableCallback).
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.
CompassEngine	getCompassEngine() Returns the compass engine used to provide compass heading values.
float	getLastKnownCompassAccuracyStatus() Return the last known CompassEngine accuracy status of the location component.
android.location.Location	getLastKnownLocation() Get the last know location of the location component.
LocationComponentOptions	getLocationComponentOptions() Returns the current location options being used.
com.mapbox.android.core.location.LocationEngine	getLocationEngine() Returns the current LocationEngine being used for updating the user location.
int	getRenderMode() Provides the current render mode being used to show the location and/or compass updates on the map.
boolean	isLocationComponentEnabled() Returns whether the plugin is enabled, meaning that location can be displayed and camera modes can be used.
void	onDestroy() Internal use.
void	onFinishLoadingStyle() Internal use.
void	onStart() Internal use.
void	onStartLoadingMap() Internal use.
void	onStop() Internal use.
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(OnLocationClickListener listener) Removes the passed listener from the current list of location click listeners.
void	removeOnLocationLongClickListener(OnLocationLongClickListener 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	setCompassEngine(CompassEngine compassEngine) Sets the compass engine used to provide compass heading values.
void	setLocationComponentEnabled(boolean isEnabled) Manage component's visibility after activation.
void	setLocationEngine(com.mapbox.android.core.location.LocationEngine locationEngine) Set the location engine to update the current user location.
void	setRenderMode(int renderMode) Sets the render mode, which determines how the location updates will be rendered on the map.
void	tiltWhileTracking(double tilt) Tilts the camera.
void	tiltWhileTracking(double tilt, long animationDuration) Tilts the camera.
void	tiltWhileTracking(double tilt, long animationDuration, DingiMap.CancelableCallback callback) Tilts the camera.
void	zoomWhileTracking(double zoomLevel) Zooms to the desired zoom level.
void	zoomWhileTracking(double zoomLevel, long animationDuration) Zooms to the desired zoom level.
void	zoomWhileTracking(double zoomLevel, long animationDuration, DingiMap.CancelableCallback callback) Zooms to the desired zoom level.

Methods inherited from class java.lang.Object

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

Constructor Detail

LocationComponent

public LocationComponent(@NonNull
                         DingiMap dingiMap)

Internal use.

To get the component object use DingiMap.getLocationComponent().

Method Detail

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context)

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by setLocationComponentEnabled(boolean).

Note: This method will initialize and use an internal LocationEngine when enabled.

Parameters:

context - the context

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context,
                                      boolean useDefaultLocationEngine)

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by setLocationComponentEnabled(boolean).

Parameters:

context - the context

useDefaultLocationEngine - true if you want to initialize and use the built-in location engine or false if there should be no location engine initialized

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context,
                                      @StyleRes
                                      int styleRes)

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by setLocationComponentEnabled(boolean).

Note: This method will initialize and use an internal LocationEngine when enabled.

Parameters:

context - the context

styleRes - the LocationComponent style res

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context,
                                      @NonNull
                                      LocationComponentOptions options)

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by setLocationComponentEnabled(boolean).

Note: This method will initialize and use an internal LocationEngine when enabled.

Parameters:

context - the context

options - the options

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context,
                                      @Nullable
                                      com.mapbox.android.core.location.LocationEngine locationEngine,
                                      @StyleRes
                                      int styleRes)

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by setLocationComponentEnabled(boolean).

Parameters:

context - the context

locationEngine - the engine, or null if you'd like to only force location updates

styleRes - the LocationComponent style res

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context,
                                      @NonNull
                                      com.mapbox.android.core.location.LocationEngine locationEngine)

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

Parameters:

context - the context

locationEngine - the engine

activateLocationComponent

public void activateLocationComponent(@NonNull
                                      android.content.Context context,
                                      @Nullable
                                      com.mapbox.android.core.location.LocationEngine locationEngine,
                                      @NonNull
                                      LocationComponentOptions options)

This method initializes the component and needs to be called before any other operations are performed. Afterwards, you can manage component's visibility by setLocationComponentEnabled(boolean).

Parameters:

locationEngine - the engine, or null if you'd like to only force location updates

options - the options

setLocationComponentEnabled

public void setLocationComponentEnabled(boolean isEnabled)

Manage component's visibility after activation.

Parameters:

isEnabled - true if the plugin should be visible and listen for location updates, false otherwise.

isLocationComponentEnabled

public boolean isLocationComponentEnabled()

Returns whether the plugin is enabled, meaning that location can be displayed and camera modes can be used.

Returns:

true if the plugin is enabled, false otherwise

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

getCameraMode

public int getCameraMode()

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

Returns:

the current camera mode

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

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

getLocationComponentOptions

public LocationComponentOptions getLocationComponentOptions()

Returns the current location options being used.

Returns:

the current LocationComponentOptions

applyStyle

public void applyStyle(@NonNull
                       android.content.Context context,
                       @StyleRes
                       int styleRes)

Apply a new component style with a style resource.

Parameters:

styleRes - a XML style overriding some or all the options

applyStyle

public void applyStyle(@NonNull
                       LocationComponentOptions options)

Apply a new component style with location component options.

Parameters:

options - to update the current style

zoomWhileTracking

public void zoomWhileTracking(double zoomLevel,
                              long animationDuration,
                              @Nullable
                              DingiMap.CancelableCallback callback)

Zooms to the desired zoom level. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of DingiMap.moveCamera(CameraUpdate), DingiMap.easeCamera(CameraUpdate) or DingiMap.animateCamera(CameraUpdate) instead.

Parameters:

zoomLevel - The desired zoom level.

animationDuration - The zoom animation duration.

callback - The callback with finish/cancel information

zoomWhileTracking

public void zoomWhileTracking(double zoomLevel,
                              long animationDuration)

Zooms to the desired zoom level. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of DingiMap.moveCamera(CameraUpdate), DingiMap.easeCamera(CameraUpdate) or DingiMap.animateCamera(CameraUpdate) instead.

Parameters:

zoomLevel - The desired zoom level.

animationDuration - The zoom animation duration.

zoomWhileTracking

public void zoomWhileTracking(double zoomLevel)

Zooms to the desired zoom level. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of DingiMap.moveCamera(CameraUpdate), DingiMap.easeCamera(CameraUpdate) or DingiMap.animateCamera(CameraUpdate) instead.

Parameters:

zoomLevel - The desired zoom level.

cancelZoomWhileTrackingAnimation

public void cancelZoomWhileTrackingAnimation()

Cancels animation started by zoomWhileTracking(double, long, DingiMap.CancelableCallback).

tiltWhileTracking

public void tiltWhileTracking(double tilt,
                              long animationDuration,
                              @Nullable
                              DingiMap.CancelableCallback callback)

Tilts the camera. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of DingiMap.moveCamera(CameraUpdate), DingiMap.easeCamera(CameraUpdate) or DingiMap.animateCamera(CameraUpdate) instead.

Parameters:

tilt - The desired camera tilt.

animationDuration - The tilt animation duration.

callback - The callback with finish/cancel information

tiltWhileTracking

public void tiltWhileTracking(double tilt,
                              long animationDuration)

Tilts the camera. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of DingiMap.moveCamera(CameraUpdate), DingiMap.easeCamera(CameraUpdate) or DingiMap.animateCamera(CameraUpdate) instead.

Parameters:

tilt - The desired camera tilt.

animationDuration - The tilt animation duration.

tiltWhileTracking

public void tiltWhileTracking(double tilt)

Tilts the camera. This API can only be used in pair with camera modes other than CameraMode.NONE. If you are not using any of CameraMode modes, use one of DingiMap.moveCamera(CameraUpdate), DingiMap.easeCamera(CameraUpdate) or DingiMap.animateCamera(CameraUpdate) instead.

Parameters:

tilt - The desired camera tilt.

cancelTiltWhileTrackingAnimation

public void cancelTiltWhileTrackingAnimation()

Cancels animation started by tiltWhileTracking(double, long, DingiMap.CancelableCallback).

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

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 have to occur through the forceLocationUpdate(Location) method.

Parameters:

locationEngine - a LocationEngine this component should use to handle updates

getLocationEngine

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

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

Returns:

the LocationEngine being used to update the user location

setCompassEngine

public void setCompassEngine(@NonNull
                             CompassEngine compassEngine)

Sets the compass engine used to provide compass heading values.

Parameters:

compassEngine - to be used

getCompassEngine

@NonNull
public CompassEngine getCompassEngine()

Returns the compass engine used to provide compass heading values.

Returns:

compass engine currently being used

getLastKnownLocation

@Nullable
public android.location.Location getLastKnownLocation()

Get the last know location of the location component.

Returns:

the last known location

getLastKnownCompassAccuracyStatus

public float getLastKnownCompassAccuracyStatus()

Return the last known CompassEngine accuracy status of the location component.

The last known accuracy of the compass sensor, one of SensorManager.SENSOR_STATUS_*

Returns:

the last know compass accuracy bearing

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

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
                                       OnLocationClickListener listener)

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

If there are registered location click listeners and the location is clicked, only OnLocationClickListener.onLocationComponentClick() is going to be delivered, DingiMap.OnMapClickListener#onMapClick(LatLng) is going to be consumed and not pushed to the listeners registered after the component's activation.

Parameters:

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

removeOnLocationClickListener

public void removeOnLocationClickListener(@NonNull
                                          OnLocationClickListener listener)

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

Parameters:

listener - to be removed

addOnLocationLongClickListener

public void addOnLocationLongClickListener(@NonNull
                                           OnLocationLongClickListener listener)

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

If there are registered location long click listeners and the location is long clicked, only OnLocationLongClickListener.onLocationComponentLongClick() is going to be delivered, DingiMap.OnMapLongClickListener#onMapLongClick(LatLng) is going to be consumed and not pushed to the listeners registered after the component's activation.

Parameters:

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

removeOnLocationLongClickListener

public void removeOnLocationLongClickListener(@NonNull
                                              OnLocationLongClickListener listener)

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

Parameters:

listener - to be removed

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.

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.

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 LocationComponentOptions.staleStateTimeout().

Parameters:

listener - invoked when last update is considered stale

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

onStart

public void onStart()

Internal use.

onStop

public void onStop()

Internal use.

onDestroy

public void onDestroy()

Internal use.

onStartLoadingMap

public void onStartLoadingMap()

Internal use.

onFinishLoadingStyle

public void onFinishLoadingStyle()

Internal use.