Map Surrounds

In this topic:

Working with Map Surrounds

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 amount.
In ArcMap, map surrounds are always contained by a MapSurroundFrame object—a type of element. The PageLayout manages all frame elements contained within the MapSurroundFrame. Each MapSurroundFrame is a child of a MapFrame; if a MapFrame is deleted, all of its MapSurroundFrames are deleted as well. It is important to note that Map surrounds are placed on the layout, not in a Map’s graphics layer.
Map surrounds can be moved anywhere on the layout, not just within the confines of a map frame. Because map surrounds are directly associated with a Map, the Map has a shortcut to all the map surrounds associated with it, IMap.getMapSurround(). This member, along with IMap.getMapSurroundCount, allows you to loop through all of the available map surrounds for a given Map object.
All map surrounds implement the IMapSurround interface. This interface provides functionality common to all types of map surrounds. Use this interface to access the name of a particular map surround and the associated map. This interface also has methods for determining a surround’s size and changing it.
IMapSurroundEvents is the outbound interface for all map surround objects. A common usage of this event interface is to trigger redraws on a map surround within a given window.

The Legend coclass is a complex MapSurround object because it relies on several other objects to create a legend.

The Legend’s primary interface is ILegend. Use this interface to modify a legend’s components. For example, this interface provides access to the legend’s items and its legend format object. ILegend also manages a few of the legend properties such as the title. When changing the properties of an existing legend, you must call Legend.refresh() to have the changes reflected in the layout.
The renderers used to display the different map layers provide the different elements comprised in a legend. Each renderer corresponds to a LegendItem in the legend. Each LegendItem contributes one or more LegendGroup objects to the legend. The number of legend groups depends on the renderer’s implementation; for instance, the Multiple Attributes renderer may provide up to three legend groups.
Each LegendGroup, in turn, contains one or more Legend ArcObjects. A Legend ArcObject represents an individual classification and has its own symbol and label—a description and format are optional. The illustration below identifies these elements in a legend.
Legend items
The construction of the legend is mostly the work of the map layers through the associated LegendItem objects. The Legend can be seen as a collection of layers with each layer represented by a LegendItem. When the legend is refreshed, the LegendItem creates a set of graphic elements to display itself, pulling the information from its associated layer and the format from the objects described in the previous section. The Legend simply positions the title and legend item graphics relative to one another.
All legend items implement the ILegendItem interface. The interface controls all of the default properties a legend item has—the layer it is associated with; the number of columns it should span; whether to display in a new column; and whether the label, description, heading, and layer name should display. This interface also provides access to the legend items LegendFormat ArcObject.
Horizontal and vertical legend items use the esriLegendItemArrangement enumeration, which can be set with IHorizontalLegendItem.setArrangement() and IVerticalLegendItem.setArrangement() to specify the position of the label, patch, and description. The default is esriPatchLabelDescription, which translates to the patch on the far left, label to the right of the patch, then the description, if available, on the far right.
The following illustration shows these parts of the legend the esriPatchLabelDescription order with a custom area patch.
There are currently four types of legend items: HorizontalLegendItem, VerticalLegendItem, HorizontalBarLegendItem, and NestedLegendItem.
Horizontal legend items are the default and most commonly used class of legend items. The IHorizontalBarLegendItem interface supports additional properties for controlling the angle of the labels above and below the patch. The default is to display the labels at a 45-degree angle.
Vertical legend items have the patches on top of the legend item text.
Nested legend items only work with graduated symbols. The INestedLegendItem interface controls the many properties a nested legend item has, including whether or not to label the ends, the leader symbol, and the outline symbol.
The aspect of the legend can be modified using the ILegendFormat interface on the LegendFormat ArcObject returned by Legend.getFormat() method. You can also use the IReadingDirection interface to set whether the legend items are aligned along the left or right side. To control the appearance of the legend more precisely you may also use a number of interface to access the individual components of the legend: the LegendItems and the patches. (Patches are the individual color boxes or lines associated with each legend class. For more information on patches, see the help under IPatch).
ILegendClassFormat is an interface very similar to ILegendFormat but at the LegendItem level. If the renderer creating the legend does not set the LegendClassFormat, the properties used to draw the LegendItem's content will be the default defined in the LegendFormat object.
North arrows
MarkerNorthArrows are character marker symbols typically coming from the ESRI North font. However, any character from any font can be used as a North arrow. In addition to the standard Map surround interfaces, MarkerNorthArrows implement two additional interfaces: INorthArrow and IMarkerNorthArrow.
The INorthArrow interface provides a common interface for North arrow properties, such as size, color, and reference location.
IMarkerNorthArrow has methods, getMarkerSymbol() and setMarkerSymbol(), that controls which marker symbol the North arrow uses. By default, the marker symbol belongs to the ESRI North font.

Map insets
A map inset is a miniature map that typically shows a magnified view of an actual map. A MapInset map surround is another view of the current map extent. If you pan or zoom in on the map the MapInset relates to, the MapInset will mimic the change.
An overview map surround is the surround found in overview data windows.

Map title and overviews

The map title object is a map surround that holds a piece of text you can use to label a map. This may not be the title of the whole layout, but rather a subtitle for a specific map in the layout.

Scale bars

There are many types of scale bar map surrounds, including scale lines, single-fill scale bars, and double-fill scale bars. All scale bars implement IScaleBar and IScaleMarks.
The IScaleBar interface manages scale bar properties including bar color, bar height, division, and label frequency. The IScaleMarks interface manages all of the properties of a scale bar that relate to the individual marks, including the division and subdivision marks heights and symbols, the marks frequency, and their position.
Double-fill scale bars are the most advanced scale bars. These use two symbols to create an attractive scale bar. There are currently three types of double-fill scale bars: alternating, double alternating, and hollow. The graphic above shows an example of each.
All double-fill scale bars implement the IDoubleFillScaleBar interface. This interface manages the two fill symbols used when rendering the scale bar.
Single-fill scale bars are similar to double-fill scale bars except they use one fill symbol. ArcMap currently has one single-fill scale bar, the SingleDivisionScaleBar. The graphic above shows an example of a single-division scale bar. The ISingleFillScaleBar interface manages the single-fill symbol used by scale bars of this type.

Scale line scale bars are the only class of scale bars that represent a scale bar as a line. ArcMap currently has one type of scale line scale bar—the stepped-line scale bar. The IScaleLine interface manages the one line symbol used by scale lines.


ScaleText is a text element that describes the map’s scale, for example, “1 inch equals 2,400 miles”. The interface IScaleText controls the format of the string that is added as a map surround element. This interface has properties such as MapUnits and MapUnitLabel, PageUnits and PageUnitLabel, and Text, which combine the label properties into a sentence.

See Also:

How to interact with Map Surrounds

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