ListLayoutElements (arcpy.mapping)

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. DATAFRAME_ELEMENT —Dataframe element GRAPHIC_ELEMENT —Graphic element LEGEND_ELEMENT —Legend element MAPSURROUND_ELEMENT —Mapsurround element PICTURE_ELEMENT —Picture element TEXT_ELEMENT —Text element (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

Return Value

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

ListLayoutElements example 1:

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 mxd

ListLayoutElements example 2:

The 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