ListLayoutElements (arcpy.mapping)

Resumen

Returns a Python list of layout elements that exist within a map document (.mxd) layout.

Debate

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.

Sintaxis

ListLayoutElements (map_document, {element_type}, {wildcard})

Parámetro	Explicación	Tipo de datos
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 (El valor predeterminado es None)	String
wildcard	A combination of asterisks (*) and characters can be used to help limit the results. (El valor predeterminado es None)	String

Valor de retorno

Tipo de datos	Explicación
Object	A Python list of page layout elements. The types of objects that can be returned are: DataFrame, GraphicElement, LegendElement, MapsurroundElement, PictureElement, and TextElement.

Ejemplo de código

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