Skip To Content

Show your location

In this topic

This topic shows you how to add and track the location of your computer on a map.

This API provides an AGSLocationDisplay object that, once associated with the map, provides an easy way to display and track the computer's location. If a developer uses this high-level object, they do not have to work directly with location services nor with Apple's CoreLocation framework.

Start displaying location

To start displaying the computer's location on the map, invoke the startDataSource method on the AGSLocationDisplay object. Invoke this method only after the map has finished loading, for example, in the mapViewDidLoad: delegate method of the AGSMapViewLayerDelegate protocol.

func mapViewDidLoad(mapView: AGSMapView!) {
	self.mapView.locationDisplay.startDataSource()
}

By default, the map uses a blue, round symbol to display the computer's location. The map always tries to get the most accurate location available. The map displays a blue circle around the location symbol to indicate the range of accuracy.

Default Location symbol
Default symbol showing location

As the computer moves, the map responds and automatically updates the position of the location symbol.

Location data sources

In the API, the AGSLocationDisplay class manages the display of location information on the map. Since it does not actually retrieve the location information, it relies on a location data source to provide updates on a frequent basis. You can use any of the provided data sources, or you can plug in your custom data sources to feed location updates to the map. By default, AGSLocationDisplay uses AGSCLLocationManagerLocationDisplayDataSource if nothing is provided.

AGSCLLocationManagerLocationDisplayDataSource

This data source uses the CoreLocation framework written by Apple to retrieve location updates through GPS or Wi-Fi.

AGSSimulatedLocationDisplayDataSource

This data source allows you to simulate location updates based on any polyline geometry. Each vertex in the polyline is used to fire a location update.

//The polyline geometry along which location updates should be simulated
let route:AGSPolyline = ...
        
//Create the data source. Assign the geometry.
let simulatedDS = AGSSimulatedLocationDisplayDataSource()
simulatedDS.setLocationsFromPolyline(route)
        
//Set data source
self.mapView.locationDisplay.dataSource = simulatedDS

AGSGPXLocationDisplayDataSource

This data source uses the first track or route in a GPX file to simulate location updates.

//Create the data source using a GPX file on the web
let url = NSURL(string: "http://www.topografix.com/fells_loop.gpx")
let gpxDS = AGSGPXLocationDisplayDataSource(URL: url)
        
//Or, create the data source using a GPX file on the device
let pathToGPXOnDevice:String = ...
let gpxDS = AGSGPXLocationDisplayDataSource(path: pathToGPXOnDevice)
        
//Set data source
self.mapView.locationDisplay.dataSource = gpxDS

Autopan modes

The map provides several presets that define how the map behaves when location updates are received.

Off

In this mode, the map only updates the position of the location symbol on the map. It does not center it again. However, it is possible that the location symbol may move off-screen in response to location updates.

Default

In this mode, the map attempts to keep the location symbol on-screen by centering again on the location symbol when the symbol moves outside a "wander extent." The location symbol may move freely within the wander extent, but as soon as the symbol exits the wander extent, the map centers again on the symbol.

By default, the wander extent is half the size of the map's viewable extent, but you can customize the wander extent by modifying wanderExtentFactor on AGSLocationDisplay. A value of 1 implies a wander extent equal to the size of the map's viewable extent, and the location symbol may move right up to the edge of the map before the map centers again. A value of 0 implies an infinitesimal wander extent and the map centers again on every location update.

self.mapView.locationDisplay.autoPanMode = .Default
self.mapView.locationDisplay.wanderExtentFactor = 0.75

If a user pans the map in this mode, the mode automatically changes its autopan mode to OFF to prevent the user from having to "fight" with the map that may otherwise try to center again based on future location updates.

Navigation

This mode is best suited for in-vehicle navigation. In this mode, the location symbol is pinned to a point on the screen, and it always points towards the top edge of the computer. The map pans and rotates based on location updates, and the direction the computer travels. The location symbol appears stationary, while the map underneath it appears to be moving and rotating.

The position of the location symbol can be adjusted by modifying the navigatonPointHeightFactor property on AGSLocationDisplay. A value of 0 implies the location symbol should be positioned at the bottom edge of the map, and 1 implies the top edge. A value between 0 and 1 positions the symbol somewhere along the centerline from the bottom edge to the top edge.

self.mapView.locationDisplay.autoPanMode = .Navigation
self.mapView.locationDisplay.wanderExtentFactor = 0.25

If a user pans the map in this mode, the mode automatically changes to OFF.

Compass navigation

