LabelClass

Summary

Provides access to a layer's label class properties

Discussion

The LabelClass object is essential for managing properties, such as label expressions or SQL queries, that are associated with a layer's individual label classes.

Access to these properties is essential when, for example, a map document's layers are redirected to a new workspace. The label classes' SQL query may need to be updated with the appropriate syntax for the new database it is being executed against. For example, field names in a personal geodatabase are surrounded by square brackets while field names in the file geodatabase are surrounded with double quotes. In addition to field names, other SQL properties (wildcard characters, other special characters, operators, and so on) may need to be changed as well. If the SQL query is not updated, layers may fail to draw. For more information on these special cases, refer to the Updating and fixing data sources within arcpy.mapping topic.

The label expression is either using the VBScript or JScript parsers. The syntax and/or special characters for the parsers should not change (for example, VBScript always uses square brackets), but realize that the field names may change. Area and perimeter are commonly used fields in an expression, and these do vary in name from data source to data source.

Not all layers support the labelClasses property, so it is useful to test this ahead of time using the supports method—for example, layer.supports("SHOWLABELS") or layer.supports("LABELCLASSES"). If a layer supports labels, it also will support the labelClasses property, so you don't need to test for both.

The labelClasses property will return a list of LabelClass objects. To reference a specific LabelClass object, it will be necessary to loop through each item in the list or provide a specific index number.

Properties

Property	Explanation	Data Type
className (Read and Write)	Provides the ability to get or set a layer's individual label class name.	String
expression (Read and Write)	Provides the ability to get or set a layer's individual label class expression. This can be as simple as a single field or more advanced using either a VBScript or JScript expression.	String
SQLQuery (Read and Write)	Provides the ability to get or set a layer's individual label class SQLQuery. This is useful for restricting labels to certain features.	String
showClassLabels (Read and Write)	Provides the ability get or set the visibility of individual label classes.	Boolean

Code Sample

LabelClass example 1

The following script will print the label class properties for only those layers that have labels and individual label classes turned on. The script first confirms that the layer supports the labelClasses property.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for lyr in arcpy.mapping.ListLayers(mxd):
    if lyr.supports("LABELCLASSES"):
        if lyr.showLabels:
            print "Layer name: " + lyr.name
            for lblClass in lyr.labelClasses:
                if lblClass.showClassLabels:
                    print "    Class Name:  " + lblClass.className
                    print "    Expression:  " + lblClass.expression
                    print "    SQL Query:   " + lblClass.SQLQuery
del mxd

LabelClass example 2

The following script will modify the SQL query that once pointed to a personal geodatabase, but now its layer references a file geodatabase. Square brackets will be changed to double quotes and the wildcard character will be modified from an asterisk (*) to a percent symbol (%). A new output map document is saved, preserving the original map document.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for lyr in arcpy.mapping.ListLayers(mxd):
    if lyr.supports("LABELCLASSES"):
        for lblClass in lyr.labelClasses:
            lblClass.SQLQuery = lblClass.SQLQuery.replace("[", "\"")
            lblClass.SQLQuery = lblClass.SQLQuery.replace("]", "\"")
            lblClass.SQLQuery = lblClass.SQLQuery.replace("*", "%")
mxd.saveACopy("c:/project/project2.mxd")
del mxd