ListLayoutElements (arcpy.mapping)

Récapitulatif

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.

Syntaxe

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

Paramètre	Explication	Type de données
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 (La valeur par défaut est None)	String
wildcard	A combination of asterisks (*) and characters can be used to help limit the results. (La valeur par défaut est None)	String

Valeur renvoyée

Type de données	Explication
Object	A Python list of page layout elements. The types of objects that can be returned are: DataFrame, GraphicElement, LegendElement, MapsurroundElement, PictureElement, and TextElement.

Exemple de code

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