LegendElement

Synthèse

The LegendElement object provides access to properties that enable its positioning and resizing on the page layout as well as modifying its title. It also provides access to individual LegendItems.

Discussion

A LegendElement is very similar to MapSurroundElement. It has an association with a MapFrame using a property called mapFrame, but it also has a property called title.

The listElements method on the Layout object returns a Python list of page layout element objects. To return a list of MapsurroundElements only, use the MAPSURROUND_ELEMENT constant for the element_type parameter. A wildcard can also be used to further refine the search based on the element name. It is important that each page layout element be given a unique name so that it can be easily isolated using ArcPy scripting.

By default, layers added to a Map automatically get added to a legend. This makes it possible to author a Layout with an empty map and legend but have those items dynamically update when new layers are added to the map.

The elementPositionX and elementPositionY values are based on the element's anchor position, which is set on the Format tab. If you prefer that a LegendElement grows downward when layers are added, it is best to set the anchor position to be upper left.

The items property will return a list of LegendItem classes that can be individually modified to further customize the contents of a legend. The LegendElement class also provides AddItem, MoveItem, and RemoveItem methods, allowing you to better manage the items in a legend. Both the LegendElement and the LegendItem classes only provide access to common properties. Finer-grained access can be accomplished using Python CIM Access. Examples are provided with both class help topics.

Propriétés

Propriété	Explication	Type de données
columnCount (Lecture et écriture)	The number of specified columns in a legend. This property only applies if the fittingStrategy is set to AdjustFontSize, AdjustFrame, or ManualColumns.	Long
elementHeight (Lecture et écriture)	The height of the element in page units.	Double
elementPositionX (Lecture et écriture)	The x-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Lecture et écriture)	The y-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementRotation (Lecture et écriture)	Rotates the element relative to the anchor position. Positive values are counterclockwise and negative values are clockwise.	Double
elementWidth (Lecture et écriture)	The width of the element in page units.	Double
fittingStrategy (Lecture et écriture)	A string that represents a valid fitting strategy method. The valid values are as follows: AdjustFontSize—Adjust font size. AdjustColumns—Adjust columns. AdjustColumnsAndFont—Adjust columns and font size. AdjustFrame—Adjust frame. ManualColumns—Manual columns.	String
items (Lecture seule)	Returns a list of the associated LegendItem classes. You cannot directly set this property, but you can iterate through the legend items and modify their properties.	List
locked (Lecture et écriture)	When set to True, the element cannot be graphically selected in the layout view.	Boolean
mapFrame (Lecture et écriture)	A reference to the associated MapFrame.	MapFrame
name (Lecture et écriture)	The name of the element. It is important that all elements have a unique name so they can be easily referenced.	String
showTitle (Lecture et écriture)	A Boolean that controls whether the title is displayed in the legend.	Boolean
syncLayerOrder (Lecture et écriture)	A Boolean that controls whether the items in the legend are in the same order as the layers in the map.	Boolean
syncLayerVisibility (Lecture et écriture)	A Boolean that controls whether an item should automatically appear in the legend if it is visible in the map.	Boolean
syncNewLayer (Lecture et écriture)	A Boolean that controls whether an item should automatically be added to the legend when added to the map.	Boolean
syncReferenceScale (Lecture et écriture)	A Boolean that controls whether the symbols in the legend should match the scaling of the symbols in a map if a reference scale is set.	Boolean
title (Lecture et écriture)	The text string that represents the legend's title.	String
type (Lecture seule)	Returns a value of LEGEND_ELEMENT.	String
visible (Lecture et écriture)	Returns True if the element is visible on the layout. Rather than having to move unwanted objects off the page before printing or exporting, you can turn the element's visibility on and off.	Boolean

Vue d’ensemble des méthodes

Méthode	Explication
addItem (layer, {add_position})	Allows you to add a Layer to a legend using basic placement options.
moveItem (reference_item, move_item, {move_position})	Allows you to move a legend item to a specific location within a legend.
removeItem (remove_item)	Allows you to remove a legend item from a legend.

Méthodes

addItem (layer, {add_position})

Paramètre	Explication	Type de données
layer	A reference to a Layer object representing the layer to be added to a legend as a LegendItem.	Layer
add_position	A constant that determines the placement of the added layer within the legend. BOTTOM—Places the layer or layers at the bottom of the TOC layer stack. TOP—Places the layer or layers at the top of the TOC layer stack. (La valeur par défaut est TOP)	String

Valeur renvoyée

Type de données	Explication
LegendItem	A LegendItem object.

The addItem method allows you to add a layer to a legend on a layout. The default add_position adds the layer to the top of the list of legend items, therefore appears first. For more precise legend item placement, refer to the moveItem method.

moveItem (reference_item, move_item, {move_position})

Paramètre	Explication	Type de données
reference_item	A LegendItem object representing an existing legend item that determines the relative location where the move_item will be moved.	LegendItem
move_item	A reference to a LegendItem object representing the layer to be moved.	Layer
move_position	A constant that determines the placement of the moved layer relative to the reference layer. AFTER—Moves the legend item after or below the reference_item. BEFORE—Moves the legend item before or above the reference_item. (La valeur par défaut est BEFORE)	String

The moveItem method moves a legend item in a legend. The move_item can be moved either AFTER or BEFORE the reference_item.

removeItem (remove_item)

Paramètre	Explication	Type de données
remove_item	A reference to a LegendItem object representing the item to be removed.	LegendItem

The removeItem method removes a single legend item from a legend.

Exemple de code

LegendElement example 1

The following script will add layers to a map that includes an inserted legend element named Legend. The layers will automatically get added to the legend and its title gets updated.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyr1 = arcpy.mp.LayerFile(r"C:\Projects\Yosemite\LYRs\Trails.lyrx")
lyr2 = arcpy.mp.LayerFile(r"C:\Projects\Yosemite\LYRs\PointsOfInterest.lyrx")
m = aprx.listMaps("Yose*")[0]
m.addLayer(lyr1, "TOP")
m.addLayer(lyr2, "TOP")
lyt = aprx.listLayouts("Main Attrations")[0]
legend = lyt.listElements("LEGEND_ELEMENT", "Legend")[0]
legend.title = "Yosemite National Park"
aprx.save()
del aprx