RouteTracker Class

Member Function Documentation

[since Esri::ArcGISRuntime 100.9] RouteTracker::RouteTracker(const Esri::ArcGISRuntime::RouteResult &routeResult, int routeIndex, bool skipCoincidentStops, QObject *parent = nullptr)

Creates a route tracker using a specific route from a route result, with an option to treat coincident stops as a single destination. The new route tracker will have a navigation mode of NavigationMode::Driving.

• routeResult - A RouteResult generated from route task solve. The RouteResult must contain at least one Route (with Route::stops and Route::directionManeuvers).
• routeIndex - Zero-based index into the array of RouteResult::routes, selecting a Route to track. The selected Route must contain Route::stops and Route::directionManeuvers.
• skipCoincidentStops - true if coincident stops (multiple stops in a row at the same location) should be treated as a single destination, false otherwise. When true, if there are multiple stops in a row at the same network location, the new voice guidance event will fire a single time and calling switchToNextDestinationAsync will skip over the other coincident stops, setting the state to the next relevant direction maneuver. If false, each stop will be treated as a unique destination. If your route does not have coincident stops this parameter will have no effect.
• parent - The optional parent QObject.

An error is emitted if the Route is not found or if it lacks Route::stops and Route::directionManeuvers.

This function was introduced in Esri::ArcGISRuntime 100.9.

[since Esri::ArcGISRuntime 300.0] RouteTracker::RouteTracker(const Esri::ArcGISRuntime::RouteResult &routeResult, int routeIndex, bool skipCoincidentStops, Esri::ArcGISRuntime::NavigationMode navigationMode, QObject *parent = nullptr)

Creates a RouteTracker from a specified route in a route result, an option for handling coincident stops, and a navigation mode. The default navigation mode is NavigationMode::Driving.

• routeResult - A RouteResult generated from route task solve. The RouteResult must contain at least one Route (with Route::stops and Route::directionManeuvers).
• routeIndex - Zero-based index into the array of RouteResult::routes, selecting a Route to track. The selected Route must contain Route::stops and Route::directionManeuvers.
• skipCoincidentStops - true if coincident stops (multiple stops in a row at the same location) should be treated as a single destination, false otherwise. When true, if there are multiple stops in a row at the same network location, the new voice guidance event will fire a single time and calling switchToNextDestinationAsync will skip over the other coincident stops, setting the state to the next relevant direction maneuver. If false, each stop will be treated as a unique destination. If your route does not have coincident stops this parameter will have no effect.
• navigationMode - The navigation mode to use for the route tracking. This determines how the route is followed and how navigation events are triggered.
• parent - The optional parent QObject.

An error is emitted if the Route is not found or if it lacks Route::stops and Route::directionManeuvers.

This function was introduced in Esri::ArcGISRuntime 300.0.

[override virtual noexcept] RouteTracker::~RouteTracker()

Destructor.

void RouteTracker::cancelRerouting()

Cancels a running reroute task.

If rerouting is in progress, this method will interrupt the background route task process.

void RouteTracker::disableRerouting() const

Disables automatic rerouting.

When disabled, the RouteTracker will not automatically recalculate a route when TrackingStatus::isOnRoute is false.

See also enableReroutingAsync(Esri::ArcGISRuntime::ReroutingParameters*).

[since Esri::ArcGISRuntime 200.2] QFuture<void> RouteTracker::enableReroutingAsync(Esri::ArcGISRuntime::ReroutingParameters *parameters)

Enables automatic rerouting when the tracker detects an off-route status.

• parameters - A ReroutingParameters allow customizing background rerouting.

Re-routing occurs only when the current location is off-route while on or near the transportation network edges. For example, if an off-route state is detected when the tracked location is in a parking lot (away from any transportation network edges), re-routing will not occur. It will occur only once a subsequent tracked location is on or near the transportation network edges. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

Esri::ArcGISRuntime::VoiceGuidance *RouteTracker::generateVoiceGuidance() const

Returns the current VoiceGuidance object.

The most recent voice guidance based on the last Location used by trackLocationAsync(const Esri::ArcGISRuntime::Location&). It can be used to repeat last/latest voice guidance.

See also TrackingStatus.

bool RouteTracker::isReroutingEnabled() const

Returns a bool that reports if routes are automatically regenerated when tracking status is off-route. true if rerouting is enabled, otherwise false.

See also enableReroutingAsync(Esri::ArcGISRuntime::ReroutingParameters*) and disableRerouting.

[since Esri::ArcGISRuntime 100.9] bool RouteTracker::isSkipCoincidentStops() const

Returns a bool that determines whether multiple consecutive stops at the same location should be treated as one stop. When true, if there are multiple consecutive stops at the same network location, the new voice guidance event will fire a single time. Calling Esri::ArcGISRuntime::RouteTracker::switchToNextDestinationAsync will skip over the other coincident stops, setting the state to the next relevant direction maneuver. If the value is false, each stop will be treated as a unique destination. The default value for this property is true. If your route does not have coincident stops, this property has no effect.

This function was introduced in Esri::ArcGISRuntime 100.9.

[since Esri::ArcGISRuntime 300.0] Esri::ArcGISRuntime::NavigationMode RouteTracker::navigationMode() const

Returns the navigation mode to use for the route tracking.

