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:
C:ArcpyBookCh4Crime_Ch4.mxd
in ArcMap.arcpy.mapping
module:import arcpy.mapping as mapping
Crime_Ch4.mxd
), and assign this reference to a variable:mxd = mapping.MapDocument("CURRENT")
ListLayoutElements()
method with a wildcard and restriction of only legend elements to return only the Crime
legend and store it in a variable:elLeg = mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT","*Crime*")[0]
title
property to update the title of the legend:elLeg.title = "Crimes by School District"
for item in elLeg.listLegendItemLayers(): print(item.name)
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)
c:ArcpyBookcodeCh4UpdateLayoutElementProperties.py
solution file.Burglaries in 2009 Crime Density by School District
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.