Summary
Returns a Python list of StyleItem objects. A referenced legend item from a style file (.style or .ServerStyle) can then be used to update already existing legend items in a layout.
Discussion
In ArcGIS Desktop, style items are stored in a .style file. In ArcGIS Server, style items are stored in a .ServerStyle file. Style items in a .style file can be viewed and managed in the Style manager window. Style files are organized into different subfolders with unique names, for example, Marker Symbols or Legend Items. Currently, the only style items that can be used with other arcpy.mapping methods are legend items. Legend items define how a layer appears in a legend. For example, they store information such as legend arrangement, layer name symbol, and default override patch.
Style items are exposed to the arcpy.mapping API so that users can control the appearance of legend item style 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, and then use its updateItem method. An example of this workflow is provided as a code sample below.
Syntax
ListStyleItems (style_file_path, style_folder_name, {wildcard})| 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 the name of the ArcGIS system style file, for example, "ESRI.style" or "ESRI.ServerStyle" or "Transportation.style". The function will automatically search for the style in the appropriate ArcGIS installation style folder. Second, with ArcGIS Desktop installations, you can use the keyword "USER_STYLE". This will automatically search the local user profile rather than requiring 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 named 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