Map surrounds

About map surrounds

Map surrounds are specific types of elements associated with a Map object. An 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 contained by a MapSurroundFrame object (a type of element). The PageLayout manages the frame elements contained in the MapSurroundFrame. Each MapSurroundFrame is a child of MapFrame. If a MapFrame is deleted, its MapSurroundFrames are also deleted. The following illustration shows the MapSurroundFrame object:
Map surrounds are placed on the layout, not on a map's graphic layer.
Map surrounds can be moved most anywhere on the layout, except 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 (the IMap.MapSurround property). This property, along with IMap.MapSurroundCount, allows you to loop through 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 map surround objects. A common use of this event interface is to trigger redraws on a map surround in a given window.

Legend

The Legend object is a complex MapSurround object because it relies on several other objects to create a legend. The following illustration shows the Legend object:

 
 
The Legend object'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 LegendFormat object. ILegend also manages a few of the legend properties, such as Title. When changing the properties of an existing legend, you must call ILegend.Refresh to have the changes reflected in the layout.
The renderers used to display the different map layers provide the elements comprised in a legend. Each renderer corresponds to a legend item in the legend. Each legend item contributes one or more LegendGroup objects to the legend. The number of legend groups depends on the renderer’s implementation, for example, the Multiple Attributes renderer provides up to three legend groups.
Each LegendGroup object, in turn, contains one or more LegendClass objects. A LegendClass object represents an individual classification and has its own symbol and label (a description and format are optional). The following shows an illustration that maps ArcMap layer renderers' legend groups and classes to a typical legend.

Legend items

The construction of the legend is primarily 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 legend item. When the legend is refreshed, the legend item creates a set of graphic elements to display itself, obtaining the information from its associated layer and the format from the objects described in the previous section. The legend positions the title and legend item graphics relative to one another.
All legend items implement the ILegendItem interface. This interface controls the default properties of a legend item—the layer with which it is associated; 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 item's LegendClassFormat object.
HorizontalLegendItem and VerticalLegendItem use the esriLegendItemArrangement enumeration, which can be set with IHorizontalLegendItem.Arrangement and IVerticalLegendItem.Arrangement, 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 the parts of the legend the esriPatchLabelDescription orders with a custom area patch.
 
 
The following legend item types are available:
  • Horizontal legend items are the default and most commonly used class of legend items. Horizontal legend items are shown in the following illustration:

  • The IHorizontalBarLegendItem interface supports additional properties for controlling the angle of the labels above and below the patch. The default of the HorizontalBarLegendItem object is to display the labels at a 45-degree angle. Horizontal bar legend items are shown in the following illustration:
 
  • Vertical legend items have the patches on top of the legend item text and are shown in the following illustration:
     
  • Nested legend items only work with graduated symbols. The INestedLegendItem interface controls the many properties of a NestedLegendItem object, such as whether or not to label the ends, the leader symbol, and the outline symbol. Nested legend items are shown in the following illustration:
     
The aspect of the legend can be modified using the ILegendFormat interface on the LegendFormat object returned by ILegend.Format. 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 can use a number of interface to access the individual components of the legend, such as the legend items and the patches. (Patches are the individual color boxes or lines associated with each legend class.) For more information on patches, see IPatch.
ILegendClassFormat is an interface similar to ILegendFormat but at the legend item level. If the renderer creating the legend does not set LegendClassFormat, the properties used to draw the legend item's content will be the default defined in the LegendFormat object.

North arrow

Marker north arrows are character marker symbols that are typically 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, the MarkerNorthArrow object implements two interfaces: INorthArrow and IMarkerNorthArrow. The MarkerNorthArrow object is shown in the following illustration:
 
 
The INorthArrow interface provides a common interface for north arrow properties, such as size, color, and reference location.
IMarkerNorthArrow has one property, MarkerSymbol, that controls the marker symbol that the north arrow uses. By default, the marker symbol belongs to the ESRI North font.

Map inset

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 to which the map inset relates, the map inset mimics the change. The MapInset object is shown in the following illustration:

 
MapTitle object and Overview map surround

The MapTitle 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.
An Overview map surround is the surround found in overview data windows.
The MapTitle and Overview objects are shown in the following illustration:
  

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 Scalebar properties including bar color, bar height, division, and label frequency. The IScaleMarks interface manages the properties of a scale bar that relate to the individual marks, such as the division and subdivision marks heights, division and subdivision mark symbols, and the mark frequency and position.

Double fill

Double-fill scale bars are the most advanced scale bars, using two symbols to create an attractive scale bar. The three types of double-fill scale bars are alternating, double alternating, and hollow. The following illustration shows an example of each:
 
The AlternatingScaleBar, DoubleAlternatingScaleBar, and HollowScaleBar objects are shown in the following illustration:
 
All double-fill scale bars implement the IDoubleFillScaleBar interface. This interface manages the two fill symbols used when rendering the scale bar.

Single fill

Single-fill scale bars are similar to double-fill scale bars except they use one fill symbol. ArcMap has one single-fill scale bar, SingleDivisionScaleBar. The following illustration 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

ScaleLine scale bars are the only class of scale bars that represent a scale bar as a line. ArcMap has one type of scale line scale bar, SteppedScaleLine. The following illustration shows an example of a stepped-line scale bar:
 
The SteppedScaleLine object is shown in the following illustration:
  
The IScaleLine interface manages the one line symbol used by scale lines.

Scale text

Scale text 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, MapUnitLabel, PageUnits, and PageUnitLabel, as well as Text, which combines the label properties into a sentence.
The ScaleText object is shown in the following illustration:

 


See Also:

Working with the page layout
Working with map surrounds



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