Summary
Returns a Python list of layout elements that exist within a map document (.mxd) layout.
Discussion
ListLayoutElements always returns a Python list object even if only one page element is returned. In order to return an element object, an index value must be used on the list (e.g., elm = arcpy.mapping.ListLayoutElements(mxd)[0]). For loops on a list provide an easy mechanism to iterate through each item in the list (e.g., for elm in arcpy.mapping.ListLayoutElements(mxd):).
ListLayoutElements only returns elements from a page layout and not map annotation elements that may exist within a data frame.
Each page element has a name property that can be set within the element properties dialog box within ArcMap (located on the Size and Position tab). It is the map document author's responsibility to ensure each page element is given a unique name so that elements can be uniquely identified. If two elements have the same name, there is no way for certain to ensure it is the element you want to reference.
ListLayoutElements will also return the elements within a group element into a flattened list. This makes it possible to easily search and replace text strings, for example, without having to navigate through a group element structure.
The element_type parameter can be skipped simply by passing an empty string ("") or entering element_type=None.
Wildcards are used on the name property and are not case sensitive. A wildcard string of "*title" will return a page element with a name Main Title. Wildcards can be skipped in the scripting syntax simply by passing an empty string (""), an asterisk (*), or entering wildcard=None, or nothing at all if it is the last optional parameter in the syntax.
Refer to the individual element objects for more information: DataFrame, GraphicElement, LegendElement, MapsurroundElement, PictureElement, and TextElement.
Syntax
ListLayoutElements (map_document, {element_type}, {wildcard})| Parameter | Explanation | Data Type |
map_document | A variable that references a MapDocument object. | MapDocument |
element_type | A string that represents the element type that will be used to filter the returned list of elements.
(The default value is None) | String |
wildcard | A combination of asterisks (*) and characters can be used to help limit the results. (The default value is None) | String |
| Data Type | Explanation |
| Object | A Python list of page layout elements. The types of objects that can be returned are: DataFrame, GraphicElement, LegendElement, MapsurroundElement, PictureElement, and TextElement. |
Code sample
This script will search all text elements, including elements in a group, that have a text value of Old String and replace that value with New String.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for elm in arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT"):
if elm.text == "Old String":
elm.text = "New String"
mxd.save()
del mxdThe following script will find a picture element using a wildcard and then change the picture's data source.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for elm in arcpy.mapping.ListLayoutElements(mxd,"PICTURE_ELEMENT", "*logo*"):
if elm.name == "CityLogo":
elm.sourceImage = r"C:\Project\Data\Photo.bmp"
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd