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 surroundsTo 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):
ESRI.ArcGIS.Carto ESRI.ArcGIS.Geometry ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)System.Windows.Forms
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 |