TableFrameElement

Summary

The TableFrameElement class provides access to capabilities that allow you to modify how tabular information is displayed on the Layout class.

Discussion

A table frame element is a specialized map surround that has an associated MapFrame element and is also dynamically linked to a Layer or Table object to display its rows and fields. The listElements method on the Layout class returns a Python list of all possible layout elements. To return a list of only TableFrameElement objects, use the TABLEFRAME_ELEMENT constant for the element_type parameter. A wildcard value can also be used to further refine the search based on the element name value. It is important to uniquely name each layout element so it can be referenced using ArcPy scripting.

All the parameters that are available to the createTableFrameElement method of the Layout class are also exposed on the TableFrameElement class—such as mapframe, table, and fields—making changes to existing table frames possible. There are a number properties you can use to resize and position a table frame. You can also modify the appearance of a table frame using the sortFields method or control the rows that appear in the table using the setQuery method. Table frame elements also have getDefinition and setDefinition methods you can use to modify additional properties that are not exposed to the TableFrameElement class. Refer to the examples below and the Python CIM access help topic for more information.

Properties

Name	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 page units.	Double
elementPositionX (Read and Write)	The x-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Read and Write)	The y-location of the element's anchor position. The units assigned or reported are in page units.	Double
elementWidth (Read and Write)	The width of the element in page units.	Double
fields (Read and Write)	A list of strings that represent the table field names that are displayed in the table frame.	List
isOverflowing (Read only)	Returns `True` if everything in the table frame does not fit within the boundaries of the geometry provided. This is typically displayed with red ellipsis on a layout. The property works well within the context of a `while` loop. It gives you an opportunity to change the font size or the size of the element until everything fits.	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 '`Table Frame`' in a group element named '`Group Element`' will return a `longName` value of '`Group Element\\Table Frame`'. If the element is not in a group, the `longName` will be the same as the `name` value.	String
mapFrame (Read and Write)	A reference to the associated `MapFrame`.	MapFrame
name (Read and Write)	The name of the element. It is important that all elements have a unique name so they can be uniquely referenced using the `wildcard` parameter with the `listElements` function on the `Layout` object.	String
parentGroupElement (Read only)	If the element is in a group, the value returned will be a `GroupElement`, otherwise a `NoneType` will be returned.	GroupElement
query (Read only)	Returns one of the following string values that represent the current query that controls which rows should be displayed.. To change the value, use the `setQuery` method. ALL_ROWS—Display all rows in the table. MAPSERIES_ROWS—Display the row associated with the current index feature if a spatial map series is enabled. VISIBLE_ROWS—Display only the visible features in the map frame.	String
table (Read and Write)	The `Layer` or `Table` object associated with the table frame.	Object
type (Read only)	Returns a value of `TABLEFRAME_ELEMENT`.	String
visible (Read and Write)	Returns `True` if the element is visible on the layout.	Boolean

Methods

`applyStyleItem(style_item)`

Applies a StyleItem to a TableFrameElement.

When referencing a StyleItem using the listStyleItems method on the ArcGISProject class, the style_class parameter must be TABLE_FRAME. For more information and code samples, refer the to StyleItem help topic.

Note:

Styles must be added to a project prior to using the applyStyleItem method. They can be added using the updateStyles method on the ArcGISProject class.

Name	Explanation	Data type
style_item	A reference to a `StyleItem` in a project.	StyleItem

`getDefinition(cim_version)`

Returns a table frame element's CIM definition.

For more information about working with the CIM and samples, see Python CIM access.

Name	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

Name

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 `TableFrameElement` value.

`setAnchor(anchor)`

The setAnchor method controls the anchor position for a TableFrameElement value.

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 table frame element is TOP_LEFT_CORNER. If you change the anchor location to BOTTOM_RIGHT_CORNER, changing elementHeight will expand the element upward instead of downward (the default), and changing elementWidth will expand the element to the left.

Name	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

Name

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

`setDefinition(definition_object)`

The setDefinition method sets the CIM definition for a table frame element.

For more information about working with the CIM and samples, see Python CIM access.

Name	Explanation	Data type
definition_object	A modified CIM definition object originally retrieved using `getDefinition`.	Object

`setQuery(query_rows)`

The setQuery method controls the display of rows in the table frame.

The default value is ALL_ROWS when creating a table frame. If you use the MAPSERIES_ROWS value, ensure that the Layout object has a spatial MapSeries value enabled; otherwise, you may not get the expected results.

