ArcGIS iPhone API - Displaying a Callout

It is sometimes necessary to show more information about features being displayed on a map. For instance, a user may want to see the business hours of a restaurant, or the price of a house on sale. This information can be displayed very effectively using a Callout.

The callout is anchored to a geographic location on the map. As the user navigates the map, the callout remains anchored to the same geographic location. The callout can display text in two sections -- title and detail. The callout also has an accessory button. This accessory button can be used to bring up another view to show more information about the feature.

The callout is an instance of AGSCallout. The map's callout be accessed through the callout property on AGSMapView.

Customizing the appearance

You can change some visual properties of the callout such as its background color, width, text color, visibility of the accessory button etc. These elements are exposed as properties on the AGSCallout object.

//don't show the accessory button
mapView.callout.accessoryButtonHidden = YES;

Displaying information

Information can be displayed in the callout in two ways -

Through the title and detail properties on AGSCallout
Through a delegate (infoTemplateDelegate)

Directly assigning values to the title and detail properties on AGSCallout is required when you display the callout programatically using showCalloutAtPoint: method on AGSMapView. This method allows you to show the callout at any geographic location on the map.

mapView.callout.title = @"<title>";
mapView.callout.detail = @"<detail>";
AGSPoint* point = ...;
[mapView showCalloutAtPoint: point];

However, in most situations, it will be more convenient to display information using an infoTemplateDelegate. The delegate needs to implement a well known protocol in order to provide the title and detail information to be displayed. When the delegate is present, the map will automatically show the callout in response to some user interaction. For instance, when the user taps on the GPS location symbol, or when the user taps on a graphic in a graphics layer. For information on how to use an infoTemplateDelegate with graphics, refer to Displaying attribute information in the callout. For information on how to use an infoTemplateDelegate with the GPS location, refer to Displaying location information in the callout

You can also display the callout programatically for a graphic by using the showCalloutAtPoint:forGraphic:animated: method on AGSMapView. If the graphic has an infoTemplateDelegate, it will be used to display information in the callout. Otherwise, you will need to specify the information using the title and detail properties on AGSCallout as shown above.

Regardless of how the callout is displayed -- programatically or automatically in response to user interaction -- the map's mapViewDelegate is always consulted to check whether the callout should be shown for a graphic or the GPS location symbol. Thus, you can control when the callout is displayed by designating one of your classes as the map's mapViewDelegate. When the callout is eventually displayed, the same mapViewDelegate is informed so that it can perform some additional operations.

@interface MyDelegate : NSObject <AGSMapViewDelegate> 
  ...
  - (BOOL) mapView: (AGSMapView *) mapView shouldShowCalloutForGraphic: (AGSGraphic *) graphic ;
  - (void) mapView: (AGSMapView *) mapView didShowCalloutForGraphic: (AGSGraphic *) graphic ;

@end

@implementation MyDelegate

- (BOOL) mapView: (AGSMapView *) mapView shouldShowCalloutForGraphic: (AGSGraphic *) graphic {
  //invoked when a user taps on a graphic
  //decide if a callout should be shown for the graphic
}

- (void) mapView: (AGSMapView *) mapView didShowCalloutForGraphic: (AGSGraphic *) graphic {
  //perform some additional operations after callout is displayed
}

Responding to the accessory button

When a user taps on the accessory button in the callout, the map's calloutDelegate is notified. Depending upon whether the callout was displayed for an arbitrary point, a graphic, or the GPS location symbol, one of three delegate methods will be invoked -

- (void) mapView: (AGSMapView *) mapView didClickCalloutAccessoryButtonAtPoint:	(AGSPoint *) point 

- (void) mapView: (AGSMapView *) mapView didClickCalloutAccessoryButtonForGraphic: (AGSGraphic *) graphic

- (void) mapView: (AGSMapView *) mapView didClickCalloutAccessoryButtonForGPS: (AGSGPS *) gps

You can implement the relevant methods in your delegate to be informed when the accessory button is tapped. You can then display a secondary view to show more information, or perform some additional operations.

Hiding the callout

To hide the callout, you simply need to enable its hidden property.

mapView.callout.hidden = YES;

3/23/2011