Skip To Content ArcGIS for Developers Sign In Dashboard

LocationDisplay QML Type

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

Import Statement: import Esri.ArcGISRuntime 100.6
Since: Esri.ArcGISRuntime 100.0
Inherits:

Object

Properties

Signals

Methods

Detailed Description

Note: You cannot declare or create a component of this type in QML code.

Instances of this type 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 PositionSource QML Type. To start displaying location, you will 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 supportedPositioningMethods property. This property is set to QGeoPositionInfoSource::NoPositioningMethods (0x0) when there is no position source.

The LocationDisplay is an overlay of the MapView, and displays over top of all Layer types, as well as any GraphicsOverlays.

The LocationDisplay is made up of 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 four different 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 is available. Heading is the direction the device is pointing in, 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.

For an example, see a QML sample using LocationDisplay.

See also Location, PositionSource QML Type, and Compass QML Type.

Property Documentation

accuracySymbol : Symbol

The accuracy symbol 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.


acquiringSymbol : Symbol

The acquiring symbol 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.


acquiringTimeoutMs : int

The time in milliseconds between the last valid position update and displaying the acquiring symbol.

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


autoPanMode : Enums.LocationDisplayAutoPanMode

The auto pan mode 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, compass navigation, 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 Enums.LocationDisplayAutoPanMode.


compass : Compass

The compass of the LocationDisplay.

In order to display position using a compass, two things must be done. First, a Compass must be given to the LocationDisplay. This will acquire the azimuth and calibration level from the compass. Second, the autoPanMode must be set to compass navigation.

See also Compass QML Type.


courseSymbol : Symbol

The course symbol 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 middle.


defaultSymbol : Symbol

The default symbol 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 autoPanMode is not compass navigation. By default, the symbol is a blue PictureMarkerSymbol.


heading : double

Returns the heading from the LocationDisplay (read-only).

Heading is the direction the device is pointing in, relative to magnetic north. This will only be applicable when the autoPanMode is compass navigation. 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.


headingSymbol : Symbol

The heading symbol 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 in, relative to magnetic north. This symbol is only used when the autoPanMode is compass navigation. By default, the symbol is a blue PictureMarkerSymbol that indicates the current heading.


initialZoomScale : double

The scale that the map should automatically be zoomed to upon receiving the first location update.

This is only applicable if the autoPanMode is recenter, navigation, or compass navigation. 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.


location : Location

Returns the current Location from the LocationDisplay (read-only).

The Location will give access to things such as the point, course, accuracy, and velocity.


mapLocation : Point

Returns the position of the location symbol as a Point (read-only).


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

This is only applicable when the autoPanMode 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 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 (i.e 1/8).


opacity : real

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

The default value is 1. The opacity can be set to any real value from 0-1.


pingAnimationSymbol : Symbol

The ping animation symbol to be used on the LocationDisplay.

The ping animation symbol displays an animation whenever a position update is received.


positionSource : PositionSource

The position source of the LocationDisplay.

The position source obtains and distributes the position updates. This is provided by Qt's PositionSource QML type, which obtains the device's current location. The LocationDisplay uses these updates to display the location on the MapView.

See also PositionSource QML Type.


showAccuracy : bool

Whether to show the accuracy symbol for display.

Returns true if the accuracy symbol is displayed. The default value is true.


showLocation : bool

Whether to show the location symbol for display.

Returns true if the location symbol is displayed. The default value is true.


showPingAnimationSymbol : bool

Whether to show the ping animation symbol for display.

Returns true if the ping animation symbol is displayed. The default value is true.


started : bool

Returns whether the LocationDisplay is active (read-only).

Returns true if the LocationDisplay is active


useCourseSymbolOnMovement : bool

Whether to show the course symbol on movement.

Returns true if the course symbol will display on movement.

See also courseSymbol.


wanderExtentFactor : real

The wander extent factor to be used on the LocationDisplay while in recenter mode

This is only applicable when the autoPanMode 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 may 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.


Signal Documentation

accuracySymbolChanged()

Emitted when the accuracySymbol property changes.


acquiringSymbolChanged()

Emitted when the acquiringSymbol property changes.


acquiringTimeoutMsChanged()

Emitted when the acquiringTimeoutMs property changes.


autoPanModeChanged()

Emitted when the autoPanMode property changes.


compassChanged()

Emitted when the compass property changes.


courseSymbolChanged()

Emitted when the courseSymbol property changes.


defaultSymbolChanged()

Emitted when the defaultSymbol property changes.


headingChanged()

Emitted when the heading property changes.


headingSymbolChanged()

Emitted when the headingSymbol property changes.


initialZoomScaleChanged()

Emitted when the initialZoomScale property changes.


locationChanged()

Emitted when the location and mapLocation properties changes.


Emitted when the navigationPointHeightFactor property changes.


opacityChanged()

Emitted when the opacity property changes.


pingAnimationSymbolChanged()

Emitted when the pingAnimationSymbol property changes.


positionSourceChanged()

Emitted when the positionSource property changes.


showAccuracyChanged()

Emitted when the showAccuracy property changes.


showLocationChanged()

Emitted when the showLocation property changes.


showPingAnimationSymbolChanged()

Emitted when the showPingAnimationSymbol property changes.


startedChanged()

Emitted when the started property changes.


useCourseSymbolOnMovementChanged()

Emitted when the useCourseSymbolOnMovement property changes.


wanderExtentFactorChanged()

Emitted when the wanderExtentFactor property changes.


Method Documentation

void start()

Starts the LocationDisplay on the MapView.

In order to start successfully, the LocationDisplay must have a valid position source. If you attempt to start position display on a 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 (PositionSource QML Type) as well.

See also PositionSource QML Type.


void stop()

Stops the LocationDisplay on the MapView.

Calling stop on the LocationDisplay will automatically attempt to stop its position source (PositionSource QML Type) as well. Location updates will no longer be received or displayed on the map.

See also PositionSource QML Type.



Feedback on this topic?