TableFrameElement

Synthèse

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 theTableFrameElement 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.

Propriétés

PropriétéExplicationType de données
anchor
(Lecture seule)

Returns one of the following string values that represent the current anchor position. To change the value, use the setAnchor method.

  • BOTTOM_LEFT_CORNERBottom left corner position
  • BOTTOM_MID_POINTBottom center position
  • BOTTOM_RIGHT_CORNERBottom right corner position
  • CENTER_POINTCenter position
  • LEFT_MID_POINTLeft center position
  • RIGHT_MID_POINTRight center position
  • TOP_LEFT_CORNERTop left corner position
  • TOP_MID_POINTTop center position
  • TOP_RIGHT_CORNERTop right corner position
String
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
elementWidth
(Lecture et écriture)

The width of the element in page units.

Double
fields
(Lecture et écriture)

A list of strings that represent the table field names that are displayed in the table frame.

List
locked
(Lecture et écriture)

When set to True, the element cannot be graphically selected in the layout view.

Boolean
longName
(Lecture seule)

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
(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 uniquely referenced using the wildcard parameter with the listElements function on the Layout object.

String
parentGroupElement
(Lecture seule)

If the element is in a group, the value returned will be a GroupElement, otherwise a NoneType will be returned.

GroupElement
query
(Lecture seule)

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_ROWSDisplay all rows in the table.
  • MAPSERIES_ROWSDisplay the row associated with the current index feature if a spatial map series is enabled.
  • VISIBLE_ROWSDisplay only the visible features in the map frame.
String
table
(Lecture et écriture)

The Layer or Table object associated with the table frame.

Object
type
(Lecture seule)

Returns a value of TABLEFRAME_ELEMENT.

String
visible
(Lecture et écriture)

Returns True if the element is visible on the layout.

Boolean

Vue d’ensemble des méthodes

MéthodeExplication
applyStyleItem (style_item)

Applies a StyleItem to a TableFrameElement.

getDefinition (cim_version)

Returns a table frame element's CIM definition.

setAnchor (anchor)

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

setDefinition (definition_object)

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

setQuery (query_rows)

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

sortFields (field_info)

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

Méthodes

applyStyleItem (style_item)
ParamètreExplicationType de données
style_item

A reference to a StyleItem in a project.

StyleItem

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.

Remarque :

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.

getDefinition (cim_version)
ParamètreExplicationType de données
cim_version

A string that represents the major version of the CIM that will be used.

  • V2The 2.x version of the CIM will be used.
  • V3The 3.x version of the CIM will be used.
String
Valeur renvoyée
Type de donnéesExplication
Object

Returns the CIM definition for a TableFrameElement value.

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

setAnchor (anchor)
ParamètreExplicationType de données
anchor

A string that specifies the location of the anchor position.

  • BOTTOM_LEFT_CORNERThe anchor will be set at the bottom left corner position.
  • BOTTOM_MID_POINTThe anchor will be set at the bottom center position.
  • BOTTOM_RIGHT_CORNERThe anchor will be set at the bottom right corner position.
  • CENTER_POINTThe anchor will be set at the center position.
  • LEFT_MID_POINTThe anchor will be set at the left center position.
  • RIGHT_MID_POINTThe anchor will be set at the right center position.
  • TOP_LEFT_CORNERThe anchor will be set at the top left corner position.
  • TOP_MID_POINTThe anchor will be set at the top center position.
  • TOP_RIGHT_CORNERThe 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 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.

setDefinition (definition_object)
ParamètreExplicationType de données
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.

setQuery (query_rows)
ParamètreExplicationType de données
query_rows

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

  • ALL_ROWSAll rows in the table will be displayed.
  • MAPSERIES_ROWSThe row associated with the current index feature will be displayed if a spatial map series is enabled.
  • VISIBLE_ROWSOnly the visible features in the map frame will be displayed.

(La valeur par défaut est ALL_ROWS)

String

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.

sortFields (field_info)
ParamètreExplicationType de données
field_info
[field_info,...]

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

  • nameA string that represents the name of the field used to sort.
  • ascendingA Boolean value of True will sort in ascending order. The default value is True.
  • caseSensitiveA Boolean value of True will honor case while sorting. The default value is True.
List

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.

Exemple de code

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