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:

Instance Methods
(void)	- startWithCompletion:

(void)	- stop

Properties
AGSSymbol *	accuracySymbol

AGSSymbol *	acquiringSymbol

AGSLocationDisplayAutoPanMode	autoPanMode

void(^	autoPanModeChangedHandler )(AGSLocationDisplayAutoPanMode autoPanMode)

AGSSymbol *	courseSymbol

AGSLocationDataSource *	dataSource

void(^	dataSourceStatusChangedHandler )(BOOL started)

AGSSymbol *	defaultSymbol

double	heading

AGSSymbol *	headingSymbol

double	initialZoomScale

AGSLocation *	location

void(^	locationChangedHandler )(AGSLocation *location)

AGSPoint *	mapLocation

float	navigationPointHeightFactor

float	opacity

AGSSymbol *	pingAnimationSymbol

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

completion block 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

Description

Instance Methods

Properties

Method Documentation

◆ startWithCompletion:

◆ stop

Property Documentation

◆ accuracySymbol

◆ acquiringSymbol

◆ autoPanMode

◆ autoPanModeChangedHandler

◆ courseSymbol

◆ dataSource

◆ dataSourceStatusChangedHandler

◆ defaultSymbol

◆ heading

◆ headingSymbol

◆ initialZoomScale

◆ location

◆ locationChangedHandler

◆ mapLocation

◆ navigationPointHeightFactor

◆ opacity

◆ pingAnimationSymbol

◆ showAccuracy

◆ showLocation

◆ showPingAnimationSymbol

◆ started

◆ useCourseSymbolOnMovement

◆ wanderExtentFactor