This mode is better suited when the user is walking. Just as in Navigation mode, the location symbol is pinned to a point on the screen, and always points towards the top edge of the computer. However, the map rotates based on the user's bearing relative to the magnetic north, and not based on the direction the computer is travelling in (as is the case in Navigation mode). The map reflects what lies ahead of the user as the user pivots around their location.

The position of the location symbol can be adjusted by modifying navigatonPointHeightFactor. A value of 0 implies the location symbol should be positioned at the bottom edge of the map, and 1 implies the top edge. A value between 0 and 1 positions the symbol somewhere between the bottom and top edges.

self.mapView.locationDisplay.autoPanMode = .CompassNavigation
self.mapView.locationDisplay.wanderExtentFactor = 0.5

If a user pans the map in this mode, the mode automatically changes to OFF.

Stop displaying location

To stop displaying the computer's location, invoke the stopDataSourcemethod.

self.mapView.locationDisplay.stopDataSource()

Customize the location symbol

The SDK provides three images, in the ArcGIS.Bundle that are used for the location symbol by default. These image files are named as follows:

  • LocationDisplay.png—Symbol showing location only.
  • LocationDisplayCourse.png—Symbol showing location and course (direction of travel).
  • LocationDisplayHeading.png—Symbol showing location and heading (compass bearing).
Without heading
LocationDisplay.png
With heading
LocationDisplayCourse.png
With bearing
LocationDisplayHeading.png

Depending on the AutoPanMode in use, and the type of information provided by the location updates, one of the default images will be used for the location symbol.

In Off, Default, and Navigation modes, the LocationDisplay.png image will be used when only location information is available, and LocationDisplayCourse.png will be used if both location and course (direction of travel) information are available. In Off and Default modes, the LocationDisplayCourse.png image will be appropriately rotated by an amount specified by the course to display the direction in which the computer travels, but in Navigation mode, the map will be rotated instead.

Note:

Course information is only available when the computer is moving at some non-trivial velocity. This is why the map typically only displays the LocationDisplayCourse.png symbol when the computer travels in a vehicle.

In Compass Navigation mode, the LocationDisplayHeading.png image is used to display the computer's location and bearing.

You can change the location symbol by providing your PNG images. Your images must have the same name as the default images, and be part of your Xcode project. The images in your Xcode project have precedence over the default ones provided in ArcGIS.bundle. Where possible, include high resolution versions of your images for computers with retina display. Name the high resolution versions LocationDisplay@2x.png, LocationDisplayCourse@2x.png, and LocationDisplayHeading@2x.png.

Location symbol images
Images for location symbol
Note:

Image names are case-sensitve.

Displaying location information in the callout

You can use the AGSCallout object to display the location information on the map. To display a callout, you need to set one of your classes as the callout's deletage. You do this by making your class (typically a view controller) adopt the <AGSCalloutDelegate> protocol.

class ViewController: UIViewController, AGSCalloutDelegate {
...
}

Next you must set the callout's delegate.

self.mapView.callout.delegate = self
Finally, you implement the callout:willshowForLocationDisplay: method defined in the protocol. In the example below, we set the callout's title and details.
func callout(callout: AGSCallout!, willShowForLocationDisplay locationDisplay: AGSLocationDisplay!) -> Bool {
 
 callout.title = "<title text>"
 callout.detail = "<detail text>"

 return true
}
The method implementation returns true at the end. This instructs the map to display the callout. If you want to temporarily disable the callout you can set the allowCallout property on the AGSMapView to false.

Access location information

AGSLocationDisplay provides the computer's location in two ways.

The location property contains the information provided by the underlying data source. The location coordinates will be in a spatial reference chosen by the data source. For example, if the data source is of type AGSCLLocationManagerLocationDisplayDatasource, the coordinates will be in WGS84.

The mapLocation method provides the same location information; however, the coordinates are projected into the map's spatial reference.

Listen for location updates

The location property on AGSLocationDisplay is KVO (Key-Value Observing) compliant. You can attach an observer to this property to be notified of location updates.

func registerAsObserver() {
	self.mapView.locationDisplay.addObserver(self, forKeyPath: "location", options: .New, context: nil)
}
    
override func observeValueForKeyPath(keyPath: String!, ofObject object: AnyObject!, change: [NSObject : AnyObject]!, context: UnsafeMutablePointer<()>) {
	if keyPath == "location" {
  println("Location updated to \(self.mapView.locationDisplay.mapLocation())")
	}
}

For more information on KVO, refer to Apple's Key-Value Observing Programming Guide.