Controls displaying position information and updates on a MapView. More...
| Header: | #include <LocationDisplay.h> |
| Since: | Esri::ArcGISRuntime 100.0 |
| Inherits: | Esri::ArcGISRuntime::Object |
This class was introduced in Esri::ArcGISRuntime 100.0.
Public Functions
| virtual | ~LocationDisplay() override |
| Esri::ArcGISRuntime::Symbol * | accuracySymbol() const |
| Esri::ArcGISRuntime::Symbol * | acquiringSymbol() const |
| int | acquiringTimeout() const |
| Esri::ArcGISRuntime::LocationDisplayAutoPanMode | autoPanMode() const |
| Esri::ArcGISRuntime::Symbol * | courseSymbol() const |
| Esri::ArcGISRuntime::AbstractLocationDataSource * | dataSource() const |
| Esri::ArcGISRuntime::Symbol * | defaultSymbol() const |
| double | heading() const |
| Esri::ArcGISRuntime::Symbol * | headingSymbol() const |
| double | initialZoomScale() const |
| bool | isShowAccuracy() const |
| bool | isShowLocation() const |
| bool | isShowPingAnimationSymbol() const |
| bool | isStarted() const |
| bool | isUseCourseSymbolOnMovement() const |
| Esri::ArcGISRuntime::Location | location() const |
| Esri::ArcGISRuntime::Point | mapLocation() const |
| float | navigationPointHeightFactor() const |
| float | opacity() const |
| Esri::ArcGISRuntime::Symbol * | pingAnimationSymbol() const |
| void | setAccuracySymbol(Esri::ArcGISRuntime::Symbol *accuracySymbol) |
| void | setAcquiringSymbol(Esri::ArcGISRuntime::Symbol *acquiringSymbol) |
| void | setAcquiringTimeout(int timeoutMilliseconds) |
| void | setAutoPanMode(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode) |
| void | setCourseSymbol(Esri::ArcGISRuntime::Symbol *courseSymbol) |
| void | setDataSource(Esri::ArcGISRuntime::AbstractLocationDataSource *dataSource) |
| void | setDefaultSymbol(Esri::ArcGISRuntime::Symbol *defaultSymbol) |
| void | setHeadingSymbol(Esri::ArcGISRuntime::Symbol *headingSymbol) |
| void | setInitialZoomScale(double initialScale) |
| void | setNavigationPointHeightFactor(float pointHeightFactor) |
| void | setOpacity(float opacity) |
| void | setPingAnimationSymbol(Esri::ArcGISRuntime::Symbol *pingSymbol) |
| void | setShowAccuracy(bool enable) |
| void | setShowLocation(bool enable) |
| void | setShowPingAnimationSymbol(bool enable) |
| void | setUseCourseSymbolOnMovement(bool enable) |
| void | setWanderExtentFactor(float wanderFactor) |
| void | start() |
| void | stop() |
| float | wanderExtentFactor() const |
Signals
| void | autoPanModeChanged(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode) |
| void | headingChanged() |
| void | locationChanged(Esri::ArcGISRuntime::Location location) |
| void | statusChanged(bool started) |
Detailed Description
Instances of this class manage the display of device location on a map - for instance, the symbols used, animation, auto pan behavior, and so on. Each MapView has its own instance of LocationDisplay. This means that you don't have to explicitly instantiate LocationDisplay, but rather, a newly created MapView already has a LocationDisplay that should be used.
The LocationDisplay does not proactively retrieve any location information. That is the job of its position source, which provides location updates on a regular basis. The position source is obtained from Qt's QGeoPositionInfoSource. To start displaying location, you first need to set the LocationDisplay's position source. Next, call start(). To stop displaying location, call stop().
Not all devices can determine their own location. Your app can check for location availability using the positionSource property's createDefaultSource method. It returns 0 if the device has no default position source, no valid plugins could be found, or the user does not have the permission to access the current position.
LocationDisplay is an overlay of the MapView, and displays over all layer types, as well as any GraphicsOverlays.
The LocationDisplay is made up of the following three visual components:
- The location symbol.
- The animated ping.
- The accuracy symbol.
By default, a round, blue symbol is used to display the device's location. This symbol is called the location symbol. The default position source tries to get the most accurate location available, but depending upon signal strength, satellite positions, and other factors, the location reported could be a best possible approximation. A semi-transparent circle around the location symbol indicates the range of accuracy. This is called the accuracy symbol. As the device moves and new location updates are provided by the position source, the location symbol will be repositioned on the map.
The location symbol will display as one of the following four symbols, depending on the auto pan mode, and whether the location is acquired:
- Default symbol: This symbol is displayed when the position is available.
- Course symbol: This symbol is displayed when the position is available, and the device's location is changing (the Location has both a velocity and course). The symbol rotates to point in the direction that the device is traveling, and is applicable in navigation, recenter, and off auto pan modes.
- Heading symbol: This symbol is displayed when the position and heading are available. Heading is the direction the device is pointing, relative to magnetic north. This symbol is only used in compass navigation auto pan mode.
- Location acquiring symbol: This symbol looks similar to the default symbol, except it is a gray color. This symbol indicates that the location being displayed is based on the last known position, and the new position is still being acquired.
Each of these location symbols can be overridden to use any other Symbol.
Example:
Show your current location on a map with the location display:
// turn on the location display m_mapView->locationDisplay()->start();
See also Location, QGeoPositionInfoSource, and QCompass.
Member Function Documentation
[signal] void LocationDisplay::autoPanModeChanged (Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode )
Emitted when the auto pan mode changes.
- autoPanMode - The auto pan mode.
[signal] void LocationDisplay::headingChanged ()
Emitted when the heading changes.
[signal] void LocationDisplay::locationChanged (Esri::ArcGISRuntime::Location location)
Emitted when the location changes.
- location - The most recent Location update.
[signal] void LocationDisplay::statusChanged (bool started)
Emitted when the status changes.
- started - Whether the LocationDisplay is started.
[override virtual] LocationDisplay::~LocationDisplay ()
Destructor.
Esri::ArcGISRuntime::Symbol *LocationDisplay::accuracySymbol () const
Gets the accuracySymbol to be used on the LocationDisplay.
See also setAccuracySymbol().
Esri::ArcGISRuntime::Symbol *LocationDisplay::acquiringSymbol () const
Gets the acquiringSymbol of the LocationDisplay.
See also setAcquiringSymbol().
int LocationDisplay::acquiringTimeout () const
The time in milliseconds between the last valid position update and displaying the acquiring symbol.
See also setAcquiringTimeout().
Esri::ArcGISRuntime::LocationDisplayAutoPanMode LocationDisplay::autoPanMode () const
Returns how location changes affect the current map view extent.
Any default zooming behavior (besides scrolling) or any operation that modifies the GeoView viewpoint will automatically set autoPanMode to false.
See also setAutoPanMode() and LocationDisplayAutoPanMode.
Esri::ArcGISRuntime::Symbol *LocationDisplay::courseSymbol () const
Gets the courseSymbol of the LocationDisplay.
See also setCourseSymbol().
Esri::ArcGISRuntime::AbstractLocationDataSource *LocationDisplay::dataSource () const
Returns the AbstractLocationDataSource used to update the display.
The LocationDisplay will be created with a DefaultLocationDataSource.
If you wish to use an alternative source for locations (for example an external GPS), you can can derive your own AbstractLocationDataSource and supply that instead.
This function was introduced in Esri::ArcGISRuntime 100.8.
See also setDataSource().
Esri::ArcGISRuntime::Symbol *LocationDisplay::defaultSymbol () const
Gets the defaultSymbol of the LocationDisplay.
See also setDefaultSymbol().
double LocationDisplay::heading() const
Gets the heading from the LocationDisplay.
Heading is the direction the device is pointing, relative to magnetic north. This will only be applicable when the autoPanMode is CompassNavigation. The value 0 means the device is pointed toward magnetic north, 90 means it is pointed due east, 180 means it is pointed due south, and so on. A negative value indicates that the heading could not be determined.
Esri::ArcGISRuntime::Symbol *LocationDisplay::headingSymbol () const
Gets the headingSymbol of the LocationDisplay.
See also setHeadingSymbol().
double LocationDisplay::initialZoomScale () const
The scale that the map should automatically be zoomed to upon receiving the first location update.
See also setInitialZoomScale().
bool LocationDisplay::isShowAccuracy () const
Gets whether the accuracy symbol is displayed.
Returns true if the accuracy symbol is displayed.
bool LocationDisplay::isShowLocation () const
Gets whether to show the location symbol.
Returns true if the location symbol is displayed.
bool LocationDisplay::isShowPingAnimationSymbol () const
Gets whether to show the ping animation symbol.
Returns true if the ping animation is displayed.
See also setPingAnimationSymbol.
bool LocationDisplay::isStarted () const
Gets whether the LocationDisplay is active.
Returns true if the LocationDisplay is active.
bool LocationDisplay::isUseCourseSymbolOnMovement () const
Gets whether to show the course symbol on movement.
Returns true if the course symbol will display on movement.
See also setCourseSymbol.
Esri::ArcGISRuntime::Location LocationDisplay::location() const
Gets the current Location from the LocationDisplay.
The Location will give access to things such as the point, course, accuracy, and velocity.
Esri::ArcGISRuntime::Point LocationDisplay::mapLocation () const
Gets the position of the location symbol as a point.
float LocationDisplay::navigationPointHeightFactor () const
Returns the navigation point height factor. The factor will decide the location symbol position vertically from the bottom of the map when the pan mode is in navigation mode. When navigating in a map, the current location is typically vertically positioned near the bottom of the map, and horizontally centered in the map, so that the map displays as much of the route ahead as possible.
See also setNavigationPointHeightFactor().
float LocationDisplay::opacity() const
Gets the opacity of content (all symbols) displayed by the LocationDisplay.
See also setOpacity().
Esri::ArcGISRuntime::Symbol *LocationDisplay::pingAnimationSymbol () const
Gets the pingAnimationSymbol of the LocationDisplay.
See also setPingAnimationSymbol().
void LocationDisplay::setAccuracySymbol (Esri::ArcGISRuntime::Symbol *accuracySymbol )
Sets the accuracySymbol to be used on the LocationDisplay.
The accuracy symbol displays a circle around the location symbol indicating the potential inaccuracy of the currently displayed position. By default, the symbol has a semi-transparent fill, and a blue outline.
See also accuracySymbol().
void LocationDisplay::setAcquiringSymbol (Esri::ArcGISRuntime::Symbol *acquiringSymbol )
Sets the acquiringSymbol to be used on the LocationDisplay.
The acquiring symbol will display once the acquiringTimeout has expired without a new position update. By default, the symbol is a grey marker symbol.
See also acquiringSymbol().
void LocationDisplay::setAcquiringTimeout (int timeoutMilliseconds )
Sets the acquiring symbol timeout to timeoutMilliseconds.
The default timeout is 5 seconds. If the acquiringTimeout is passed, the location symbol will change to display the location acquiring symbol (which is gray in color).
See also acquiringTimeout().
void LocationDisplay::setAutoPanMode (Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode )
Sets the autoPanMode on the LocationDisplay.
Auto pan modes define how the MapView will automatically pan when a new location update is received. There are several auto pan modes, including Navigation, CompassNavigation, Recenter, and Off. The auto pan mode will be Off by default. Further explanations of each different auto pan modes are covered in the LocationDisplayAutoPanMode enumeration documentation.
See also autoPanMode().
void LocationDisplay::setCourseSymbol (Esri::ArcGISRuntime::Symbol *courseSymbol )
Sets the courseSymbol to be used on the LocationDisplay.
The course symbol is displayed when the position is available, and the device's location is changing (the Location has both a velocity and course). The symbol is rotated to point in the direction that the device is traveling, and is applicable in navigation, recenter, and off auto pan modes. By default, the symbol is a PictureMarkerSymbol that displays a blue marker with a white arrow in the center.
See also courseSymbol().
void LocationDisplay::setDataSource (Esri::ArcGISRuntime::AbstractLocationDataSource *dataSource )
Sets the AbstractLocationDataSource used to update the display to dataSource.
This function was introduced in Esri::ArcGISRuntime 100.8.
See also dataSource.
void LocationDisplay::setDefaultSymbol (Esri::ArcGISRuntime::Symbol *defaultSymbol )
Sets the defaultSymbol to be used on the LocationDisplay.
The default symbol is displayed when the position is available, the device's location is not changing, and the auto pan mode is not CompassNavigation. By default, the symbol is a blue PictureMarkerSymbol.
See also defaultSymbol().
void LocationDisplay::setHeadingSymbol (Esri::ArcGISRuntime::Symbol *headingSymbol )
Sets the headingSymbol to be used on the LocationDisplay.
The heading symbol is displayed when the position and heading is available. Heading is the direction the device is pointing, relative to magnetic north. This symbol is only used when the auto pan mode is CompassNavigation. By default, the symbol is a blue PictureMarkerSymbol that indicates the current heading.
See also headingSymbol().
void LocationDisplay::setInitialZoomScale (double initialScale )
Sets the initialScale to display the MapView when LocationDisplay is started.
This is only applicable if the LocationDisplayAutoPanMode is Recenter, Navigation, or CompassNavigation. All three of these modes allow the MapView's Viewpoint to be updated automatically. If the auto pan mode is off, this property will be ignored.
The default value is 10,000, and the map will zoom to this scale upon receiving the first location update (as long as the auto pan mode is something other than Off). This zooming behavior can be turned off by setting the value to 0.
See also initialZoomScale().
void LocationDisplay::setNavigationPointHeightFactor (float pointHeightFactor )
Sets the pointHeightFactor to determine where the location symbol is displayed in the MapView while in Navigation mode.
This is only applicable when the LocationDisplayAutoPanMode is Navigation.
The position of the location symbol can be adjusted by calling setNavigationPointHeightFactor. A value of 0 implies the location symbol should be positioned at the bottom edge of the MapView, and a setting of 1 implies the top edge. A value between 0 and 1 positions the symbol somewhere along the center line from the bottom edge to the top edge. The default is 0.125 (1/8).
See also navigationPointHeightFactor().
void LocationDisplay::setOpacity (float opacity)
Sets the opacity of content (all symbols) displayed by the LocationDisplay.
The default value is 1. The opacity can be set to any float value from 0-1.
See also opacity().
void LocationDisplay::setPingAnimationSymbol (Esri::ArcGISRuntime::Symbol *pingSymbol )
Sets the pingSymbol to be used on the LocationDisplay.
The ping animation symbol displays an animation whenever a position update is received.
See also pingAnimationSymbol().
void LocationDisplay::setShowAccuracy (bool enable)
Sets whether to enable the accuracy symbol for display.
The default value is true.
See also isShowAccuracy().
void LocationDisplay::setShowLocation (bool enable)
Sets whether to enable the location symbol for display.
The default value is true.
See also isShowLocation().
void LocationDisplay::setShowPingAnimationSymbol (bool enable)
Sets whether to enable the ping animation for display.
The default value is true.
See also isShowPingAnimationSymbol() and setPingAnimationSymbol.
void LocationDisplay::setUseCourseSymbolOnMovement (bool enable)
Sets whether to enable the course symbol on movement.
The default value is true.
See also isUseCourseSymbolOnMovement() and setCourseSymbol.
void LocationDisplay::setWanderExtentFactor (float wanderFactor )
Sets the wanderFactor to be used on the LocationDisplay while in Recenter mode.
This is only applicable when the LocationDisplayAutoPanMode is Recenter. In this mode, the MapView attempts to keep the location symbol on the screen by recentering the MapView once the symbol moves outside of the wander extent. The location symbol can move freely within the wander extent, but as soon as the symbol exits the wander extent, the MapView will recenter on the symbol.
By default, the wanderExtentFactor is 0.5, which represents half the size of the MapView's extent. A value of 1 implies a wander extent equal to the size of the MapView's extent. This would result in the MapView recentering once the symbol reached the edge of the map. This factor could result in lighter CPU and battery consumption. A value of 0, however, implies an infinitesimal wander extent, and the map would potentially be re-centered on every location update. This factor could result in heavier CPU and battery consumption.
See also wanderExtentFactor().
void LocationDisplay::start()
Starts the LocationDisplay on the MapView.
To start successfully, the LocationDisplay must have a valid position source. If you attempt to start position display on an instance that is already started, it will complete without attempting to start it again. There is no need to check if it is started before calling start. If a user had previously denied the app access to location services, calling start again will again attempt to start. Calling start on the LocationDisplay will automatically attempt to start its position source (QGeoPositionInfoSource) as well.
void LocationDisplay::stop()
Stops the LocationDisplay on the MapView.
Calling stop on the LocationDisplay will automatically attempt to stop its position source (QGeoPositionInfoSource) as well. Location updates will no longer be received or displayed on the map.
float LocationDisplay::wanderExtentFactor () const
Gets the wanderExtentFactor used in the LocationDisplay while in Recenter mode.
See also setWanderExtentFactor().