MapSurroundElement

Summary

The MapsurroundElement class provides access to size and positioning properties as well as a reference to the associated map frame.

Discussion

A MapSurroundElement is a layout element that has an associated MapFrame element and is dynamically linked to map frame information. For example, a north arrow is a map surround and is linked to the associated map frame's map rotation, and a scale bar is linked to the map's scale. The listElements method on the Layout class returns a Python list of all possible layout elements. To return a list of only MapSurroundElement objects, use the MAPSURROUND_ELEMENT constant for the element_type parameter. A wildcard value can also be used to further refine the search based on the element name value. It is important to uniquely name each layout element so it can be referenced using ArcPy scripting.

A MapSurroundElement is a generic object with relatively few properties. Many of the properties are related to size and position of the map surround on the layout. The mapFrame property will return a reference to a MapFrame object and from that object, you can access the map frame's map using its map property.

A number of layout elements return a type value of MAPSURROUND_ELEMENT. These include north arrows, scale bars, chart frames, table frames, and possibly other future element types that don't currently have a dedicated object with specialized properties. You can access some of these specialized object properties using Python CIM access. Examples of this are provided in the code samples below. One example of a map surround with specialized methods and properties is LegendElement. It returns an element type value of LEGEND_ELEMENT.

Caution:

In future development, objects with a current type value of MAPSURROUND_ELEMENT may be made into their own specialized object type, which would potentially affect the value of the element's type property and the element_type enumeration list available to the layout listElements method.

The elementPositionX and elementPositionY values are based on the element's anchor position, which is set on the Format tab. The default position depends on the type of map surround. For example, a north arrow's anchor default position is the center point, but a scale bar's default position is the lower left.

You can also create map surrounds using the createMapSurroundElement method on the Layout class. Using this method, you are limited to creating map surround element types based on the map_surround_type input parameter. It's also useful to reference an existing StyleItem element during creation to control how the element appears in the layout. Examples of this are below.

Properties

Property	Explanation	Data Type
anchor (Read Only)	Returns one of the following string values that represent the current anchor position. To change the value, use the setAnchor method. BOTTOM_LEFT_CORNER—Bottom left corner position BOTTOM_MID_POINT—Bottom center position BOTTOM_RIGHT_CORNER—Bottom right corner position CENTER_POINT—Center position LEFT_MID_POINT—Left center position RIGHT_MID_POINT—Right center position TOP_LEFT_CORNER—Top left corner position TOP_MID_POINT—Top center position TOP_RIGHT_CORNER—Top right corner position	String
elementHeight (Read and Write)	The height of the element in page units.	Double
elementPositionX (Read and Write)	The x-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Read and Write)	The y-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementRotation (Read and Write)	The element's rotation angle in degrees. Positive values rotate clockwise and negative values rotate counterclockwise. Note: This property does not apply to north arrows because their rotation is based on the rotation of the map.	Double
elementWidth (Read and Write)	The width of the element in page units.	Double
locked (Read and Write)	When set to True, the element cannot be graphically selected in the layout view.	Boolean
longName (Read Only)	An element's full name including group information if it exists. For example, an element named 'North Arrow' in a group element named 'Group Element' will return a longName value of 'Group Element\\North Arrow'. If the element is not in a group, the longName will be the same as the name value.	String
mapFrame (Read and Write)	A reference to the associated MapFrame.	MapFrame
name (Read and Write)	The name of the element. It is important that all elements have a unique name so they can be uniquely referenced using the wildcard parameter with the listElements function on the Layout object.	String
parentGroupElement (Read Only)	If the element is in a group, the value returned will be a GroupElement, otherwise a NoneType will be returned.	GroupElement
type (Read Only)	Returns a value of MAPSURROUND_ELEMENT.	String
visible (Read and Write)	Returns True if the element is visible on the layout. Rather than having to move unwanted objects off the page before printing or exporting, you can turn the element's visibility on and off.	Boolean

Method Overview

Method	Explanation
applyStyleItem (style_item)	Applies a StyleItem to a MapSurroundElement.
getDefinition (cim_version)	Returns a map surround element's CIM definition.
setAnchor (anchor)	The setAnchor method controls the anchor position for a MapSurroundElement value.
setDefinition (definition_object)	Sets a map surround element's CIM definition.

Methods

applyStyleItem (style_item)

Parameter	Explanation	Data Type
style_item	A reference to a StyleItem in a project.	StyleItem

When referencing a StyleItem using the listStyleItems method on the ArcGISProject class, the style_class parameter must be NORTH_ARROW or SCALE_BAR. For more information and code samples, refer the to StyleItem help topic.

Note:

Styles must be added to a project prior to using the applyStyleItem method. They can be added using the updateStyles method on the ArcGISProject class.

getDefinition (cim_version)

Parameter	Explanation	Data Type
cim_version	A string that represents the major version of the CIM that will be used. V2—The 2.x version of the CIM will be used. V3—The 3.x version of the CIM will be used.	String

