ArcObjects Library Reference (Carto)

IMapServerLayout.ExportLegend Method

Exports a legend to an image file. The client can create the legend object and set its desired properties appropriately. If legend is Nothing/Null, a default legend will be generated.

[Visual Basic .NET]
Public Function ExportLegend ( _
    ByVal Legend As ILegend, _
    ByVal mapDesc As IMapDescription, _
    ByVal pMapDisplay As IImageDisplay, _
    ByVal BackgroundColor As IColor, _
    ByVal imageDesc As IImageDescription _
) As IImageResult

[C#]
public IImageResult ExportLegend (
    ILegend Legend,
    IMapDescription mapDesc,
    IImageDisplay pMapDisplay,
    IColor BackgroundColor,
    IImageDescription imageDesc
);

[C++]
HRESULT ExportLegend(
  ILegend* Legend,
  IMapDescription* mapDesc,
  IImageDisplay* pMapDisplay,
  IColor* BackgroundColor,
  IImageDescription* imageDesc,
  IImageResult** ImageResult
);

[C++]

Parameters
Legend [in]

  Legend is a parameter of type ILegend
mapDesc [in]

  mapDesc is a parameter of type IMapDescription
pMapDisplay [in]

  pMapDisplay is a parameter of type IImageDisplay
BackgroundColor [in]

  BackgroundColor is a parameter of type IColor
imageDesc [in]

  imageDesc is a parameter of type IImageDescription
ImageResult [out, retval]

  ImageResult is a parameter of type IImageResult

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Remarks

Use ExportLegend to export a single image representing the map's legend. Use the input parameter ILegend to access the Legend object in order to customize the legend. If the MapDescription parameter is Nothing/Null the default map description is used. Use TransparentColor in IImageDisplay2 if you want the background to be transparent. Size, resolution and file format are determined by the ImageDescription object, which includes ImageDisplay and ImageType. ExportLegend results in an ImageResult object.

An ExportLegend result displays all visible layers in the map (default).

The default size of a legend is based on the number of layers, symbol size and length of label or description text. This size is likely to vary from map to map.

To best manage the size of the ExportLegend request keep either the width or the height set in ImageDisplay constant. This ImageDisplay object is part of the imageDesc parameter. Don't confuse this ImageDisplay object with the one that refers to the map (MapDisplay).

In order to ensure a constant size do not specify a height and width, or set a value of 0 for each, for the ImageDisplay. However, you can enter your own height or width values. For example, set the ImageDisplay width at 150 and set the height at 0. A setting of 0 will calculate a default value for best fit. The actual height value will adjust as the legend changes to accommodate changes in layer visibility. Depending on the symbols and text you have in youir legend, symbol and text size may not be constant as the number of legend items changes such as when you turn on or off map layers. Make sure to provide an adequate size to the legend to accomodate this. Otherwise, parts of the legend may be cut off or the legend may be illegible. You may need to experiment to find an adequate size. Remember, setting 0 for both the height and width will provide the most consistent and accurate results.

To achieve more control over the legend of a MapServer map use the ILegend input parameter or use GetLegendInfo on IMapServer.

[C#]

The following sample code shows how to customize the legend by using the ILegend input parameter: all the raster layers in the legend are removed. The sample also shows the difference between the input parameters IMapDisplay and IImageDescription . The sample assumes that you already have a valid MapServer and MapDescription object, and that you are not working with a server context. However, if you are developing an ArcGIS for Server application using a server context, you should not use New to create local ArcObjects, but you should always create objects within the server by calling CreateObject on IServerContext.

IMapServer mapServer;
IMapDescription mapDesc;

// Get legend from map
IMapServerObjects mapServerObjects;
mapServerObjects=(IMapServerObjects)mapServer; // QI
IMap map;
map=mapServerObjects.get_Map(mapServer.DefaultMapName);
UID uid=new UIDClass();
uid.Value="esriCarto.Legend";
ILegend legend;
legend =(ILegend) map.CreateMapSurround(uid, null );

// Remove all raster layers in legend
int i, itemCount;
ILegendItem legendItem;
ILayer layer;
itemCount=legend.ItemCount;
// Step through legend items bottom to top (this is necessary to keep
// item numbers in sync after having deleted a raster layer)
for (i=0; i < itemCount; i++)
{
        legendItem=legend.get_Item(itemCount - 1 - i);
        layer=legendItem.Layer;
        if (layer is IRasterLayer)
        {
                legend.RemoveItem(itemCount - 1 - i);
        }
}

// Set image description and map display (Make sure not to confuse input
// parameters pMapDisplay and pImageDesc!):

// Step 1: Set image description (used for the legend image to be generated)
// Image type
IImageType imageType=new ImageTypeClass ();
imageType.Format=esriImageFormat.esriImageJPG;
imageType.ReturnType=esriImageReturnType.esriImageReturnMimeData;
// Image Display
IImageDisplay imageDisp=new ImageDisplayClass();
imageDisp.Height=0;
imageDisp.Width=150;
imageDisp.DeviceResolution=96;
// Image Description
IImageDescription imageDesc=new ImageDescriptionClass();
imageDesc.Type=imageType;
imageDesc.Display=imageDisp;

// Step 2: Set map display (used to calculate scale dependet layer visibility in 
// the legend
IImageDisplay mapDisplay=new ImageDisplayClass();
mapDisplay.Height=500;
mapDisplay.Width=500;
mapDisplay.DeviceResolution=96;

// Export legend
IMapServerLayout mapServerLayout;
mapServerLayout=(IMapServerLayout)mapServer;
IImageResult imageResult;
imageResult=mapServerLayout.ExportLegend(legend, mapDesc, mapDisplay, null, imageDesc);

IMapServerLayout.ExportLegend Method

Product Availability

Remarks

See Also