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
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo
Engine Developer Kit Engine Runtime