ArcGIS Runtime SDK for iOS: AGSLocationDisplay Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSLocationDisplay Class Reference

Description

Displays device location on a map.

Instances of this class manage the "display" of device location on a map - for instance, the symbols used, animation, auto pan behavior, etc. Each AGSMapView has its own instance of a location display.

The location display does not itself retrieve any location information. Rather, that is the job of its dataSource which provides location updates on a frequent basis. The default dataSource, AGSCLLocationDataSource, uses the underlying platform's location manager (CLLocationManager).

Note
The default location datasource, AGSCLLocationDataSource, needs the app to be authorized in order to access the device's location. The app's Info.plist must contain appropriate purpose strings (NSLocationWhenInUseUsageDescription, NSLocationAlwaysUsageDescription, or NSLocationAlwaysAndWhenInUseUsageDescription keys) to permit this functionality. When the datasource is started it will attempt to request when-in-use authorization if the app's authorization status is not determined, otherwise it will reuse the authorization that has already been granted. If authorization is denied, location updates will not be available.

To start displaying location, you need to call startWithCompletion: (AGSLocationDisplay). To stop displaying location, you need to call stop (AGSLocationDisplay).

By default, a round, blue symbol is used to display the device's location. The default dataSource will try 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. As the device moves and new location updates are provided by the dataSource, the location symbol will be repositioned on the map.

Since
100
Inheritance diagram for AGSLocationDisplay:
AGSObject

Instance Methods

(void) - startWithCompletion:
 
(void) - stop
 

Properties

AGSSymbolaccuracySymbol
 
AGSSymbolacquiringSymbol
 
AGSLocationDisplayAutoPanMode autoPanMode
 
void(^ autoPanModeChangedHandler )(AGSLocationDisplayAutoPanMode autoPanMode)
 
AGSSymbolcourseSymbol
 
AGSLocationDataSourcedataSource
 
void(^ dataSourceStatusChangedHandler )(BOOL started)
 
AGSSymboldefaultSymbol
 
double heading
 
AGSSymbolheadingSymbol
 
double initialZoomScale
 
AGSLocationlocation
 
void(^ locationChangedHandler )(AGSLocation *location)
 
AGSPointmapLocation
 
float navigationPointHeightFactor
 
float opacity
 
AGSSymbolpingAnimationSymbol
 
BOOL showAccuracy
 
BOOL showLocation
 
BOOL showPingAnimationSymbol
 
BOOL started
 
BOOL useCourseSymbolOnMovement
 
float wanderExtentFactor
 

Method Documentation

◆ startWithCompletion:

- (void) startWithCompletion: (nullable void(^)(NSError *__nullable error))  completion

Start the location display, which will in-turn start its dataSource to start receiving location updates. As the updates are received they will be displayed on the map.

Parameters
completionblock which will be invoked when the operation completes. If the dataSource failed to start, the error property will be populated.
Since
100

◆ stop

- (void) stop

Stop the location display, which will in-turn stop its dataSource property. Location updates will no longer be received or displayed on the map.

Since
100

Property Documentation

◆ accuracySymbol

- (AGSSymbol*) accuracySymbol
readwritenonatomicstrong

The symbol that is used to show the accuracy circle around the location display, provided the showAccuracy property is YES. Use a symbol that can fill a polygon geometry.

Since
100

◆ acquiringSymbol

- (AGSSymbol*) acquiringSymbol
readwritenonatomicstrong

The symbol that is used for location updates that are not current but instead based on a last known position (for example, in the case of deferred location updates). Use a symbol that can symbolize a point geometry.

See also
AGSLocation::lastKnown
Since
100

◆ autoPanMode

- (AGSLocationDisplayAutoPanMode) autoPanMode
readwritenonatomicassign

Defines how to automatically pan the map when new location updates are received. Default is AGSLocationDisplayAutoPanModeOff.

Since
100

◆ autoPanModeChangedHandler

- (void(^ autoPanModeChangedHandler) (AGSLocationDisplayAutoPanMode autoPanMode))
readwritenonatomiccopy

Block that is invoked whenever the location display's autoPanMode changes.

Note
The block will be invoked on the same thread on which the event occurred, which could be any arbitrary thread. You need to dispatch any UI related work to the main thread.
Since
100

◆ courseSymbol

- (AGSSymbol*) courseSymbol
readwritenonatomicstrong

The symbol that is used when the location update has both a velocity and course, provided the useCourseSymbolOnMovement property is YES. Use a symbol that can symbolize a point geometry.

Since
100

◆ dataSource

- (AGSLocationDataSource*) dataSource
readwritenonatomicstrong

