Package com.trimblemaps.mapsdk.location

Class LocationComponent

java.lang.Object
com.trimblemaps.mapsdk.location.LocationComponent
public final class LocationComponent extends 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 TrimbleMapsMap.getLocationComponent() and activate it with activateLocationComponent(LocationComponentActivationOptions). Then, manage its visibility with setLocationComponentEnabled(boolean). The component will not process location updates right after activation, but only after being enabled.

Using this component requires you to request permission beforehand manually or using PermissionsManager. Either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permissions can be requested for this component to work as expected.

This component offers a default, built-in LocationEngine called TrimbleMapsFusedLocationEngineImpl. If you'd like to utilize the previously available Google Play Services for more precise location updates, refer to the migration guide of 10.0.0 in the changelog. After a custom engine is passed to the component, or the built-in is initialized, the location updates are going to be requested with the LocationEngineRequest, either a default one, or the one passed during the activation. When using any engine, requesting/removing the location updates is going to be managed internally.

You can also push location updates to the component without any internal engine management. To achieve that, set `useDefaultLocationEngine` in LocationComponentActivationOptions to false. No engine is going to be initialized and you can push location updates with forceLocationUpdate(Location).

For location puck animation purposes, like navigation, we recommend limiting the maximum zoom level of the map for the best user experience.

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

  • Constructor Details

  • Method Details

    • activateLocationComponent

      public void activateLocationComponent(@NonNull LocationComponentActivationOptions activationOptions)
      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:
      activationOptions - a fully built LocationComponentActivationOptions object

    • setLocationComponentEnabled

      @RequiresPermission(anyOf={"android.permission.ACCESS_FINE_LOCATION","android.permission.ACCESS_COARSE_LOCATION"}) 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.

      When camera is transitioning to a new mode, it will reject inputs like zoomWhileTracking(double) or tiltWhileTracking(double). Use OnLocationCameraTransitionListener to listen for the transition state.

      Parameters:
      cameraMode - one of the modes found in CameraMode

    • setCameraMode

      public void setCameraMode(int cameraMode, @Nullable OnLocationCameraTransitionListener transitionListener)
      Sets the camera mode, which determines how the map camera will track the rendered location.

      When camera is transitioning to a new mode, it will reject inputs like zoomWhileTracking(double) or tiltWhileTracking(double). Use OnLocationCameraTransitionListener to listen for the transition state.

      Parameters:
      cameraMode - one of the modes found in CameraMode
      transitionListener - callback that's going to be invoked when the transition animation finishes

    • setCameraMode

      public void setCameraMode(int cameraMode, long transitionDuration, @Nullable Double zoom, @Nullable Double bearing, @Nullable Double tilt, @Nullable OnLocationCameraTransitionListener transitionListener)
      Sets the camera mode, which determines how the map camera will track the rendered location.

      When camera is transitioning to a new mode, it will reject inputs like zoomWhileTracking(double) or tiltWhileTracking(double). Use OnLocationCameraTransitionListener to listen for the transition state.

      Set values of zoom, bearing and tilt that the camera will transition to. If null is passed to any of those, current value will be used for that parameter instead. If the camera is already tracking, provided values are ignored.

      Parameters:
      cameraMode - one of the modes found in CameraMode
      transitionDuration - duration of the transition in milliseconds
      zoom - target zoom, set to null to use current camera position
      bearing - target bearing, set to null to use current camera position
      tilt - target tilt, set to null to use current camera position
      transitionListener - callback that's going to be invoked when the transition animation finishes

    • 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.

      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 TrimbleMapsMap.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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the zoom change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the zoom as a camera change argument.

      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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the zoom change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the zoom as a camera change argument.

      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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the zoom change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the zoom as a camera change argument.

      Parameters:
      zoomLevel - The desired zoom level.

    • cancelZoomWhileTrackingAnimation

      public void cancelZoomWhileTrackingAnimation()
      Cancels animation started by zoomWhileTracking(double, long, TrimbleMapsMap.CancelableCallback).

    • paddingWhileTracking

      public void paddingWhileTracking(double[] padding)
      Sets the padding. 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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the padding change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the padding as a camera change argument.

      Parameters:
      padding - The desired padding.

    • paddingWhileTracking

      public void paddingWhileTracking(double[] padding, long animationDuration)
      Sets the padding. 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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the padding change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the padding as a camera change argument.

      Parameters:
      padding - The desired padding.
      animationDuration - The padding animation duration.

    • paddingWhileTracking

      public void paddingWhileTracking(double[] padding, long animationDuration, @Nullable TrimbleMapsMap.CancelableCallback callback)
      Sets the padding. 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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the padding change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the padding as a camera change argument.

      Parameters:
      padding - The desired padding.
      animationDuration - The padding animation duration.
      callback - The callback with finish/cancel information

    • cancelPaddingWhileTrackingAnimation

      public void cancelPaddingWhileTrackingAnimation()
      Cancels animation started by paddingWhileTracking(double[], long, TrimbleMapsMap.CancelableCallback).

    • tiltWhileTracking

      public void tiltWhileTracking(double tilt, long animationDuration, @Nullable TrimbleMapsMap.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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the tilt change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the tilt as a camera change argument.

      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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the tilt change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the tilt as a camera change argument.

      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 TrimbleMapsMap.moveCamera(CameraUpdate), TrimbleMapsMap.easeCamera(CameraUpdate) or TrimbleMapsMap.animateCamera(CameraUpdate) instead.

      If the camera is transitioning when the tilt change is requested, the call is going to be ignored. Use LocationComponent.CameraTransitionListener to chain the animations, or provide the tilt as a camera change argument.

      Parameters:
      tilt - The desired camera tilt.

    • cancelTiltWhileTrackingAnimation

      public void cancelTiltWhileTrackingAnimation()
      Cancels animation started by tiltWhileTracking(double, long, TrimbleMapsMap.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

    • forceLocationUpdate

      public void forceLocationUpdate(@NonNull LocationUpdate locationUpdate)

    • forceLocationUpdate

      public void forceLocationUpdate(@Nullable List<android.location.Location> locations, boolean lookAheadUpdate)
      Use to either force a location update or to manually control when the user location gets updated.

      This method can be used to provide the list of locations where the last one is the target location and the rest are intermediate points used as the animation path. The puck and the camera will be animated between each of the points linearly until reaching the target.

      Parameters:
      locations - where the location icon is placed on the map
      lookAheadUpdate - If set to true, the last location's timestamp has to be greater than current timestamp and should represent the time at which the animation should actually reach this position, cutting out the time interpolation delay.

    • setMaxAnimationFps

      public void setMaxAnimationFps(int maxAnimationFps)
      Set max FPS at which location animators can output updates. The throttling will only impact the location puck and camera tracking smooth animations.

      Setting this will not impact any other animations schedule with TrimbleMapsMap, gesture animations or zoomWhileTracking(double)/tiltWhileTracking(double).

      Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.

      Example usage: 

       
 TrimbleMapsMap.addOnCameraIdleListener(new TrimbleMapsMap.OnCameraIdleListener() {
   {@literal @}Override
   public void onCameraIdle() {
     double zoom = TrimbleMapsMap.getCameraPosition().zoom;
     int maxAnimationFps;
     if (zoom < 5) {
       maxAnimationFps = 3;
     } else if (zoom < 10) {
       maxAnimationFps = 5;
     } else if (zoom < 15) {
       maxAnimationFps = 7;
     } else if (zoom < 18) {
       maxAnimationFps = 15;
     } else {
       maxAnimationFps = Integer.MAX_VALUE;
     }
     locationComponent.setMaxAnimationFps(maxAnimationFps);
   }
 });

      If you're looking for a way to throttle the FPS of the whole map, including other animations and gestures, see MapView.setMaximumFps(int).

      Parameters:
      maxAnimationFps - max location animation FPS

    • setLocationEngine

      public void setLocationEngine(@Nullable com.trimblemaps.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

    • setLocationEngineRequest

      public void setLocationEngineRequest(@NonNull com.trimblemaps.android.core.location.LocationEngineRequest locationEngineRequest)
      Set the location request that's going to be used when requesting location updates.
      Parameters:
      locationEngineRequest - the location request

    • getLocationEngineRequest

      @NonNull public com.trimblemaps.android.core.location.LocationEngineRequest getLocationEngineRequest()
      Get the location request that's going to be used when requesting location updates.

    • getLocationEngine

      @Nullable public com.trimblemaps.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(@Nullable CompassEngine compassEngine)
      Sets the compass engine used to provide compass heading values.
      Parameters:
      compassEngine - to be used

    • getCompassEngine

      @Nullable 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

    • 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, TrimbleMapsMap.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, TrimbleMapsMap.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.

    • addOnRenderModeChangedListener

      public void addOnRenderModeChangedListener(@NonNull OnRenderModeChangedListener listener)
      Adds a listener that gets invoked when render mode changes.
      Parameters:
      listener - Listener that gets invoked when render mode changes.

    • removeRenderModeChangedListener

      public void removeRenderModeChangedListener(@NonNull OnRenderModeChangedListener listener)
      Removes a listener that gets invoked when render mode changes.
      Parameters:
      listener - Listener that gets invoked when render mode 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

    • addOnIndicatorPositionChangedListener

      public void addOnIndicatorPositionChangedListener(@NonNull OnIndicatorPositionChangedListener listener)
      Adds a listener that gets invoked when indicator position changes.
      Parameters:
      listener - Listener that gets invoked when indicator position changes

    • removeOnIndicatorPositionChangedListener

      public void removeOnIndicatorPositionChangedListener(@NonNull OnIndicatorPositionChangedListener listener)
      Removes a listener that gets invoked when indicator position changes.
      Parameters:
      listener - Listener that gets invoked when indicator position changes.

    • 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.

    • isLocationComponentActivated

      public boolean isLocationComponentActivated()
      Returns whether the location component is activated.
      Returns:
      true if the component is activated, false otherwise