Name	Explanation	Data type
query_rows	A keyword string that serves as a filter and specifies the rows that will be displayed in the table frame. ALL_ROWS—All rows in the table will be displayed. MAPSERIES_ROWS—The row associated with the current index feature will be displayed if a spatial map series is enabled. VISIBLE_ROWS—Only the visible features in the map frame will be displayed. The default value is ALL_ROWS.	String

Name

Explanation

Data type

query_rows

A keyword string that serves as a filter and specifies the rows that will be displayed in the table frame.

ALL_ROWS—All rows in the table will be displayed.
MAPSERIES_ROWS—The row associated with the current index feature will be displayed if a spatial map series is enabled.
VISIBLE_ROWS—Only the visible features in the map frame will be displayed.

The default value is ALL_ROWS.

String

`sortFields(field_info[field_info,...])`

The sortFields method sorts a table frame using a list of dictionary key-value pairs for one or many fields.

Sorting applies to all fields at once and is based on the order of the fields defined in the field_info list. You must re-create all the sorting information for all the relevant fields and pass that information into the field_info parameter.

Name Explanation Data type

Name	Explanation	Data type
field_info[field_info,...]	A list of Python dictionaries that each contain field sorting information. The dictionary keys are defined below. name—A string that represents the name of the field used to sort. ascending—A Boolean value of `True` will sort in ascending order. The default value is `True`. caseSensitive—A Boolean value of `True` will honor case while sorting. The default value is `True`.	List

field_info[field_info,...]

A list of Python dictionaries that each contain field sorting information. The dictionary keys are defined below.

name—A string that represents the name of the field used to sort.
ascending—A Boolean value of True will sort in ascending order. The default value is True.
caseSensitive—A Boolean value of True will honor case while sorting. The default value is True.

List

Code sample

TableFrameElement example 1

The following script creates a table frame in a layout. Its uses a function to construct the envelop used to place the table frame on the layout.

def MakeRec_UL(ulx, uly, w, h):
    xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rect = arcpy.Polygon(array)
    return rect

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps('Map')[0]
lyr = m.listLayers('States*')[0]
lyt = p.listLayouts('Create*')[0]
mf = lyt.listElements()[0]

#States table frame
tfStyle = p.listStyleItems('ArcGIS 2D', 'TABLE_FRAME', 'Blue Alternating Rows')[0]
tfEnv = MakeRec_UL(0.5, 5, 7.5, 4)
tfFields = ['STATE_NAME', 'STATE_ABBR', 'POP2000', 'POP2010']
tf = lyt.createTableFrameElement(tfEnv, mf, lyr, tfFields, tfStyle, 'States TableFrame')

#Display only visible rows
tf.setQuery('VISIBLE_ROWS')

TableFrameElement example 2

The following script references an existing table frame and uses class methods to modify its appearance. The script makes additional changes to properties that are exposed via Python CIM access.

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Modify*')[0]
tf = lyt.listElements('TABLEFRAME_ELEMENT', 'States*')[0]

#Modify table frame
tf.setQuery('VISIBLE_ROWS')
tf.sort({'name':'STATE_NAME', 'ascending':True, 'caseSensitive':True})

#Modify additional properties using the CIM
tf_cim = tf.getDefinition('V3')
tf_cim.minFontSize = 8
tf_cim.alternate1RowBackgroundCount = 2
tf_cim.alternate2RowBackgroundCount = 2
tf_cim.balanceColumns = False
tf_cim.columnGap = 75
tf_cim.fittingStrategy = 'AdjustColumnsAndSize'
tf.setDefinition(tf_cim)

TableFrameElement example 3

The following script creates a spatial map series prior to creating a new table frame. It finishes by setting the query value to MAPSERIES_ROWS.

def MakeRec_UL(ulx, uly, w, h):
    xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rect = arcpy.Polygon(array)
    return rect

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps('Map')[0]
lyr = m.listLayers('GreatLakes')[0]
lyt = p.listLayouts('MapSeries')[0]
mf = lyt.listElements()[0]

#Create a spatial map series
lyt.createSpatialMapSeries(mf, lyr, 'NAME', 'AREA')

#Create a table frame
tfStyle = p.listStyleItems('ArcGIS 2D', 'TABLE_FRAME', 'Orange Alternating Rows')[0]
tfEnv = MakeRec_UL(0.5, 5.75, 7.5, 2)
tf = lyt.createTableFrameElement(tfEnv, mf, lyr, ['NAME', 'AREA'], tfStyle, 'Great Lakes TableFrame')

#Set the query to match mapseries rows
tf.setQuery('MAPSERIES_ROWS')