ArcGIS Help 10.2 - TextElement (arcpy.mapping)

Summary

The TextElement object provides access to properties that enable its repositioning on the page layout as well as modifying the text string and font size.

Discussion

The TextElement object represents inserted text within a page layout. This includes items such as inserted text, callouts, rectangle text, titles, and so on. It also includes text strings that have been grouped into a group element. It does not include text strings that are part of a legend or inserted table. The ListLayoutElements function returns a Python list of page layout element objects. It is necessary to then iterate through each item in the list or specify an index number to reference a specific page element object. To return a list of TextElements only, use the TEXT_ELEMENT constant for the element_type parameter. A wildcard can also be used to further refine the search based on the element name.

Existing text elements can be cloned and deleted. This capability was initially added to support the creation of dynamic graphic tables. To accomplish this, a map document must be authored with the text elements having the appropriate symbology. If column field names have different text property settings than the cell values, then at least two text elements need to be authored. As the information is read from a table, the text can be cloned using the clone method and positioned appropriately using other text element properties. When cloning an element it is very useful to provide a suffix value so that cloned elements can be easily identified while using the ListLayoutElements function with a wildcard and the same suffix value. The returned list of elements can be further modified or deleted using the delete method.

To see a complete code sample on how to created a dynamic graphic table based on records in a feature class, see the code sample provided in the GraphicElement class help.

The TextElement is also unique from most other page elements in that it has a text property. It is with this property that strings can be read and modified. A common example is to perform a search and replace operation on all text elements in a page layout. Similar to the ArcMap user interface, the text string cannot be an empty string; it must include at least an empty space, for example, textElm.text = " ", not textElm.text = "".

It is highly recommended that each page layout element be given a unique name so that it can be easily isolated using ArcPy scripting. X and Y element positions are based on the element's anchor position, which is set via the Size and Position tab on the element's properties dialog box in ArcMap.

Properties

Property	Explanation	Data Type
angle (Read and Write)	The text baseline angle of the element in degrees.	Double
elementHeight (Read and Write)	The height of the element in page units. The units assigned or reported are in page units.	Double
elementPositionX (Read and Write)	The X location of the data frame element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Read and Write)	The Y location of the data frame 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. The units assigned or reported are in page units.	Double
fontSize (Read and Write)	The element font size in page units.	Double
name (Read and Write)	The name of the element.	String
text (Read and Write)	The text string associated with the element.	String
type (Read Only)	Returns the element type for any given page layout element. DATAFRAME_ELEMENT —Dataframe element GRAPHIC_ELEMENT —Graphic element LEGEND_ELEMENT —Legend element MAPSURROUND_ELEMENT —Mapsurround element PICTURE_ELEMENT —Picture element TEXT_ELEMENT —Text element	String

Method Overview

Method	Explanation
clone ({suffix})	Provides a mechanism to clone an existing graphic text on a page layout.
delete ()	Provides a mechanism to delete an existing text element on a page layout.

Methods

clone ({suffix})

Parameter	Explanation	Data Type
suffix	An optional string that is used to tag each newly created text element. The new element will get the same element name as the parent text element plus the suffix value plus a numeric sequencer. For example, if the parent element name is FieldLabel and the suffix value is _copy, the newly cloned elements would be named FieldLabel_copy, FieldLabel_copy_1, FieldLabel_copy_2, and so on. If a suffix is not provided, then the results would look like FieldLabel_1, FieldLabel_2, FieldLabel_3, and so on.	String

Grouped text elements can't be cloned. All grouped elements are graphic element types. First check to see if a graphic element is grouped by using the isGroup property on the GraphicElement object.

delete ()

It may be necessary to delete cloned elements. Cloned elements, when created, can be given a custom suffix so they can be easy to find when using the wildcard parameter on the ListLayoutElements function.

Code Sample

TextElement example 1

The following script will replace all occurrences of the year 2009 with the year 2010.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for elm in arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT"):
    if elm.text == "2009":
        elm.text = "2010"
mxd.save()
del mxd

TextElement example 2

The following script will update a static 9.3 map document date/time text element string to now incorporate the new version 10 dynamic text strings. Current time is appended as a new line below the current date. The text string is set using a couple of different Python techniques. All produce the same result.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
elm = arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT", "DateTimeElm")[0]

#Concatenate the date and time with a new line character (\n) using single quotes so that double quotes are treated as part of the string.
elm.text = 'Date: <dyn type="date" format="short"/> \nTime: <dyn type="time" format=""/>'

#Use triple quotes and put the line break within the string.
elm.text = """Date: <dyn type="date" format="short"/>
Time: <dyn type="time" format=""/>"""

mxd.save()
del mxd

TextElement example 3

The following script will adjust a string's font size to fit a specified page width. It essentially sets the initial font size to 100 points and reduces the font size until the text string fits the desired width. The text string is set up as dynamic text that represents the map's title information. This script will only run properly if you set the title property of the map document. This can be found under File > Map Document Properties.

import arcpy
mxd = arcpy.mapping.MapDocument("CURRENT")
elm = arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT", "MapTitle")[0]
elmWidth = 4.0
x = 100
elm.text = '<dyn type="document" property="title"/>'
elm.fontSize = x
while elm.elementWidth > float(elmWidth):
    elm.fontSize = x
    x = x - 1
arcpy.RefreshActiveView()
del mxd

3/3/2014