GroupElement

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. BOTTOM_LEFT_CORNER—Bottom left corner position BOTTOM_MID_POINT—Bottom center position BOTTOM_RIGHT_CORNER—Bottom right corner position CENTER_POINT—Center position LEFT_MID_POINT—Left center position RIGHT_MID_POINT—Right center position TOP_LEFT_CORNER—Top left corner position TOP_MID_POINT—Top center position TOP_RIGHT_CORNER—Top right corner position	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. V2—The 2.x version of the CIM will be used. V3—The 3.x version of the CIM will be used.	String

Return Value

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. BOTTOM_LEFT_CORNER—The anchor will be set at the bottom left corner position. BOTTOM_MID_POINT—The anchor will be set at the bottom center position. BOTTOM_RIGHT_CORNER—The anchor will be set at the bottom right corner position. CENTER_POINT—The anchor will be set at the center position. LEFT_MID_POINT—The anchor will be set at the left center position. RIGHT_MID_POINT—The anchor will be set at the right center position. TOP_LEFT_CORNER—The anchor will be set at the top left corner position. TOP_MID_POINT—The anchor will be set at the top center position. TOP_RIGHT_CORNER—The anchor will be set at the top right corner 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

GroupElement example 1

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')

GroupElement example 2

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)