LegendElement

Сводка

Объект LegendElement обеспечивает доступ к свойствам и методам, которые разрешают позиционирование и изменение размеров легенды на странице компоновки, а также позволяют изменить заголовок и элементы легенды.

Описание

Так же, как и MapsurroundElement, объект LegendElement имеет связь с одним родительским фреймом данных. Кроме того, LegendElement также содержит методы и свойства для управления содержанием легенды. Они удобны для управления способом добавления новых элементов легенды, изменения размеров легенды, обновления свойств ее элементов с помощью стиля, а также для задания количества столбцов в легенде.

Функция ListLayoutElements возвращает список Python с объектами элементов компоновки страницы. Затем необходимо пройти по всем элементами списка в цикле или указать номер индекса для ссылки на определенный объект элемента страницы. Чтобы только получить список LegendElements, используйте константу LEGEND_ELEMENT с параметром element_type. Подстановочные знаки также могут использоваться для поиска по имени элемента.

Легенда на странице компоновки в интерфейсе ArcMap имеет параметр При добавлении нового слоя к карте добавлять новый пункт легенды (Add a new item to the legend when a new layer is added to the map), который позволяет автоматически обновлять легенду при добавлении или удалении слоев карты. Свойство autoAdd позволяет включить или выключить это поведение, что позволит управлять автоматическим добавлением новых слоев в легенду. Например, вы хотите добавить в слой ортофотоснимок, но не хотите, чтобы он появлялся в легенде. Прежде чем использовать функцию AddLayer, желательно задать для свойства autoAdd значение False.

Элементы легенды в интерфейсе ArcMap также имеют параметр Фиксированный фрейм. Если этот параметр включен, при добавлении большого количества элементов они могут не уместиться в выделенной области. Если это происходит, элементы, которые не поместились во фрейм, заменяются значком, который означает, что легенда переполнена. Свойство isOverflowing позволяет проверить все ли элементы поместились во фрейм, затем изменить размер легенды или изменить элементы легенды, например, применив стиль, который использует меньший размер шрифта.

Свойства removeItem и updateItem – основной метод arcpy.mapping, обеспечивающий возможность удаления элементов легенды или изменения стилей элементов. При работе с интерфейсом, когда вы добавляете новый слой в таблицу содержания и он автоматически добавляется в легенду, применяется стиль по умолчанию. Модуль arcpy.mapping позволяет обновлять отдельные стили элементов легенды с помощью LegendElement на странице компоновки. Это можно сделать, используя следующий рабочий процесс.

• Создайте собственный элемент стиля легенды с помощью Менеджера стилей (Style Manager).
• Создайте ссылку на этот элемент стиля с помощью функции ListStyleItems.
• Создайте ссылку на элемент легенды с помощью функции ListLayoutElements.
• Обновите определенный элемент стиля легенды с помощью метода updateItem класса LegendElement.

Рекомендуется присваивать каждому элементу страницы компоновки уникальное имя, чтобы их можно было легко изолировать с помощью скриптов ArcPy. Их можно задать в закладке Размер и положение (Size and Position Tab) диалогового окна Свойства (Properties) в ArcMap.

Положения X и Y элемента основаны на положении якоря элемента, который также задается на закладке Размер и положение (Size and Position Tab) диалогового окна Свойства (Properties) в ArcMap.

Единицы измерения страницы в ArcMap можно изменить с помощью Настройка (Customize) > Опции ArcMap (ArcMap Options) > закладка Вид компоновки (Layout View).

Свойства

