ArcMap

MapsurroundElement

Summary

Provides access to properties that enables its repositioning on the page layout as well as identifying its parent data frame.

Discussion

A MapsurroundElement object is a page element that has an association with a data frame. For example, there is a one-to-one relationship between a north arrow and a data frame. Mapsurround elements also include scale text and scale bars items. There is a property called parentDataFrameName that allows you to find the elements that are associated with a particular data frame. A legend element is also an example of a mapsurround, but because it has additional properties, it is a separate element type. The ListLayoutElements function returns a Python list of page layout element objects. It is necessary to then iterate through each item in the list or specify an index number to reference a specific page element object. To return a list of only MapsurroundElements, use the MAPSURROUND_ELEMENT constant for the element_type parameter. A wildcard can also be used to further refine the search based on the element name.

It is recommended that each page layout element be given a unique name so that it can be easily isolated using arcpy scripting. X and Y element positions are based on the element's anchor position, which is set via the Size and Position tab on the Elements Properties dialog box in ArcMap.

Properties

PropertyExplanationData Type
elementHeight
(Read and Write)

The height of the element in page units. The units assigned or reported are in page units.

Double
elementPositionX
(Read and Write)

The x location of the data frame element's anchor position. The units assigned or reported are in page units.

Double
elementPositionY
(Read and Write)

The y location of the data frame element's anchor position. The units assigned or reported are in page units.

Double
elementWidth
(Read and Write)

The width of the element in page units. The units assigned or reported are in page units.

Double
name
(Read and Write)

The name of the element.

String
parentDataFrameName
(Read Only)

A string that represents the name of the DataFrame for the associated element.

String
type
(Read Only)

Returns the element type for any given page layout element.

  • DATAFRAME_ELEMENT —Dataframe element
  • GRAPHIC_ELEMENT —Graphic element
  • LEGEND_ELEMENT —Legend element
  • MAPSURROUND_ELEMENT —Mapsurround element
  • PICTURE_ELEMENT —Picture element
  • TEXT_ELEMENT —Text element
String

Code sample

MapsurroundElement example

The following script will find the mapsurround element named ScaleBar and change it's position.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
scaleBar = arcpy.mapping.ListLayoutElements(mxd, "MAPSURROUND_ELEMENT", "ScaleBar")[0]
df = arcpy.mapping.ListDataFrames(mxd, scaleBar.parentDataFrameName)[0]
scaleBar.elementPositionX = df.elementPositionX + (df.elementWidth / 2)
mxd.save()
del mxd