Summary
The GroupElement object provides access to properties for group elements in a layout.
Discussion
The listElements method on the Layout object returns a Python list of layout elements. To return a list of only GroupElement objects, use the GROUP_ELEMENT constant for the element_type parameter. A wildcard value can also be used to further refine the search based on the element's name value. It is important that each element be given a unique name so that it can be easily referenced.
Group elements can be created using the createGroupElement method on the ArcGISProject class. To create a group element, elements must exist and be added to the required element_list parameter. In other words, you cannot create an empty group element. You can create group elements inside other existing group elements.
The GroupElement object is important for many of the map graphic and layout element creation methods. Like the GroupElement object, many of the other methods have a destination container parameter, and if the value is a group element, the newly created objects will be added to the specified group element. The container parameter can be a graphics layer in a map, a Layout, or a reference to an existing GroupElement object in a layout.
Note:
You can only group elements that are at the same level in the Contents pane. For example, you can group a graphic element, a group element, and a map surround element all positioned at the root of the Contents pane into a new group but you cannot group a graphic element at the root level and another graphic element in a group.
The deleteElement method on the Layout class allows you to delete elements in a layout. To remove group elements that may exist inside other group elements, you must delete group elements in opposite order because you must delete the child groups before the parent group. See the second code example below.
Note:
Prior to version 3.2, group elements in a layout were categorized as a GraphicElement and would return a type value of GRAPHIC_ELEMENT. To maintain compatibility with older scripts, the isGroup property was carried over from the GraphicElement object. It is not necessary to use this property with newer scripts because a group element now has a type value of GROUP_ELEMENT and can be searched and referenced using the Layout listElements method with the value of GROUP_ELEMENT for the element_type pick list.
Properties
Property | Explanation | Data Type |
anchor (Read Only) | Returns one of the following string values that represent the current anchor position. To change the value, use the setAnchor method.
| String |
elementHeight (Read and Write) | The height of the element in either layout page units or map units. | Double |
elementPositionX (Read and Write) | The x-location of the element's anchor position in either layout page units or map units. | Double |
elementPositionY (Read and Write) | The y-location of the element's anchor position in either layout page units or map units. | Double |
elementRotation (Read and Write) | The element's rotation angle in degrees. Positive values rotate clockwise and negative values rotate counterclockwise. | Double |
elements (Read Only) | Returns a list of elements in the GroupElement object. | List |
elementWidth (Read and Write) | The width of the element in either layout page units or map units. | Double |
isGroup (Read Only) | Returns True if the element is a GroupElement. Refer to the discussion for additional information. | Boolean |
locked (Read and Write) | When set to True, the element cannot be graphically selected in the layout view. | Boolean |
longName (Read Only) | An element's full name including group information if it exists. For example, an element named 'Point' in a group element named 'Group Element' will return a longName value of 'Group Element\\Point'. If the element is not in a group, the longName will be the same as the name value. | String |
name (Read and Write) | The name of the element. It is important that all elements have a unique name so they can be easily referenced. | String |
parentGroupElement (Read Only) | If an element, including a GroupElement, is in a group, the value returned will be a GroupElement, otherwise a NoneType will be returned. | GroupElement |
type (Read Only) | Returns a value of GROUP_ELEMENT. | String |
visible (Read and Write) | Returns True if the element is visible. | Boolean |
Method Overview
Method | Explanation |
getDefinition (cim_version) | Returns a graphic element's CIM definition. |
setAnchor (anchor) | The setAnchor method controls the anchor position for a GroupElement value. |
setDefinition (definition_object) | Sets a group element's CIM definition. |
ungroupElements () | The ungroupElements method separates all elements in the group element. |
Methods
getDefinition (cim_version)
Parameter | Explanation | Data Type |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
Data Type | Explanation |
Object | Returns the CIM definition for a GraphicElement. |
For more information about working with the CIM and samples, see Python CIM access.
setAnchor (anchor)
Parameter | Explanation | Data Type |
anchor | A string that specifies the location of the anchor position.
| String |
Setting the anchor position is helpful because you can control how the element might expand when resized. For example, the default anchor position for a group element is BOTTOM_LEFT_CORNER. If you change the anchor location to TOP_RIGHT_CORNER, changing elementHeight will expand the element downward instead of upward (the default), and changing elementWidth will expand the element to the left.
setDefinition (definition_object)
Parameter | Explanation | Data Type |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
For more information about working with the CIM and samples, see Python CIM access.
ungroupElements ()
The elements are separated into the parentGroup value of the GroupElement value and the group element is removed. If no parent group exists, the elements are placed at the root level of the layout.
Code sample
The following script groups all GraphicElement objects into one group and all TextElement objects into a second group. Then both resulting group elements are grouped into a third, parent group. At the start of the script, all elements are at the root level of the Contents pane.
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
#Group graphic elements
graElmList = []
for gra in lyt.listElements('GRAPHIC_ELEMENT'):
graElmList.append(gra)
graphics = p.createGroupElement(lyt, graElmList, 'Graphic Elements')
#Group text elements
txtElmList = []
for txt in lyt.listElements('TEXT_ELEMENT'):
txtElmList.append(txt)
text = p.createGroupElement(lyt, txtElmList, 'Text Elements')
#Group of groups
supGrp = p.createGroupElement(lyt, [graphics, text], 'Group of Groups')
The following script deletes all elements on a layout. If group elements exist inside other group elements, is important to remove group elements in reverse order because the child groups need to be removed before the parent groups.
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
# delete all the group elements and their children in reverse order
for elm in reversed(lyt.listElements('GROUP_ELEMENT')):
lyt.deleteElement(elm)
# delete remaining elements
for elm in lyt.listElements():
lyt.deleteElement(elm)