Working with map surrounds


About working 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.
The first code example in this topic adds a legend to the page layout. North arrows and legends are types of map surrounds. All map surrounds are held in 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 which layers and symbology a map contains. The second code example shows how to access the map surrounds through the MapSurroundFrame.
The following code example shows how to add a MapSurroundFrame to a given map and page layout:
[C#]
public void AddMapSurround(IPageLayout pageLayout, IActiveView activeView)
{
    IMap map = activeView.FocusMap;
    IGraphicsContainer graphicsContainer = pageLayout as IGraphicsContainer;
    IFrameElement frameElement = graphicsContainer.FindFrame(map);
    IMapFrame mapFrame = (IMapFrame)frameElement;
    IMapSurroundFrame mapSurroundFrame = new MapSurroundFrameClass();
    UID elementUID = new UIDClass();

    //The value determines the type of MapSurroundFrame being added.
    elementUID.Value = "esriCarto.Legend";

    //The CreateSurroundFrame method takes the UID of the element and an optional style.
    mapSurroundFrame = mapFrame.CreateSurroundFrame(elementUID, null);
    mapSurroundFrame.MapSurround.Name = "Legend";

    //Cast the MapSurroundFrame as an element so it can be inserted into the page layout.
    IElement doc_Element = mapSurroundFrame as IElement;
    IElement mainMap_Element = mapFrame as IElement;
    IGeometry geometry = mainMap_Element.Geometry;
    IEnvelope mainMap_Envelope = geometry.Envelope;
    IEnvelope envelope = new EnvelopeClass();
    double xMin = mainMap_Envelope.XMax + 1.5;
    double yMin = mainMap_Envelope.YMin + 1.5;
    double xMax = mainMap_Envelope.XMax - 1.5;
    double yMax = mainMap_Envelope.YMax - 1.5;
    envelope.PutCoords(xMin, yMin, xMax, yMax);

    doc_Element.Geometry = envelope as IGeometry;
    doc_Element.Activate(activeView.ScreenDisplay);
    graphicsContainer.AddElement(doc_Element, 0);

    activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, null, null);
}
[VB.NET]
Public Sub AddMapSurround(ByVal pageLayout As IPageLayout, ByVal activeView As IActiveView)
    
    Dim map As IMap = activeView.FocusMap
    Dim graphicsContainer As IGraphicsContainer = TryCast(pageLayout, IGraphicsContainer)
    Dim frameElement As IFrameElement = graphicsContainer.FindFrame(map)
    Dim mapFrame As IMapFrame = CType(frameElement, IMapFrame)
    
    Dim mapSurroundFrame As IMapSurroundFrame = New MapSurroundFrameClass()
    Dim elementUID As UID = New UIDClass
    
    'The value determines the type of MapSurroundFrame being added.
    elementUID.Value = "esriCarto.Legend"
    
    'The CreateSurroundFrame method takes the UID of the element and an optional style.
    mapSurroundFrame = mapFrame.CreateSurroundFrame(elementUID, Nothing)
    mapSurroundFrame.MapSurround.Name = "Legend"
    
    'Cast the MapSurroundFrame as an element so it can be inserted into the page layout.
    Dim doc_Element As IElement = TryCast(mapSurroundFrame, IElement)
    Dim mainMap_Element As IElement = TryCast(mapFrame, IElement)
    Dim geometry As IGeometry = mainMap_Element.Geometry
    Dim mainMap_Envelope As IEnvelope = geometry.Envelope
    Dim envelope As IEnvelope = New EnvelopeClass
    Dim xMin As Double = mainMap_Envelope.XMax + 1.5
    Dim yMin As Double = mainMap_Envelope.YMin + 1.5
    Dim xMax As Double = mainMap_Envelope.XMax - 1.5
    Dim yMax As Double = mainMap_Envelope.YMax - 1.5
    envelope.PutCoords(xMin, yMin, xMax, yMax)
    
    doc_Element.Geometry = TryCast(envelope, IGeometry)
    doc_Element.Activate(activeView.ScreenDisplay)
    graphicsContainer.AddElement(doc_Element, 0)
    
    activeView.PartialRefresh(esriViewDrawPhase.esriViewGraphics, Nothing, Nothing)
    
End Sub
The following code example shows how to find and access the MapSurroundFrame:
[C#]
public void ReportMapSurrounds(IPageLayout pageLayout)
{
    //Get the page layout as a graphics container.
    IGraphicsContainer graphicsContainer = pageLayout as IGraphicsContainer;
    graphicsContainer.Reset();
    IElement element = graphicsContainer.Next();

    //Enumerate through the graphics container, finding all MapSurroundFrames.
    while (element != null)
    {
        if (element is IMapSurroundFrame)
        {
            IMapSurroundFrame mapSurroundFrame = element as IMapSurroundFrame;
            IMapSurround mapSurround = mapSurroundFrame.MapSurround;
            IMap map = mapSurround.Map;

            //If a SurroundFrame is found, report the name of the surround and
            //the name of the map with which it is associated. 
            string mapSurroundName = mapSurround.Name;
            string mapName = map.Name;
            MessageBox.Show("Found mapsurround " + mapSurroundName + 
                " associated with map " + mapName);
        }
        element = graphicsContainer.Next();
    }
}
[VB.NET]
Public Sub ReportMapSurrounds(ByVal pageLayout As IPageLayout)
    
    'Get the page layout as a graphics container.
    Dim graphicsContainer As IGraphicsContainer = TryCast(pageLayout, IGraphicsContainer)
    graphicsContainer.Reset()
    Dim element As IElement = graphicsContainer.Next()
    
    'Enumerate through the graphics container, finding all MapSurroundFrames.
    While Not element Is Nothing
        
        If TypeOf element Is IMapSurroundFrame Then
            
            Dim mapSurroundFrame As IMapSurroundFrame = TryCast(element, IMapSurroundFrame)
            Dim mapSurround As IMapSurround = mapSurroundFrame.MapSurround
            Dim map As IMap = mapSurround.Map
            
            'If a SurroundFrame is found, report the name of the surround and
            'the name of the map with which it is associated.
            Dim mapSurroundName As String = mapSurround.Name
            Dim mapName As String = map.Name
            MessageBox.Show("Found mapsurround " + mapSurroundName + " associated with map " + mapName)
            
        End If
        
        element = graphicsContainer.Next()
        
    End While
    
End Sub


See Also:

Map surrounds




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced
Engine Developer Kit Engine