StyleItem

Summary

The StyleItem object provides access to properties and methods for styling elements.

Discussion

The symbols you use to display features or graphic elements in a map or layout are stored in style files (.stylx). You use the Catalog ribbon associated with the Catalog view to create, view, and modify styles and their contents. A system style is organized into unique names such as ArcGIS 2D, ArcGIS 3D, and so on, as well as a personal style named Favorites. A style contains style items that are organized by styleClass values, for example, Point symbol, Legend, and Scale bar. A custom style value is a .stylx file that has a folder path and a file name ending in .stylx. Custom styles must be loaded and saved with a project before they can be referenced. They are referenced by passing in their full path and file name.

The StyleItem class allows you to create elements in a layout and in a graphics layer in a map. To reference an existing style item, use the listSytleItems method on the ArcGISProject class and specify the appropriate style_class value for the type of element you're creating. Optionally, wildcard and key values can be used to filter the search. After a list of style items is returned, you can further refine the search by testing the values of the category and tags properties. The following methods accept a styleItem value as a parameter:

The createMapSurround and createTableFrameElement methods on the Layout class.
The createGraphicElement, createPredefinedGraphicElement, and createTextElement methods on the ArcGISProject class.

Note:

Styles must be present in a project in order to use the individual style items when creating a new layout element, for example. The updateStyles method on the ArcGISProject object allows you to add styles to a project. Refer to the samples below for ensuring the styles are present in the project.

Properties

Name	Explanation	Data type
category (Read only)	Returns a string that represents the category of the item. If a value does not exist, it will return an empty string.	String
key (Read only)	Returns a string that represents the unique key identifier for the item. If a value does not exist, it will return an empty string.	String
name (Read only)	Returns a string that represents the name of the item the way it appears in the Symbol gallery or in the Catalog View.	String
style (Read only)	Returns a string that represents either a system style name such as ArcGIS 2D, a personal style such as Favorites, or a custom `.stylx` file. Note: Styles must already be added to the project before they can be referenced using `listStyleItems`. To reference a custom `.stylx` file, use the name that appears in the application. This can be viewed using the Catalog Pane.	String
style_class (Read only)	Returns a string that represents the style class of the item the way it appears in the Catalog View. The currently supported string values are: AREA_LEGEND_PATCH COLOR COLORRAMP DIMENSION_STYLE GRID LEGEND LEGEND_ITEM LINE LINE_LEGEND_PATCH MAPLEX_LABEL_PLACEMENT MAP_SURROUND MESH_SYMBOL NORTH_ARROW POINT POLYGON SCALE_BAR STANDARD_LABEL_PLACEMENT TABLE_FRAME TABLE_FRAME_FIELD TEXT For a more complete description of each style class, refer the Manage Styles help topic.	String
tags (Read only)	Returns a string that represents the tags associated with the item. If a value does not exist, it will return an empty string.	String

Code sample

StyleItem example 1

The following script demonstrates using the listStyleItems method in a number of ways.

p = arcpy.mp.ArcGISProject('current')

#Print the point symbol names for all arrow related items in ArcGIS 2D
for styleItem in p.listStyleItems('ArcGIS 2D', 'POINT', 'Arrow*'):
    print(f'StyleItem Name: {styleItem.name}')

#Print polygon symbol names for ArcGIS 2D items from a category called shapes
for styleItem in p.listStyleItems('ArcGIS 2D', 'POLYGON'):
    if styleItem.category == 'Shapes':
        print(f'StyleItem Name: {styleItem.name}')

#Print all symbol names for a few style classes in a custom style belonging to a category
for styleClass in ['Point', 'Line', 'Polygon']:
    print(f'Style Class:{styleClass}\n')

    customStylePath = r'C:\Projects\MyOwnStyleFile.stylx'
    for styleItem in p.listStyleItems(customStylePath, styleClass):
        if styleItem.category == 'Capitol Forest':
            print(f'    StyleItem Name: {styleItem.name}')
    print('\n')

StyleItem example 2

