Skip To Content ArcGIS for Developers Sign In Dashboard

LocationDisplay Class

(Esri::ArcGISRuntime::LocationDisplay)

Controls displaying position information and updates on a MapView. More...

Header: #include <LocationDisplay>
Since: Esri::ArcGISRuntime 100.0
Inherits: Object

Public Functions

~LocationDisplay()
Symbol *accuracySymbol() const
Symbol *acquiringSymbol() const
int acquiringTimeout() const
LocationDisplayAutoPanMode autoPanMode() const
QCompass *compass() const
Symbol *courseSymbol() const
Symbol *defaultSymbol() const
double heading() const
Symbol *headingSymbol() const
double initialZoomScale() const
bool isShowAccuracy() const
bool isShowLocation() const
bool isShowPingAnimationSymbol() const
bool isStarted() const
bool isUseCourseSymbolOnMovement() const
Location location() const
Point mapLocation() const
float navigationPointHeightFactor() const
float opacity() const
Symbol *pingAnimationSymbol() const
QGeoPositionInfoSource *positionSource() const
void setAccuracySymbol(Symbol *accuracySymbol)
void setAcquiringSymbol(Symbol *acquiringSymbol)
void setAcquiringTimeout(int timeoutMilliseconds)
void setAutoPanMode(LocationDisplayAutoPanMode autoPanMode)
void setCompass(QCompass *compass)
void setCourseSymbol(Symbol *courseSymbol)
void setDefaultSymbol(Symbol *defaultSymbol)
void setHeadingSymbol(Symbol *headingSymbol)
void setInitialZoomScale(double initialScale)
void setNavigationPointHeightFactor(float pointHeightFactor)
void setOpacity(float opacity)
void setPingAnimationSymbol(Symbol *pingSymbol)
void setPositionSource(QGeoPositionInfoSource *positionSource)
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
  • 31 public functions inherited from QObject

Signals

void autoPanModeChanged(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode)
void headingChanged()
void locationChanged(Esri::ArcGISRuntime::Location location)
void statusChanged(bool started)

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public slot inherited from QObject
  • 1 public variable inherited from QObject
  • 10 static public members inherited from QObject
  • 9 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

Controls displaying position information and updates on a MapView.

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()->setPositionSource(QGeoPositionInfoSource::createDefaultSource(this));
QCompass* compass = new QCompass(this);
m_mapView->locationDisplay()->setCompass(compass);
m_mapView->locationDisplay()->start();

See also Location, QGeoPositionInfoSource, and QCompass.

Member Function Documentation

LocationDisplay::~LocationDisplay()

Destructor.

Symbol *LocationDisplay::accuracySymbol() const

Gets the accuracySymbol to be used on the LocationDisplay.

See also setAccuracySymbol().

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

LocationDisplayAutoPanMode LocationDisplay::autoPanMode() const

Gets the current LocationDisplayAutoPanMode that has been set to the LocationDisplay.

See also setAutoPanMode().

[signal] void LocationDisplay::autoPanModeChanged(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode)

Emitted when the auto pan mode changes.

  • autoPanMode - The auto pan mode.

QCompass *LocationDisplay::compass() const

Gets the QCompass that has been set to the LocationDisplay.

See also setCompass() and QCompass.

Symbol *LocationDisplay::courseSymbol() const

Gets the courseSymbol of the LocationDisplay.

See also setCourseSymbol().

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.

[signal] void LocationDisplay::headingChanged()

Emitted when the heading changes.

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.

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.

[signal] void LocationDisplay::locationChanged(Esri::ArcGISRuntime::Location location)

Emitted when the location changes.

  • location - The most recent Location update.

Point LocationDisplay::mapLocation() const

Gets the position of the location symbol as a point.

Where the location symbol is displayed in the MapView while in Navigation mode.

See also setNavigationPointHeightFactor().

float LocationDisplay::opacity() const

Gets the opacity of content (all symbols) displayed by the LocationDisplay.

See also setOpacity().

Symbol *LocationDisplay::pingAnimationSymbol() const

Gets the pingAnimationSymbol of the LocationDisplay.

See also setPingAnimationSymbol().

QGeoPositionInfoSource *LocationDisplay::positionSource() const

Gets the QGeoPositionInfoSource that has been set to the LocationDisplay.

See also setPositionSource() and QGeoPositionInfoSource.

void LocationDisplay::setAccuracySymbol(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(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(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::setCompass(QCompass *compass)

Sets the compass on the LocationDisplay.

To display position using a compass, two things must be done. First, a QCompass must be given to the LocationDisplay. This will acquire the azimuth and calibration level from the compass. Second, the LocationDisplayAutoPanMode must be set to CompassNavigation.

See also compass() and QCompass.

void LocationDisplay::setCourseSymbol(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::setDefaultSymbol(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(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(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::setPositionSource(QGeoPositionInfoSource *positionSource)

Sets the positionSource on the LocationDisplay.

The position source obtains and distributes the position updates. The LocationDisplay uses these updates to display the location on the MapView.

See also positionSource() and QGeoPositionInfoSource.

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.

[signal] void LocationDisplay::statusChanged(bool started)

Emitted when the status changes.

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


Feedback on this topic?