Владение	Объяснение	Тип данных
autoAdd (чтение и запись)	Управляет опцией автоматического добавления слоя в легенду при использовании функций AddLayer или AddLayerToGroup. Это свойство имитирует опцию отметки Подключение к карте (Map Connection), обозначенную При добавлении нового слоя к карте добавлять новый пункт легенды (Add a new item to legend when a new layer is added to the map), которая находится на закладке Элемент (Item) в диалоговом окне Свойства легенды (Legend Properties).	Boolean
elementHeight (чтение и запись)	Высота элемента в единицах страницы. Единицы измерения задаются или считываются в единицах страницы.	Double
elementPositionX (чтение и запись)	Положение x якоря элемента во фрейме данных. Единицы измерения задаются или считываются в единицах страницы.	Double
elementPositionY (чтение и запись)	Положение y якоря элемента во фрейме данных. Единицы измерения задаются или считываются в единицах страницы.	Double
elementWidth (чтение и запись)	Ширина элемента в единицах страницы. Единицы измерения задаются или считываются в единицах страницы.	Double
isOverflowing (только чтение)	Возвращает значение True, если не удается разместить элементы легенды при установленной опции Фиксированный фрейм (Fixed Frame) в свойствах легенды.	Boolean
items (только чтение)	Возвращает список строк, представляющих отдельные имена элементов легенды.	String
name (чтение и запись)	Имя элемента.	String
parentDataFrameName (только чтение)	Строка, представляющая имя выходного фрейма данных для соответствующего связанного элемента.	String
title (чтение и запись)	Текстовая строка, представляющая заголовок легенды.	String
type (только чтение)	Возвращает тип любого элемента на странице компоновки. DATAFRAME_ELEMENT —Фрейм данных GRAPHIC_ELEMENT —Графический элемент LEGEND_ELEMENT —Легенда MAPSURROUND_ELEMENT —Элемент окружения карты PICTURE_ELEMENT —Рисунок TEXT_ELEMENT —Элемент Текст	String

Обзор метода

Метод	Объяснение
adjustColumnCount (column_count)	Содержит механизм, позволяющий установить число столбцов в легенде.
listLegendItemLayers ()	Возвращает список ссылок объекта Layer для каждого элемента в легенде.
removeItem (legend_item_layer, {index})	Метод removeItem позволяет удалять элемент из легенды.
updateItem (legend_item_layer, {legend_item_style_item}, {preserve_item_sizes}, {use_visible_extent}, {show_feature_count}, {use_ddp_extent}, {index})	Метод updateItem позволяет обновлять отдельные свойства элемента легенды.

Методы

adjustColumnCount (column_count)

Параметр	Объяснение	Тип данных
column_count	Целое число, отображающее необходимое количество столбцов. (Значение по умолчанию — 1)	Integer

Часто в компоновке не хватает места, чтобы вместить все элементы легенды в одном столбце. В диалоговом окне легенды можно указать высоту элементы (elementHeight) или ширину элемента (elementWidth) для определения необходимого места на странице. Для второго метода необходимо сосчитать количество элементов в легенде. В любом случае после этого можно использовать функцию adjustColumnCount для определения необходимого количества столбцов в легенде.

listLegendItemLayers ()

Значение отраженного сигнала

Тип данных	Объяснение
Layer	Список Python объектов Layer. Каждый элемент легенды ссылается на слой.

Метод listLegendItemLayers удобен для определения различных слоев, использующихся в легенде и частоты их упоминания. Объект Layer возвращается для каждого элемента, найденного в легенде. Возможно, что слой может быть указан в таблице содержания только один раз, но несколько раз указан в легенде. Оценив возвращенный список объектов Layer (по одному на каждый элемент легенды), можно определить, сколько раз встречается один слой. Если вы хотите удалить или изменить каждый из этих экземпляров, необходимо использовать значение параметра index для обоих методов removeItem и updateItem.

removeItem (legend_item_layer, {index})

Параметр	Объяснение	Тип данных
legend_item_layer	Ссылка на слой, использующийся в легенде.	Layer
index	Простой слой может быть добавлен в одну и ту же легенду несколько раз. Значение индекса позволяет ссылаться на конкретный элемент легенды. Если у вас несколько элементов и вы хотите удалить все экземпляры, необходимо будет вызвать removeItem несколько раз. По умолчанию будет удален первый элемент легенды. (Значение по умолчанию — 0)	Long

Может возникнуть необходимость удалить элемент из легенды. Например, элемент, ссылающийся на ортофотоснимок, не обязательно должен находиться в легенде. Метод removeItem позволяет удалить отдельный элемент из легенды после его автоматического добавления. Другой способ – использовать задание свойства autoAdd для легенды, что позволит управлять автоматическим добавление новых слоев в легенду.

updateItem (legend_item_layer, {legend_item_style_item}, {preserve_item_sizes}, {use_visible_extent}, {show_feature_count}, {use_ddp_extent}, {index})