The following script creates a layout, map, map frame, and three map surrounds using the system ArcGIS 2D style, the system Favorites style and a custom style file. The script also adds the custom style if it is not already present in the project.

def MakeRec_LL(llx, lly, w, h):
    xyRecList = [[llx, lly], [llx, lly+h], [llx+w,lly+h], [llx+w,lly], [llx,lly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rec = arcpy.Polygon(array)
    return rec

p = arcpy.mp.ArcGISProject('current')

#Create a layout, map and mapframe
m = p.createMap('New Map', 'Map')
lyt = p.createLayout(8.5, 11, 'INCH', 'New Layout')
mf = lyt.createMapFrame(MakeRec_LL(0.5,5.5,7.5,5), m, "New Map Frame")
lyt.openView()

#Create scale bar using the system 'ArcGIS 2D' style
sbKeyVal = 'Double Alternating Scale Bar 1 Metric_Metric_8'
sbStyItm = p.listStyleItems('ArcGIS 2D', 'SCALE_BAR', key=sbKeyVal)[0]
sbEnv = MakeRec_LL(0.5, 5.5, 2.5, 0.5)
sb = lyt.createMapSurroundElement(sbEnv, 'Scale_bar', mf, sbStyItm)

#Create north arrow using the system 'Favorites' style
try:
    naStyItem = p.listStyleItems('Favorites', 'North_Arrow', 'Compass North 1')[0]
except:
    print('Error: A style item was not properly referenced, exiting script.')
    arcpy.AddError('Error: A style item was not properly referenced, exiting script.')
    exit()
lyt.createMapSurroundElement(arcpy.Point(7,7), 'North_Arrow', mf, naStyItem)

#Create a legend using a custom stylx file but first ensure it is added to the project
customStylePath = r'C:\Projects\MyOwnStyleFile.stylx'
styleItemList = p.styles
if not customStylePath in styleItemList:
    styleItemList.append(customStylePath)
    p.updateStyles(styleItemList)
try:
    legStyItm = p.listStyleItems(customStylePath, 'LEGEND', key='*Legend 2*')[0]
except:
    print('Error: A style item was not properly referenced, exiting script.')
    arcpy.AddError('Error: A style item was not properly referenced, exiting script.')
    exit()
lyt.createMapSurroundElement(arcpy.Point(0.5, 5), 'Legend', mf, legStyItm)

StyleItem example 3

The following script is similar to the previous sample but this time uses the applyStyleItem method to apply different style items to the same, existing layout elements.

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('New Layout')[0]

#Modify the scale bar using the system 'ArcGIS 2D' style
sbKeyVal = 'Alternating Scale Bar 1 Metric*'
sbStyItm = p.listStyleItems('ArcGIS 2D', 'SCALE_BAR', key=sbKeyVal)[0]
sb = lyt.listElements('MAPSURROUND_ELEMENT', 'Scale Bar')[0]
sb.applyStyleItem(sbStyItm)

#Modify the north arrow using the system 'Favorites' style
try:
    naStyItem = p.listStyleItems('Favorites', 'North_Arrow', wildcard = 'ArcGIS North 10')[0]
except:
    print('Error: A style item was not properly referenced, exiting script.')
    arcpy.AddError('Error: A style item was not properly referenced, exiting script.')
    exit()
na = lyt.listElements('MAPSURROUND_ELEMENT', 'North Arrow')[0]
na.applyStyleItem(naStyItem)

#Modify a legend using a custom stylx file but make sure it is added to the project first
customStylePath = r'C:\Projects\MyOwnStyleFile.stylx'
styleItemList = p.styles
if not customStylePath in styleItemList:
    styleItemList.append(customStylePath)
    p.updateStyles(styleItemList)
try:
    legStyItm = p.listStyleItems(customStylePath, 'LEGEND', key='*Legend 1*')[0]
except:
    print('Error: A style item was not properly referenced, exiting script.')
    arcpy.AddError('Error: A style item was properly not referenced, exiting script.')
    exit()
leg = lyt.listElements('LEGEND_ELEMENT', 'Legend')[0]
leg.applyStyleItem(legStyItm)