Using the SymbologyControl

The SymbologyControl is used to display the contents of server style files (*.ServerStyle) and custom symbology. The symbology can be used to update part of an application, such as a layer's renderer or an element's symbol.

Server Styles are collections of symbols and map elements that are often grouped by functionality. For example, symbols and map elements used by the transportation industry maybe grouped into Transportation Server Style.

Server Styles are stored in files that have a .ServerStyle extension. ESRI provides several styles for you to use out of the box. These styles are found under \ArcGIS\Styles. You will find commonly used symbols and map elements in ESRI.ServerStyle, and more domain specific style items in relevantly named .ServerStyle files (for example, Transportation.ServerStyle).

A style is composed of several style items. These style items provide access to individual map elements and symbols. Style items are organized into style classes, which are types of style items. A style class may have several groups of items organized into categories. For example, Precipitation is style item that belongs to the Color Ramps style class and the Default Ramps category.

Server Style files can be loaded at design-time through the SymbologyControl property pages (in development environments that support property page capability) and the SymbologyControl can be set to "link" or "contain" the symbology. When linking, the SymbologyControl will read the Server Style files whenever the SymbologyControl is created on the container. When containing, the SymbologyControl will copy the contents of the Server Style file into the SymbologyControl. Containing increases the size of the application executable containing the SymbologyControl.

Alternatively, Server Style files can be loaded into the SymbologyControl programmatically using the LoadStyleFile method, and removed using the RemoveFile method.

The SymbologyControl displays the contents of one SymbologyStyleClass at any one time (for example, marker symbols or north arrow symbols). Use the ISymbologyControl::StyleClass property to set the current SymbologyStyleClass and the ISymbologyControl::GetStyleClass method to return a specific SymbologyStyleClass. The ISymbologyStyleClass interface has properties and methods for managing each ServerStyleGalleryItem within a SymbologyStyleClass. Individual items can be removed, selected and previewed using the RemoveItem, SelectItem and PreviewItem methods. Custom symbology can be added using the AddItem method.

When the contents of a server style file is loaded into the SymbologyControl with the LoadStyleFile method, items are 'demand loaded' to the end of a SymbologyStyleClass item collection. This is done to increase performance and means items are only loaded into a SymbologyStyleClass when it is the current ISymbologyControl::StyleClass. To increase the speed that items display themselves within the SymbologyControl, the Update method can be used to force items to be loaded into a SymbologyStyleClass, when it is not the current ISymbologyControl::StyleClass.