ArcGIS iPhone API - Displaying location on the map

Many iOS devices such as iPod Touch, iPad, and the iPhone provide information about the device's location. iOS includes a framework known as "CoreLocation" that abstracts how the location is retrieved, whether through Wi-Fi, cellular networks, or GPS. The framework also provides an API for developers to incorporate location capabilities in their applications and configure it based on their needs.

The map component in ArcGIS API for iOS shields developers from the complexity of the CoreLocation framework and provides an easy way to display and track the device's location on the map. The AGSGPS object associated with the map provides a simple façade over the CoreLocation framework and greatly simplifies working with location services.

Start displaying location

To start displaying the device's location on the map, you need to invoke the start method on the AGSGPS object available in the map's gps property.

[self.mapView.gps start];

By default, the map uses a blue, round symbol to display the device's location. The map will always try to get most accurate location available. Depending upon signal strength, satellite positions, and other factors, the location reported could be a best possible approximation. The map displays a blue-circle around the location symbol to indicate the range of accuracy.

Default symbol showing location

The map will automatically respond to location updates as promptly as possible, and appropriately udpate the position of the location symbol.

If you enable the autoPan property, the map will try to re-center itself on the device's location whenever the location symbol comes close to the edges of the map.

self.mapView.gps.autoPan = true;

If the user navigates the map while it's trying to re-center itself, autoPan will automatically be disabled so that the user does not have to "fight" with the map.

Stop displaying location

To stop displaying the device's location, you need to invoke the stop method.

[self.mapView.gps stop];

Customizing the location symbol

By default, the map uses a blue, round symbol to display the device's location. But you can change the symbol by using your own PNG images. The images must be named "GpsDisplay.png" and "GpsDisplayHeading.png" and they must be included in the application bundle. The images must 35x35 pixels for devices without retina display. It is recommended that you also include high resolution version of these images (70x70) pixels for devices with retina display and name them "GpsDisplay@2x.png" and "GpsDisplayHeading@2x.png"

Images for location symbol

Note:

Image names are case-sensitve.

If heading information is available from the location service, the map will use "GpsDisplayHeading.png" to display the location. The map will also automatically rotate the image by an amount specified by the heading to display the direction in which the device is travelling. To ensure the image points in the right direction when rotated, the symbol you use in "GpsDisplayHeading.png" should be pointing straight up by default.

Symbol showing location only

Symbol showing location and heading

Heading information is usually only available when the device is moving at some non-trivial velocity. If heading is not available, the map falls back to using "GPSDisplay.png". If this image is also not available, the map uses the default symbol.

Displaying location information in the callout

To display a callout when a user taps on the location symbol, you need to set one of your classes as the infoTemplateDelegate of the AGSGPS object. You do this by making the class adopt the AGSGPSInfoTemplateDelegate protocol.

@interface MyTemplate : NSObject <AGSGPSInfoTemplateDelegate> 
  ...
 @end

Your class must implement the methods defined in the protocol to specify what text needs to be displayed in the callout's Title and Detail sections.

@implementation MyTemplate 
  
  ...

  - (NSString*) titleForGPS: (AGSGPS*) gps screenPoint: (CGPoint) screen {
      NSLog(@"Location : %@", gps.currentPoint);
      return @"<title text>";
  }

  - (NSString*) detailForGPS:(AGSGPS*) gps screenPoint:(CGPoint) screen {
      NSLog(@"Location : %@", gps.currentPoint);
      return @"<detail text>";
  }
@end

Finally, an instance of your class must then be set as the infoTemplateDelegate on the AGSGPS instance. This will allow your class to be consulted before showing the callout.

MyTemplate* template = ... ;

self.mapView.gps.infoTemplateDelegate = template;

If you don't assign an infoTemplateDelegate, the map does not display the callout when the user taps on the GPS location symbol.

3/23/2011