Skip To Content

Map legend

In this topic

A legend conveys the meaning of symbols used on the map. It associates a symbol with the real world entity that it represents. Typically, each item in the legend consists of a symbol with a label containing explanatory text.


Retrieving legend information

Starting with version 1.8 of the ArcGIS Runtime SDK for iOS API, you can retrieve legend information for the following layer types:

  • ArcGIS Dynamic Map Service layer
  • ArcGIS Tiled Map Service layer
  • ArcGIS Feature layer
  • ArcGIS Graphics layer

ArcGIS Dynamic and Tiled Map Service layers

Legend information for ArcGIS Dynamic and Tiled Map Service layers is only available if the layers are using a service from ArcGIS 10 for Server SP1 or later. This is because the REST API for services prior to version 10 SP1 did not provide legend information.

You can retrieve legend images and labels by invoking the retrieveLegendInfo method on the layer's AGSMapServiceInfo object. AGSMapServiceInfo's delegate is informed when the legend information is retrieved successfully or if an error is encountered. When successful, the legendImages and legendLabels properties of individual AGSMapServiceLayerInfo objects are populated.

@interface LegendFetcher : NSObject <AGSMapServiceInfoDelegate> {
   -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operation:(NSOperation *)op didFailToRetrieveLegendInfoWithError:(NSError *)error ;
   -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operationDidRetrieveLegendInfo:(NSOperation *)op ;

@implementation LegendFetcher {

 -(void) retrieveLegend {   
   AGSMapServiceInfo* msi = ...;
   //set the delegate
   msi.delegate = self;
   //retrieve legend 
   [msi retrieveLegendInfo];
 //delegate method called when error is encountered
 -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operation:(NSOperation *)op didFailToRetrieveLegendInfoWithError:(NSError *)error { 
   NSLog(@"Error : %@",error);

 //delegate method called when legend is retrieved successfully
 -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operationDidRetrieveLegendInfo:(NSOperation *)op { 
   //loop through all sub-layers
   NSArray* layerInfos = mapServiceInfo.layerInfos;
   for(int i=0;i<[layerInfos count];i++){
     //access legend information of each sub-layer
     AGSMapServiceLayerInfo* layerInfo = [layerInfos objectAtIndex:i];
     NSArray* legendLabels = layerInfo.legendLabels;
     NSArray* legendImages = layerInfo.legendImages;

ArcGIS Feature and Graphics layers

For an ArcGIS Feature layer, you typically display a legend item for each feature type or feature template available in the layer. For a Graphics layer, you display a legend item for each type of symbol used by the layer. Renderers are usually a good starting point for determining how many legend items should be displayed, because a renderer associates different symbols with graphics based on logical groupings.

To create legend items for ArcGIS Feature and Graphics layers, you need to retrieve images of symbols used in the layers. Both AGSRenderer and AGSSymbol provide convenience methods that return images for symbols.

AGSRenderer* renderer = ...;
AGSGraphic* graphic = ...;

//Getting legend image from a renderer
UIImage* image = [renderer swatchForFeature:graphic size:CGSizeMake(20,30)]; 

//Getting legend image from a symbol
AGSSymbol* symbol = ...;
UIImage* image = [symbol swatchForGeometryType:AGSGeometryTypePoint size:CGSizeMake(20,30)];

Once you have the images, you need to associate them with appropriate labels in the legend.

Displaying the legend

Once you have the image and label information for each legend item, you can display the legend using a UITableView or a custom view.

See also