Controls displaying position information and updates on a MapView. More...
| Import Statement: | import Esri.ArcGISRuntime 100.15 |
| Since: | Esri.ArcGISRuntime 100.0 |
| Inherits: |
Properties
- accuracySymbol : Symbol
- acquiringSymbol : Symbol
- acquiringTimeoutMs : int
- autoPanMode : Enums.LocationDisplayAutoPanMode
- courseSymbol : Symbol
- dataSource : AbstractLocationDataSource
- defaultSymbol : Symbol
- heading : double
- headingSymbol : Symbol
- initialZoomScale : double
- location : Location
- mapLocation : Point
- navigationPointHeightFactor : real
- opacity : real
- pingAnimationSymbol : Symbol
- showAccuracy : bool
- showLocation : bool
- showPingAnimationSymbol : bool
- started : bool
- useCourseSymbolOnMovement : bool
- wanderExtentFactor : real
Signals
- accuracySymbolChanged()
- acquiringSymbolChanged()
- acquiringTimeoutMsChanged()
- autoPanModeChanged()
- compassChanged()
- courseSymbolChanged()
- dataSourceChanged()
- defaultSymbolChanged()
- headingChanged()
- headingSymbolChanged()
- initialZoomScaleChanged()
- locationChanged()
- navigationPointHeightFactorChanged()
- opacityChanged()
- pingAnimationSymbolChanged()
- positionSourceChanged()
- showAccuracyChanged()
- showLocationChanged()
- showPingAnimationSymbolChanged()
- startedChanged()
- useCourseSymbolOnMovementChanged()
- wanderExtentFactorChanged()
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.
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).
Returns how the location changes affect the current map view extent.
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.
Any default zooming behavior (besides scrolling) or any operation that modifies the GeoView viewpoint will automatically set autoPanMode to false.
See also Enums.LocationDisplayAutoPanMode.
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.
dataSource : AbstractLocationDataSource |
The data source of the LocationDisplay.
The data source provides the location data updates that are displayed on the MapView.
This property was introduced in Esri.ArcGISRuntime 100.8.
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.
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.
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).
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.
Whether to show the accuracy symbol for display.
Returns true if the accuracy symbol is displayed. The default value is true.
Whether to show the location symbol for display.
Returns true if the location symbol is displayed. The default value is true.
Whether to show the ping animation symbol for display.
Returns true if the ping animation symbol is displayed. The default value is true.
Returns whether the LocationDisplay is active (read-only).
Returns true if the LocationDisplay is active
Whether to show the course symbol on movement.
Returns true if the course symbol will display on movement.
See also courseSymbol.
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
Emitted when the accuracySymbol property changes.
Note: The corresponding handler is onAccuracySymbolChanged.
Emitted when the acquiringSymbol property changes.
Note: The corresponding handler is onAcquiringSymbolChanged.
Emitted when the acquiringTimeoutMs property changes.
Note: The corresponding handler is onAcquiringTimeoutMsChanged.
Emitted when the autoPanMode property changes.
Note: The corresponding handler is onAutoPanModeChanged.
Emitted when the compass property changes.
Note: The corresponding handler is onCompassChanged.
Emitted when the courseSymbol property changes.
Note: The corresponding handler is onCourseSymbolChanged.
Emitted when the dataSource property changes.
Note: The corresponding handler is onDataSourceChanged.
This signal was introduced in Esri.ArcGISRuntime 100.8.
Emitted when the defaultSymbol property changes.
Note: The corresponding handler is onDefaultSymbolChanged.
Emitted when the heading property changes.
Note: The corresponding handler is onHeadingChanged.
Emitted when the headingSymbol property changes.
Note: The corresponding handler is onHeadingSymbolChanged.
Emitted when the initialZoomScale property changes.
Note: The corresponding handler is onInitialZoomScaleChanged.
Emitted when the location and mapLocation properties changes.
Note: The corresponding handler is onLocationChanged.
Emitted when the navigationPointHeightFactor property changes.
Note: The corresponding handler is onNavigationPointHeightFactorChanged.
Emitted when the opacity property changes.
Note: The corresponding handler is onOpacityChanged.
Emitted when the pingAnimationSymbol property changes.
Note: The corresponding handler is onPingAnimationSymbolChanged.
Emitted when the positionSource property changes.
Note: The corresponding handler is onPositionSourceChanged.
Emitted when the showAccuracy property changes.
Note: The corresponding handler is onShowAccuracyChanged.
Emitted when the showLocation property changes.
Note: The corresponding handler is onShowLocationChanged.
Emitted when the showPingAnimationSymbol property changes.
Note: The corresponding handler is onShowPingAnimationSymbolChanged.
Emitted when the started property changes.
Note: The corresponding handler is onStartedChanged.
Emitted when the useCourseSymbolOnMovement property changes.
Note: The corresponding handler is onUseCourseSymbolOnMovementChanged.
Emitted when the wanderExtentFactor property changes.
Note: The corresponding handler is onWanderExtentFactorChanged.
Method Documentation
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.
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.