Creating a list of layout elements

Often, the first step in a geoprocessing script that automates the production of maps is to generate a list of the available layout elements. For example, you might need to update the title of your map before printing or creating a PDF file. In this case, the title is likely be stored in a TextElement object. You can generate a list of TextElement objects in your map layout view and then change the title. The first step is to generate a list of TextElement objects.

Getting ready

In ArcMap, two views are available, namely data view and layout view. Data view is used to view geographic and tabular data, analyze data, symbolize layers, and manage data without regard for any particular map page size or layout. Layout view shows the map as printed on a page, and is used to create production quality maps through the addition of map elements. These elements include map frames, layers, legends, titles, north arrows, scale bars, and title blocks. Each object in the layout is represented in arcpy.mapping as a layout element class. Examples of many of these layout element classes are displayed in the following screenshot:

Each element can be assigned a unique name that can then be used to access the element programmatically. This unique name is defined in ArcMap. The arcpy.mapping module provides a ListLayoutElements() function that returns a list of all these elements. In this recipe, you will learn how to use the ListLayoutElements() function to generate a list of map layout elements.

How to do it…

Follow these steps to learn how to generate a list of layout elements:

1. Open C:\ArcpyBook\Ch4\Crime_Ch4.mxd in ArcMap.
2. Open the Python window.
3. Import the arcpy.mapping module:

   import arcpy.mapping as mapping

4. Reference the currently active document (Crime_Ch4.mxd) and assign this reference to a variable:

   mxd = mapping.MapDocument("CURRENT")

5. Generate a list of layout elements and print them to the screen if the name property is not empty:

   for el in mapping.ListLayoutElements(mxd):
     if el.name != '':
       print(el.name)

6. The entire script should appear as follows:

   import arcpy.mapping as mapping
   mxd = mapping.MapDocument("CURRENT")
   for el in mapping.ListLayoutElements(mxd):
     if el.name != '':
       print(el.name)

7. You can check your work by examining the c:\ArcpyBook\code\Ch4\CreateListLayoutElements.py solution file.
8. Run the script to see the following output:

   Crime_Inset
   Alternating Scale Bar
   Legend Test Performance
   Crime Legend
   North Arrow
   Inset_Map
   Test_Performance
   Crime
   

How it works…

ListLayoutElements() returns a list of layout elements in the form of various layout classes. Each element can be one of the GraphicElement, LegendElement, PictureElement, TextElement, or MapSurroundElement object instances. Each element can have a unique name. You don't have to assign a name to each element, but it is helpful to do so if you plan to access these elements programmatically in your scripts. In this script, we first made sure that the element had a name assigned to it before printing the name. This was done because ArcMap does not require that an element be assigned a name.