MapsurroundElement (arcpy.mapping)
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
| Property | Explanation | Data 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.
| String |
Code Sample
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