Each layout element has a set of properties that you can update programmatically. For example, LegendElement includes properties that allow you to change the position of the legend on the page, update the legend title, and access legend items.
There are many different types of layout elements, including graphics, legends, text, maps, and pictures. Each of these elements is represented by a class in the arcpy.mapping package. These classes provide various properties that you can use to programmatically alter the element.
The DataFrame class provides access to the data frame properties in the map document file. This object can work with both map units and page layout units, depending on the property being used. Page layout properties, such as positioning and sizing, can be applied to the properties, including elementPositionX, elementPositionY, elementWidth, and elementHeight.
The GraphicElement object is a generic object for various graphics that can be added to the page layout, including tables, graphs, neatlines, markers, lines, and area shapes. You'll want to make sure that you set the name property for each graphic element (and any other element for that matter), if you intend to access it through a Python script.
LegendElement provides operations to position the legend on the page layout, modification of the legend title, and also provides access to the legend items and the parent data frame. LegendElement can only be associated with a single data frame.
MapSurroundElement can refer to north arrows, scale bars, and scale text. It is similar to LegendElement and is associated with a single data frame. Properties on this object enable repositioning of the element on the page.
PictureElement represents a raster or image on the page layout. The most useful property of this object enables acquiring and setting the data sources, which can be extremely helpful when you need to change a picture, such as a logo, in multiple map documents. For example, you could write a script that iterates through all your map document files and replaces the current logo with a new logo. You can also reposition or resize the object.
TextElement represents text on a page layout, including inserted text, callouts, rectangle text, and titles, but does not include legend titles or texts that are part of a table or chart. Properties enable the modification of a text string, which can be extremely useful in situations where you need to make the same text string change in multiple places in the page layout or over multiple map documents, and of course, repositioning of the object is also available.
Each element in the page layout is returned as an instance of one of the element objects. In this recipe, we're going to use the title property of the Legend object to programmatically change the title of the Crime legend and obtain a list of the layers that are part of the legend.
Follow these steps to learn how to update the properties of a layout element:
- Open
C:ArcpyBookCh4Crime_Ch4.mxdin ArcMap. - Open the Python window.
- Import the
arcpy.mappingmodule:import arcpy.mapping as mapping
- Reference the currently active document (
Crime_Ch4.mxd), and assign this reference to a variable:mxd = mapping.MapDocument("CURRENT") - Use the
ListLayoutElements()method with a wildcard and restriction of only legend elements to return only theCrimelegend and store it in a variable:elLeg = mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT","*Crime*")[0]
- Use the
titleproperty to update the title of the legend:elLeg.title = "Crimes by School District"
- Get a list of the layers that are a part of the legend and print the names:
for item in elLeg.listLegendItemLayers(): print(item.name)
- The entire script should appear as follows:
import arcpy.mapping as mapping mxd = mapping.MapDocument("CURRENT") elLeg = mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT","*Crime*")[0] elLeg.title = "Crimes by School District" for item in elLeg.listLegendItemLayers(): print(item.name) - You can check your work by examining the
c:ArcpyBookcodeCh4UpdateLayoutElementProperties.pysolution file. - Run the script. You should see the following layers printed:
Burglaries in 2009 Crime Density by School District
- The change is displayed in the following screenshot:
Each of the layout elements has a set of properties and methods. In this particular case, we've used the title property on the Legend object. Other properties of this object allow you to set the width and height, positioning, and so on. Methods used for the Legend object give you the ability to adjust the column count, list the legend items, and remove and update items.