This determines how the route is followed and how navigation events are triggered. If not provided in the constructor, this defaults to NavigationMode::Driving.

This function was introduced in Esri::ArcGISRuntime 300.0.

[signal] void RouteTracker::newVoiceGuidance(Esri::ArcGISRuntime::VoiceGuidance *voiceGuidance)

Emitted when there is new voice guidance.

• voiceGuidance - new voice guidance.

The returned VoiceGuidance object has the RouteTracker as its parent.

See also Returned QObjects Parenting.

[signal] void RouteTracker::rerouteCompleted(Esri::ArcGISRuntime::TrackingStatus *trackingStatus, const Esri::ArcGISRuntime::Error &error)

Emitted when background rerouting is finished.

• trackingStatus - current TrackingStatus with recalculated RouteResult.
• error - populated if error occurs during rerouting, otherwise NULL.

The returned TrackingStatus object has the RouteTracker as its parent.

See also Returned QObjects Parenting.

[signal] void RouteTracker::rerouteStarted()

Emitted when background rerouting starts.

[since Esri::ArcGISRuntime 100.12] void RouteTracker::setSpeechEngineReadyFunction(std::function<bool ()> func)

Sets a function to be called to determine if the text-to-speech engine is ready to func.

The function is called by RouteTracker internally before newVoiceGuidance emits to check if the text-to-speech engine is busy. If it is busy it will postpone raising the voice guidance event until next time trackLocationAsync is called.

This will be called internally by RouteTracker on a background thread.

Setting this is optional, and if this is not set RouteTracker assumes the speech engine is always ready so that no voice guidance messages are skipped.

The function provided must return true if the engine is ready, false otherwise.

This can be set or unset at any time.

Here is an example of usage with a lambda.

// QTextToSpeech* m_speaker;
m_routeTracker->setSpeechEngineReadyFunction([speaker = m_speaker]() -> bool
{
  return speaker->state() == QTextToSpeech::State::Ready;
});

Here is an example of unsetting this if you no longer want it to be used.

m_routeTracker->setSpeechEngineReadyFunction({});

By default no function is set.

This function was introduced in Esri::ArcGISRuntime 100.12.

See also speechEngineReadyFunction().

void RouteTracker::setVoiceGuidanceUnitSystem(Esri::ArcGISRuntime::UnitSystem distanceUnit)

Sets the voiceGuidanceUnitSystem to distanceUnit.

See also voiceGuidanceUnitSystem.

[since Esri::ArcGISRuntime 100.12] std::function<bool ()> RouteTracker::speechEngineReadyFunction() const

Gets the function to be called to determine if the text-to-speech engine is ready, if any was set.

This function was introduced in Esri::ArcGISRuntime 100.12.

See also setSpeechEngineReadyFunction.

[since Esri::ArcGISRuntime 200.2] QFuture<void> RouteTracker::switchToNextDestinationAsync()

Starts tracking progress to the next destination in the Route.

Use switchToNextDestinationAsync when the tracker reports a DestinationStatus::Reached status. Before calling switchToNextDestinationAsync make sure that TrackingStatus::remainingDestinationCount > 1 (a value of 1 means navigation is proceeding to last destination). This method can also be called after DestinationStatus::Approaching is raised in cases where the location cannot get near enough to the destination point for DestinationStatus::Reached to be raised (such as the center of a park or shopping center, for example). trackLocationAsync(const Esri::ArcGISRuntime::Location&) needs to be called at least once before calling this method otherwise an error will be thrown. trackLocationAsync(const Esri::ArcGISRuntime::Location&) is needed for getting TrackingStatus and for handling visitFirstStopOnStart.

This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<void> RouteTracker::trackLocationAsync(const Esri::ArcGISRuntime::Location &location)

Returns the route tracking status relative to the provided location.

• location - A location used to evaluate status and progress along the route.

The location generally comes from a GPS but may also be a simulated or manually entered location. It must have valid values for X and Y coordinates, speed (in meters per second), course (in degrees), and a timestamp. Events fired for RouteTracker when completed. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

[since Esri::ArcGISRuntime 200.2] QFuture<void> RouteTracker::trackLocationAsync(const QGeoPositionInfo &gpsLocation)

Provides route tracking status relative to the provided location.

• gpsLocation - A location used to evaluate status and progress along the route.

The location generally comes from a GPS but may also be a simulated or manually entered location. It must have valid values for X and Y coordinates, speed (in meters per second), course (in degrees), and a timestamp. Events fired for RouteTracker when completed. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

See Working with QFuture for further details.

This function was introduced in Esri::ArcGISRuntime 200.2.

Esri::ArcGISRuntime::TrackingStatus *RouteTracker::trackingStatus() const

Returns the tracker status for the current location on the route.

[signal] void RouteTracker::trackingStatusChanged(Esri::ArcGISRuntime::TrackingStatus *trackingStatus)

Emitted when trackingStatus changes.

• trackingStatus - current TrackingStatus.

The returned TrackingStatus object has the RouteTracker as its parent.

See also Returned QObjects Parenting.

Esri::ArcGISRuntime::UnitSystem RouteTracker::voiceGuidanceUnitSystem()

Returns the unit system used in voice guidance commands.

Default value is UnitSystem::Metric. Supported values are UnitSystem::Metric and UnitSystem::Imperial.

See also setVoiceGuidanceUnitSystem().