TextElement

Summary

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

Discussion

The TextElement object represents inserted text within a page layout. This includes items like inserted text, callouts, rectangle text, titles, and so on. It even 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 only TextElements, use the TEXT_ELEMENT constant for the element_type parameter. A wild card can also be used to further refine the search based on the element name.

The TextElement is 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.

It is 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
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
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

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")
elmWidth = 4.0
elmText = '<dyn type="document" property="title"/>'
elm = arcpy.mapping.ListLayoutElements(mxd, "TEXT_ELEMENT", "MapTitle")[0]
x = 100
elm.text = '<FNT name="Arial" size="' + str(x) + '">' + elmText + '</FNT>'
while elm.elementWidth > float(elmWidth):
    elm.text = '<FNT name="Arial" size="' + str(x) + '">' + elmText + '</FNT>'
    x = x - 1
arcpy.RefreshActiveView()
del mxd