Working with Layout Elements in the ArcPy Mapping Module
In my last post I introduced the ArcPy Mapping module, released with ArcGIS 10, which provides a number of capabilities including the management of map documents and layers, printing, exporting, ArcGIS Server publishing, map automation, and the creation of PDF map books. Today we’re going to take a closer look at the Layout classes provided by the module.
The ListLayoutElements() function returns a list of Layout elements in the form of various Layout classes. Each element can be one of: GraphicElement, LegendElement, PictureElement, TextElement, MapSurroundElement, or PictureElement as seen in the graphic below.
ListLayoutElements() is a versatile function which in its most basic form is used to return a list of all the layout elements on the page layout of a map document. However, there are two optional parameters that you can supply to filter this list. The first type of filter is an element type filter in which you specify that you only want to return one of the layout element types. You can also apply a wildcard to filter the returned list. These two types of filters can be used in combination. For example, in the code below we are specifying that we only want to return LEGEND_ELEMENT objects with the name “Legend Crime”. This would likely result in a highly filtered list, and as we can see only a single item was returned.
Each graphic on a layout has a ‘name’ property that you can view in ArcMap by right clicking the element and selecting Properties. Most elements are assigned a default name if you don’t specifically supply one. You should make it a best practice to assign a unique ‘name’ to each element on your page layout. This will make it easier for you to access particular elements from your Python scripts.
Each element on the page layout has various properties that can be set through your Python code. For example, in the code block below we are accessing a specific Legend element (“Legend Crime”) and assigning a new title to the legend.
In this case we are only changing the Legend title. However, LegendElement provides other properties that enable it to be repositioned on the page layout as well as getting legend items and the parent data frame.
Below is a brief description of each of the layout elements accessible through Python.
The DataFrame class provides access to data frame properties in the map document file. This object can work with both map units and page layout units depending upon the property being used. Page layout properties such as positioning and sizing can be applied to the properties on this slide 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.
The LegendElement provides operations for positioning of the legend on the page layout, modification of the legend title, and also provides access to the legend items and the parent data frame. A LegendElement can be associated with only a single data frame.
The MapsurroundElement can refer to north arrows, scale bars, and scale text and like LegendElement is associated with a single data frame. Properties on this object enable repositioning on the page.
PictureElement represents a raster or image on the page layout. The most useful property on this object allows for getting and setting the data source which can be extremely helpful when you need to change out a picture such as 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 the object.
TextElement represents text on a page layout including inserted text, callouts, rectangle text and titles, but does not include legend titles or text that is part of a table or chart. Properties enable modifying the 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.
The next session of our Internet based, instructor led course, GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS begins October 25th. This course is only $499 when you register by August 31st. The regular price of this course is $667.