The source for location updates. Defaults to AGSCLLocationDataSource. You can create your own datasource, or choose from one of the datasources provided.

Since
100

◆ dataSourceStatusChangedHandler

- (void(^ dataSourceStatusChangedHandler) (BOOL started))
readwritenonatomiccopy

Block that is invoked whenever the dataSource status changes.

Note
The block will be invoked on the same thread on which the event occurred, which could be any arbitrary thread. You need to dispatch any UI related work to the main thread.
Since
100

◆ defaultSymbol

- (AGSSymbol*) defaultSymbol
readwritenonatomicstrong

The symbol that is used when the location update doesn't have velocity or a course. Use a symbol that can symbolize a point geometry.

See also
acquiringSymbol for location updates that are not current but instead based on a last known position
Since
100

◆ heading

- (double) heading
readnonatomicassign

Heading relative to the geographic North Pole. The value 0 means the device is pointed toward true 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.

Since
100

◆ headingSymbol

- (AGSSymbol*) headingSymbol
readwritenonatomicstrong

The symbol that is used when the location display autoPanMode property is AGSLocationDisplayAutoPanModeCompassNavigation. Use a symbol that can symbolize a point geometry.

Since
100

◆ initialZoomScale

- (double) initialZoomScale
readwritenonatomicassign

Scale that map should automatically be zoomed to upon receiving the first location update. Only applies to the first location update received after the autoPanMode goes from AGSLocationDisplayAutoPanModeOff to any other value. Defaults to 10,000. A value of 0 or less will tell the location display not to auto zoom at all.

Since
100

◆ location

- (AGSLocation*) location
readnonatomicstrong

Most recent location update provided by the dataSource property. It includes the raw information about the location and may not be in the map's spatial reference.

See also
mapLocation
Since
100

◆ locationChangedHandler

- (void(^ locationChangedHandler) (AGSLocation *location))
readwritenonatomiccopy

Block that is invoked whenever the location display receives a new location update from its dataSource property.

Note
The block will be invoked on the same thread on which the event occured, which could be any arbitrary thread. You need to dispatch any UI related work to the main thread.
Since
100

◆ mapLocation

- (AGSPoint*) mapLocation
readnonatomiccopy

Position of the location symbol, as provided by the most recent location update, projected to the map's spatial reference.

Since
100

◆ navigationPointHeightFactor

- (float) navigationPointHeightFactor
readwritenonatomicassign

Determines where to position the location symbol when autoPanMode is AGSLocationDisplayAutoPanModeNavigation. The default is 0.125 (1/8th), which places it 1/8th of the height of the map view starting from the bottom of the map view.

Since
100

◆ opacity

- (float) opacity
readwritenonatomicassign

The opacity of content (all symbols) displayed by the location display. Default is 1.

Since
100

◆ pingAnimationSymbol

- (AGSSymbol*) pingAnimationSymbol
readwritenonatomicstrong

The symbol that is animated to depict a ping around the location symbol to suggest that a location upate was received, provided showPingAnimationSymbol is true. Use a symbol that can symbolize a point geometry.

Since
100

◆ showAccuracy

- (BOOL) showAccuracy
readwritenonatomicassign

Indicates whether the accuracy circle around the location symbol should be displayed. Default is YES.

Since
100

◆ showLocation

- (BOOL) showLocation
readwritenonatomicassign

Indicates whether the location symbol should be displayed. Default is YES.

Since
100

◆ showPingAnimationSymbol

- (BOOL) showPingAnimationSymbol
readwritenonatomicassign

Indicates whether the ping symbol animating around the location symbol should be displayed. Default is YES.

Since
100

◆ started

- (BOOL) started
readnonatomicassign

Indicates whether the location display is active or not.

Since
100

◆ useCourseSymbolOnMovement

- (BOOL) useCourseSymbolOnMovement
readwritenonatomicassign

Indicates whether the courseSymbol property should be used instead of the defaultSymbol property when location updates suggest the device is moving.

Since
100

◆ wanderExtentFactor

- (float) wanderExtentFactor
readwritenonatomicassign

The factor that is used to calculate a wander extent for the location symbol. The location symbol may move freely within the wander extent, but as soon as the symbol exits the wander extent, the mapview re-centers the map on the symbol. The default value for this property is 0.5, which means that the wander extent is half the size of the mapview. Permissible values are between 0 and 1. A value of 0 implies an infinitesimal wander extent, and the map is potentially re-centered on every location update (heavy CPU & battery consumption). A value of 1 implies a wander extent equal to the size of the mapview's extent, so the location symbol may move up to the edge of the mapview before the map re-centers (light CPU & battery consumption).

Since
100