ListStyleItems (arcpy.mapping)
Summary
Returns a Python list of StyleItem objects. A referenced legend item from a style file (.style) can then be used to update already existing legend items in a layout.
Discussion
Style items can be viewed and managed in the Style manager window. Styles items are stored in a (.style) file and are organized into different subfolders with unique names, for example, Marker Symbols or Legend Items. Currently, the only style item that can be used with other arcpy.mapping methods are Legend Items. Legend items define how a layer appears in a legend. For example, it stores information such as legend arrangement, layer name symbol, default override patch, and so on.
Style items are exposed to the arcpy.mapping API so that users can control the appearance of legend item styles items. A common requirement is to be able to control the default font size or font type for newly added legend items. To accomplish this, you must first author a custom legend item and then reference it with the ListStyleItems function. Next, you would reference the appropriate Layer that appears in a Legend, then use its updateItem method. An example of this workflow is provided as a code sample below.
Syntax
| Parameter | Explanation | Data Type |
style_file_path |
A full path to an existing style (.style) or server style (.serverstyle) file. There are two additional shortcuts that don't require a full path. First, type in the name of the ArcGIS system style file, for example, "ESRI.style" or "Transportation.style". The function will automatically search for the style in the appropriate ArcGIS installation style folder. Second, with ArcGIS for Desktop installations, you can use the keyword "USER_STYLE". This will automatically search the local user profile rather than having to type in the full path. If the style file does not exist in either of these two known system locations, then the full path including the file extension must be provided, for example, "C:\Project\CustomStyles.style". | String |
style_folder_name |
The name of the style folder in the style file the way it appears in the Style manager window. Currently, only Legend Items can be used with other arcpy.mapping methods. | String |
wildcard |
A combination of asterisks (*) and characters can be used to help limit the results based on the style item name property. (The default value is None) | String |
Code Sample
The following script uses the workflow outlined above and updates a legend's legend item style item. A layer is added to the first data frame in the map document and the legend item style item will be updated with a custom legend item style item called NewDefaultLegendStyle. The custom .style file is saved in the user's profile location.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Rivers.lyr")
arcpy.mapping.AddLayer(df, lyrFile, "TOP")
styleItem = arcpy.mapping.ListStyleItems("USER_STYLE", "Legend Items", "NewDefaultLegendStyle")[0]
lyr = arcpy.mapping.ListLayers(mxd, 'Rivers', df)[0]
legend = arcpy.mapping.ListLayoutElements(mxd, "LEGEND_ELEMENT")[0]
legend.updateItem(lyr, styleItem)
del mxd