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. They are referenced by passing in their full path and file name, not just their name as with system styles.

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. A wildcard value can be used to refine the search. 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 method on the Layout class.
• The createGraphicElement, createPredefinedGraphicElement, and createTextElement methods on the ArcGISProject class.

Properties

Property	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
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. Currently supported classes are: LEGEND—For creating or modifying legend elements. LINE—For creating or modifying polyline graphic elements. NORTH_ARROW—For creating or modifying north arrow map surround elements. POINT—For creating or modifying point graphic elements. POLYGON—For creating or modifying polygon graphic elements. SCALE_BAR—For creating or modifying scale bar map surround elements TEXT—For creating or modifying text graphic elements.	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 catagory 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.

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
sbName = 'Double Alternating Scale Bar 1 Metric'
sbStyItm = p.listStyleItems('ArcGIS 2D', 'SCALE_BAR', sbName)[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
naStyItem = p.listStyleItems('Favorites', 'North_Arrow', 'Compass North 1')[0]
lyt.createMapSurroundElement(arcpy.Point(7,7), 'North_Arrow', mf, naStyItem)
                      
#Create a legend using a custom stylx file
customStylePath = r'C:\Projects\MyOwnStyleFile.stylx'
legStyItm = p.listStyleItems(customStylePath, 'LEGEND', 'Legend 2')[0]
lyt.createMapSurroundElement(arcpy.Point(0.5, 5), 'Legend', mf, legStyItm)