Return Value

Data Type	Explanation
Object	Returns the CIM definition for a MapsurroundElement value.

For more information about working with the CIM and samples, see Python CIM access.

setAnchor (anchor)

Parameter	Explanation	Data Type
anchor	A string that specifies the location of the anchor position. BOTTOM_LEFT_CORNER—The anchor will be set at the bottom left corner position. BOTTOM_MID_POINT—The anchor will be set at the bottom center position. BOTTOM_RIGHT_CORNER—The anchor will be set at the bottom right corner position. CENTER_POINT—The anchor will be set at the center position. LEFT_MID_POINT—The anchor will be set at the left center position. RIGHT_MID_POINT—The anchor will be set at the right center position. TOP_LEFT_CORNER—The anchor will be set at the top left corner position. TOP_MID_POINT—The anchor will be set at the top center position. TOP_RIGHT_CORNER—The anchor will be set at the top right corner position.	String

Setting the anchor position is helpful because you can control how the element might expand when resized. For example, the default anchor position for a scale bar map surround element is BOTTOM_LEFT_CORNER. If you change the anchor location to TOP_RIGHT_CORNER, changing elementHeight will expand the element downward instead of upward (the default), and changing elementWidth will expand the element to the left.

setDefinition (definition_object)

Parameter	Explanation	Data Type
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

For more information about working with the CIM and samples, see Python CIM access.

Code sample

MapsurroundElement example 1

The following script finds the MapsurroundElement named ScaleBar and changes its position so the center of the scale bar is located 0.5 page units below and to the center of its associated map frame. Note that the scale bar was authored with its anchor location in the center position. The map frame was authored with its anchor position located to the lower left.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Points of Interest")[0]
scaleBar = lyt.listElements("MAPSURROUND_ELEMENT", "ScaleBar")[0]
mf = scaleBar.mapFrame
scaleBar.elementPositionX = mf.elementPositionX + (mf.elementWidth / 2)
scaleBar.elementPositionY = mf.elementPositionY - 0.5
aprx.save()
del aprx

MapsurroundElement example 2

The following script creates a north arrow at a point location on a layout using an Esri system style. Then it uses Python CIM access to modify the calibrationAngle value.

#Page units Centimeters
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]

naStyle = p.listStyleItems('ArcGIS 2D', 'North_Arrow', 'Compass North 1')[0]
na = lyt.createMapSurroundElement(arcpy.Point(18.5,18), 'North_Arrow', mf,
                                      nArrowStyle, "Compass North Arrow")
na.elementWidth = 2

#CIM modifications - change calibration angle
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
    if elm.name == "Compass North Arrow":
        elm.northType = 'TrueNorth'
        elm.calibrationAngle = -2.5
lyt.setDefinition(lyt_cim)

MapsurroundElement example 3

The following script creates a scale bar on a layout using a helper function to create a rectangle for its placement and also uses an Esri system style. Then it uses Python CIM access to modify scale bar subdivisions and rounding.

#Helper function to make an envelope from a lower left X, Y, width and height
def MakeRec_LL(llx, lly, w, h):
    xyRecList = [[llx, lly], [llx, lly+h], [llx+w,lly+h], [llx+w,lly], [llx,lly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rec = arcpy.Polygon(array)
    return rec

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]

#Page units Centimeters
sbName = 'Double Alternating Scale Bar 1 Metric'
sbStyle = p.listStyleItems('ArcGIS 2D', 'Scale_bar', sbName)[0]
sbEnv = MakeRec_LL(1.5, 15, 8, 1)
sb = lyt.createMapSurroundElement(sbEnv, 'Scale_bar', mf, sbStyle, 'New Scale Bar')

#CIM modifications - change number of subdivisions and rounding
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
    if elm.name == 'New Scale Bar':
        elm.subdivisions = 2
        elm.numberFormat.roundingOption = "esriRoundNumberOfSignificantDigits"
        elm.numberFormat.roundingValue = 2
lyt.setDefinition(lyt_cim)

MapsurroundElement example 4

The following script creates a legend on a layout using an Esri system style and a helper function to create a rectangle for its placement. Then it uses Python CIM access to modify the minimum font size.

#Helper function to make an envelope from a upper left X, Y, width and height
def MakeRec_UL(ulx, uly, w, h):
    xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rec = arcpy.Polygon(array)
    return rec

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]

#Page units Centimeters
legStyle = p.listStyleItems('ArcGIS 2D', 'Legend', 'Legend 3')[0]
legEnv = MakeRec_UL(1.5, 14, 18.5, 10)
sb = lyt.createMapSurroundElement(legEnv, 'Legend', mf, legStyle, 'New Legend')

#CIM modifications - change the minimum font size
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
    if elm.name == 'New Legend':
        if elm.fittingStrategy == 'AdjustColumnsAndSize':
            elm.minFontSize = 8
lyt.setDefinition(lyt_cim)