This document is archived and information here might be outdated.  Recommended version.


Working with map surrounds (ArcObjects .NET 10.6 SDK)
ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Interacting with and configuring maps, layers, and graphics > Working with the page layout > Working with map surrounds (ArcObjects .NET 10.6 SDK)

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 Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced
Engine Developer Kit Engine