Параметр	Объяснение	Тип данных
legend_item_layer	Ссылка на слой, использующийся в легенде.	Layer
legend_item_style_item	Ссылка на стиль элемента легенды, возвращаемый функцией ListStyleItems. Этот элемент берется из имени папки стиля Legend Items. (Значение по умолчанию — None)	Object
preserve_item_sizes	Булево значение, определяющее, могут ли изменяться размеры символов при изменении размера легенды. Если указано значение True (Истина), размеры, указанные в элементе стиля, будут оставаться неизменными. (Значение по умолчанию — False)	Boolean
use_visible_extent	Булево значение, определяющее, будут ли отображаться в легенде только объекты видимого экстента фрейма данных. (Значение по умолчанию — False)	Boolean
show_feature_count	Булево значение, определяющее, будет ли отображаться в легенде количество объектов. (Значение по умолчанию — False)	Boolean
use_ddp_extent	Булево значение, определяющее, будут ли отображаться в легенде только объекты индексного слоя Многостраничной компоновки. Должна быть активирована Многостраничная компоновка. (Значение по умолчанию — False)	Boolean
index	Один и тот же слой можно добавить в одну и ту же легенду несколько раз. Значение индекса позволяет ссылаться на конкретный элемент легенды. Если у вас есть несколько элементов и вы хотите удалить все экземпляры, вам нужно будет вызвать метод updateItem несколько раз. По умолчанию будет обновлен первый элемент легенды. (Значение по умолчанию — 0)	Long

Метод updateItem – основной метод arcpy.mapping, обеспечивающий возможность обновления элементов легенды и задания пользовательских параметров. При работе с интерфейсом, когда вы добавляете новый слой в таблицу содержания, и он автоматически добавляется в легенду, применяется стиль по умолчанию. Модуль arcpy.mapping позволяет обновлять отдельные элементы легенды с помощью LegendElement на странице компоновки.

Пример кода

LegendElement пример 1

Следующий скрипт добавит слои в новый фрейм данных документа карты, который содержит элемент легенды с именем Legend. Слои будут автоматически добавляться в легенду, кроме слоя orthophoto. За это отвечает свойство autoAdd. Наконец, после добавления слоев, число столбцов меняется на 2.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "New Data Frame")[0]
lyr1 = arcpy.mapping.Layer(r"C:\Project\Data\Parcels.lyr")
lyr2 = arcpy.mapping.Layer(r"C:\Project\Data\MapIndex.lyr")
lyr3 = arcpy.mapping.Layer(r"C:\Project\Data\Orthophoto.lyr")
legend = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT", "Legend")[0]
legend.autoAdd = True
arcpy.mapping.AddLayer(df, lyr1, "BOTTOM")
arcpy.mapping.AddLayer(df, lyr2, "BOTTOM")
legend.autoAdd = False
arcpy.mapping.AddLayer(df, lyr3, "BOTTOM")
legend.adjustColumnCount(2)
mxd.save()
del mxd

LegendElement пример 2

Следующий скрипт работает с элементом легенды с включенным параметром Фиксированный фрейм (Fixed Frame). Если элементы легенды переполняются, скрипт будет увеличивать высоту легенды с шагом 0.1 дюйма, пока все элементы не будут полностью отображаться.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
legendElm = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT", "Legend")[0]
while legendElm.isOverflowing:
  legendElm.elementHeight = legendElm.elementHeight + 0.1
del mxd

LegendElement пример 3

Следующий скрипт использует рабочий процесс, описанный выше, и обновляет данный элемент легенды. В первый фрейм данных документа карты добавляется слой, а элемент легенды обновляется с использованием пользовательского стиля NewDefaultLegendStyle. Пользовательский файл .style сохранен в папке профиля пользователя. Затем, скрипт проверяет легенду на переполнение, и, если это происходит, удаляет из легенды лишний слой, чтобы освободить место.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Rivers.lyr")
arcpy.mapping.AddLayer(df, lyrFile, "TOP")
lyr = arcpy.mapping.ListLayers(mxd, 'Rivers', df)[0]
styleItem = arcpy.mapping.ListStyleItems("USER_STYLE", "Legend Items", "NewDefaultLegendStyle")[0]
legend = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT")[0]
legend.updateItem(lyr, styleItem)
if legend.isOverFlowing:
  removeLyr = arcpy.mapping.ListLayers(mxd, "County Boundary")[0]
  legend.removeItem(removeLyr)
del mxd

LegendElement пример 4

Следующий скрипт обновляет все слои в легенде, чтобы использовать пользовательский элемент стиля элемента легенды с названием MyNewStyle.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
legend = arcpy.mapping.ListLayoutElements(mxd,"LEGEND_ELEMENT")[0]
styleItem = arcpy.mapping.ListStyleItems("USER_STYLE", 
                                         "Legend Items", 
                                         "MyNewStyle")[0]
for lyr in legend.listLegendItemLayers():
     legend.updateItem(lyr, styleItem)
del mxd