Map Legend

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

Legend

Retrieving legend information

Starting with v1.8 of the 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 Server v10 Service Pack 1 or greater. This is because the REST API for services prior to v10 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, 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 would typically display a legend item for each feature type or feature template available in the layer. For a Graphics layer, you would 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 swatchForGraphic: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

Legend Sample