How to interact with map surrounds

Interacting with map surrounds

Map surrounds are specific types of elements that are associated with a map object. A good example of a map surround and its capabilities is the north arrow. North arrows are built as map surrounds so that they can respond to map rotation. When a map is rotated, its north arrow is rotated the same degree.
This example code adds a legend to the page layout. North arrows and legends are types of map surrounds. All map surrounds are held inside a MapSurroundFrame container, an element object, and this frame is related to a MapFrame. This relationship enables, for example, north arrows to automatically rotate when their related map is rotated and it tells the legends the layers and symbology a map has. The second function shows how to access the map surrounds through the MapSurroundFrame.
The following code demonstrates how to add a MapSurroundFrame to a given map and page layout:
static void addMapSurround(IPageLayout docPageLayout, IMap docMap, IActiveView
    docActiveView)throws Exception{
    IGraphicsContainer docGraphicsContainer = (IGraphicsContainer)docPageLayout;
    IMapFrame docMapFrame = (IMapFrame)docGraphicsContainer.findFrame(docMap);
    UID elementUID = new UID();
    // The value determines the type of MapSurroundFrame being added.
    // The createsurroundframe method takes the UID of the element and an
    // optional style.
    IMapSurroundFrame docMapSurroundFrame = docMapFrame.createSurroundFrame
        (elementUID, null);
    // Now cast the MapSurroundFrame as an element so it can be inserted
    // into the page layout.
    IElement docElement = (IElement)docMapSurroundFrame;
    IElement mainMapElement = (IElement)docMapFrame;
    IEnvelope mainEnv = mainMapElement.getGeometry().getEnvelope();
    IEnvelope env = new Envelope();
    env.putCoords(mainEnv.getXMax() + 1.5, mainEnv.getYMin() + 1.5, mainEnv.getXMax()
        - 1.5, mainEnv.getYMax() - 1.5);
    docGraphicsContainer.addElement(docElement, 0);
    docActiveView.partialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);

The following code example shows how to find and access the MapSurroundFrame:
static void reportMapSurrounds(IPageLayout docPageLayout)throws Exception{
    //Get the page layout as a graphics container.
    IGraphicsContainer graphicsContainer = (IGraphicsContainer)docPageLayout;
    IElement docElement =;
    //Enumerate through the graphics container, finding all mapSurroundFrames.
    while (docElement != null){
        if (docElement instanceof IMapSurroundFrame){
            IMapSurroundFrame mapSurroundFrame;
            mapSurroundFrame = (IMapSurroundFrame)docElement;
            //If a surroundframe is found, report the name of the surround and
            //the name of the map that it is associated with. 
            System.out.println("Found mapsurround " +
                mapSurroundFrame.getMapSurround().getName() + 
                " associated with map " + mapSurroundFrame.getMapSurround().getMap()
        docElement =;

Development licensingDeployment licensing
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced
Engine Developer KitEngine