Package com.trimblemaps.navigation.ui.map

Class NavigationTrimbleMapsMap

  • All Implemented Interfaces:
    androidx.lifecycle.LifecycleObserver 
    @UiThread()
public class NavigationTrimbleMapsMap
 implements LifecycleObserver

    Wrapper class for TrimbleMapsMap.

    This class initializes various map-related components and plugins that are useful for providing a navigation-driven map experience.

    These APIs include drawing a route line, camera animations, and more.

    • Constructor Detail

    • Method Detail

      • addDestinationMarker

         void addDestinationMarker(Point position)

        Adds a marker icon on the map at the given position.

        The icon used for this method can be defined in your theme with the attribute navigationViewDestinationMarker.

        Parameters:
        position - the point at which the marker will be placed

      • addCustomMarker

         Symbol addCustomMarker(SymbolOptions options)

        Adds a custom marker to the map based on the options provided.

        Please note, the map will manage all markers added. Calling clearMarkers will clear all destination / custom markers that have been added to the map.

        Parameters:
        options - for the custom com.trimblemaps.mapsdk.plugins.annotation.Symbol

      • clearMarkerWithId

         void clearMarkerWithId(long markerId)

        Clears marker with the specified marker id.

        Please note, this only clears the marker added by addCustomMarker

        Parameters:
        markerId - of the com.trimblemaps.mapsdk.plugins.annotation.Symbol

      • clearMarkersWithIconImageProperty

         void clearMarkersWithIconImageProperty(String markerIconImageProperty)

        Clears all markers with the specified icon image.

        Please note, this only clears the markers added by addCustomMarker

        Parameters:
        markerIconImageProperty - of the com.trimblemaps.mapsdk.plugins.annotation.Symbol

      • clearMarkers

         void clearMarkers()

        Clears all markers on the map that have been added by this class.

        This will not clear all markers from the map entirely. Does nothing if no markers have been added.

      • updateLocation

         void updateLocation(@Nullable() Location location)

        Updates the location icon on the map and way name data (if found) for the given Location.

        NavigationTrimbleMapsMap automatically listens to onNewMapMatcherResult when a progress observer is subscribed with addProgressChangeListener and invoking this method in that scenario will lead to competing updates.

        Parameters:
        location - to update the icon and query the map

      • updateLocation

         void updateLocation(@Nullable() Location location, @Nullable() Long animationDuration)

        Updates the location icon on the map and way name data (if found) for the given Location.

        NavigationTrimbleMapsMap automatically listens to onNewMapMatcherResult when a progress observer is subscribed with addProgressChangeListener and invoking this method in that scenario will lead to competing updates.

        Parameters:
        location - to update the icon and query the map
        animationDuration - specifies the duration of the transition animation.

      • updateLocation

         void updateLocation(@NonNull() List<Location> locations)

        This method can be used to provide the list of locations where the last one is the target 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.

        NavigationTrimbleMapsMap automatically listens to onNewMapMatcherResult when a progress observer is subscribed with addProgressChangeListener and invoking this method in that scenario will lead to competing updates.

        Parameters:
        locations - the path to update the location icon

      • updateLocation

         void updateLocation(@NonNull() List<Location> locations, @Nullable() Long animationDuration)

        This method can be used to provide the list of locations where the last one is the target 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.

        NavigationTrimbleMapsMap automatically listens to onNewMapMatcherResult when a progress observer is subscribed with addProgressChangeListener and invoking this method in that scenario will lead to competing updates.

        Parameters:
        locations - the path to update the location icon
        animationDuration - specifies the duration of the transition animation.

      • updateLocation

         void updateLocation(@NonNull() Location location, @NonNull() List<Location> intermediateLocations, @Nullable() Long animationDuration)

        This method can be used to provide the target location and a list of 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.

        NavigationTrimbleMapsMap automatically listens to onNewMapMatcherResult when a progress observer is subscribed with addProgressChangeListener and invoking this method in that scenario will lead to competing updates.

        Parameters:
        location - the target position
        intermediateLocations - points that lead up to the target position for animation purposes
        animationDuration - specifies the duration of the transition animation.

      • updateMapFpsThrottle

         void updateMapFpsThrottle(int maxFpsThreshold)

        The maximum preferred frames per second at which to render the map.

        This property only takes effect when the application has limited resources, such as when the device is running on battery power. By default, this is set to 20fps.

        Throttling will also only take effect when the camera is currently tracking the user location.

        Parameters:
        maxFpsThreshold - to be used to limit map frames per second

      • updateMapFpsThrottleEnabled

         void updateMapFpsThrottleEnabled(boolean isEnabled)

        Enabled by default, the navigation map will throttle frames per second when the application has limited resources, such as when the device is running on battery power.

        Throttling will also only take effect when the camera is currently tracking the user location.

        Parameters:
        isEnabled - true to enable (default), false to render at device ability

      • updateLocationFpsThrottleEnabled

         void updateLocationFpsThrottleEnabled(boolean isEnabled)

        Enabled by default, the navigation map will throttle frames per second of the location icon based on the map zoom level.

        Parameters:
        isEnabled - true to enable (default), false to render at device ability

      • updateLocationLayerRenderMode

         void updateLocationLayerRenderMode(int renderMode)

        Updates how the user location is shown on the map.

        • NORMAL: Shows user location, bearing ignored
        • COMPASS: Shows user location with bearing considered from compass
        • GPS: Shows user location with bearing considered from location
        Parameters:
        renderMode - GPS, NORMAL, or COMPASS

      • addProgressChangeListener

         void addProgressChangeListener(@NonNull() TrimbleMapsNavigation navigation)

        Can be used to automatically drive the map camera, puck and route updates when STARTED.

        Use removeProgressChangeListener when the session is finished to avoid leaks.

        Parameters:
        navigation - to add the progress listeners

      • drawRoute

         void drawRoute(@NonNull() DirectionsRoute route)

        Will draw the given DirectionsRoute on the map using the colors defined in your given style.

        In most of the scenarios, this call can be wired to the onRoutesChanged to display the route that TrimbleMapsNavigation uses to compute the route progress.

        Parameters:
        route - to be drawn

      • drawRoutes

         void drawRoutes(@NonNull() List<out DirectionsRoute> routes, TrimbleMapsTrip trimbleMapsTrip, int stopNumberOffset)

        Will draw the given list of DirectionsRoute on the map using the colors defined in your given style.

        The primary route will default to the first route in the directions route list. All other routes in the list will be drawn on the map using the alternative route style.

        In most of the scenarios, this call can be wired to the onRoutesChanged to display the route that TrimbleMapsNavigation uses to compute the route progress.

        Parameters:
        routes - to be drawn

      • onNewRouteProgress

         void onNewRouteProgress(RouteProgress routeProgress)

        Can be used to manually update the route progress.

        NavigationTrimbleMapsMap automatically listens to onRouteProgressChanged when a progress observer is subscribed with addProgressChangeListener and invoking this method in that scenario will lead to competing updates.

        Parameters:
        routeProgress - current progress

      • showAlternativeRoutes

         void showAlternativeRoutes(boolean alternativesVisible)

        Toggle whether or not you'd like the map to display the alternative routes. This option can be used for when the user actually begins the navigation session and alternative routes aren't needed anymore.

        Parameters:
        alternativesVisible - true if you'd like alternative routes to be displayed on the map, else false

      • hideRoute

         void hideRoute()

        Will hide the drawn route displayed on the map. Does nothing if no route is drawn.

      • showRoute

         void showRoute()

        Will show the drawn route displayed on the map.

      • retrieveCamera

         NavigationCamera retrieveCamera()

        Provides the camera being used to animate the map camera positions along the route, driven by the progress change listener.

      • startCamera

         void startCamera(@NonNull() DirectionsRoute directionsRoute)

        Centers the map camera to the beginning of the provided DirectionsRoute.

        Parameters:
        directionsRoute - to update the camera position

      • resetCameraPositionWith

         void resetCameraPositionWith(int trackingCameraMode)

        Resets the map camera / padding to the last known camera position.

        You can also specify a tracking mode to reset with. For example if you would like to reset the camera and continue tracking, you would use NAVIGATION_TRACKING_MODE_GPS.

        Parameters:
        trackingCameraMode - the tracking mode

      • resetPadding

         void resetPadding()

        This method resets the map padding to the default padding that is generated when navigation begins (location icon moved to lower half of the screen) or the custom padding that was last passed via adjustLocationIconWith.

        The custom padding will be used if it exists, otherwise the default will be used.

      • showRouteGeometryOverview

         boolean showRouteGeometryOverview(Array<int> padding)

        Adjusts the map camera to DirectionsRoute being traveled along.

        Also includes the given padding.

        Parameters:
        padding - for creating the overview camera position

      • updateWaynameQueryMap

         void updateWaynameQueryMap(boolean isEnabled)

        Enables or disables the way name chip underneath the location icon.

        Parameters:
        isEnabled - true to enable, false to disable

      • updateLocationVisibilityTo

         void updateLocationVisibilityTo(boolean isVisible)

        Hide or show the location icon on the map.

        Parameters:
        isVisible - true to show, false to hide

      • retrieveMap

        @NonNull() TrimbleMapsMap retrieveMap()

        Provides the TrimbleMapsMap originally given in the constructor.

        This method gives access to all map-related APIs.

      • updateTrafficVisibility

         void updateTrafficVisibility(boolean isVisible)

        Updates the visibility of traffic layers on the map (if any exist).

        Parameters:
        isVisible - true if traffic should be visible, false otherwise

      • updateTruckRestrictionsVisibility

         void updateTruckRestrictionsVisibility(boolean isVisible)

        Updates the visibility of truck restrictions layers on the map (if any exist).

        Parameters:
        isVisible - true if restrictions should be visible, false otherwise

      • isTrafficVisible

         boolean isTrafficVisible()

        Returns true if the map has traffic layers and they are visible and will return false otherwise.

      • isTruckRestrictionsVisible

         boolean isTruckRestrictionsVisible()

        Returns true if the map has truck restrictions layers and they are visible and will return false otherwise.

      • addOnCameraTrackingChangedListener

         void addOnCameraTrackingChangedListener(@NonNull() OnCameraTrackingChangedListener listener)

        Add a OnCameraTrackingChangedListener to the LocationComponent that is wrapped within this class.

        This listener will fire any time camera tracking is dismissed or the camera mode is updated.

        Parameters:
        listener - to be added

      • removeOnCameraTrackingChangedListener

         void removeOnCameraTrackingChangedListener(@NonNull() OnCameraTrackingChangedListener listener)

        Remove a OnCameraTrackingChangedListener from the LocationComponent that is wrapped within this class.

        Parameters:
        listener - to be removed

      • adjustLocationIconWith

         void adjustLocationIconWith(@NonNull() Array<int> customPadding)

        Use this method to position the location icon on the map.

        For example, to position the icon in the center of the map, you can pass {0, 0, 0, 0} which eliminates the default padding we provide when navigation begins.

        Parameters:
        customPadding - true if should be centered on the map, false to position above the bottom view

      • setCamera

         void setCamera(Camera camera)

        Set Camera which allows you to perform operations like zoom, tilt etc.

        Parameters:
        camera - Camera

      • takeScreenshot

         void takeScreenshot(@NonNull() TrimbleMapsMap.SnapshotReadyCallback snapshotReadyCallback)

        Used to take the snapshot of the current state of the map.

      • enableVanishingRouteLine

         void enableVanishingRouteLine()

        This will enable the feature to change the appearance of the route line behind the puck as it moves across the map.

      • disableVanishingRouteLine

         void disableVanishingRouteLine()

        This will disable the feature to change the appearance of the route line behind the puck as it moves across the map.