About using the SymbologyControl
The SymbologyControl is used to display the contents of server style files (*.ServerStyle) and custom symbology. If ArcGIS for Desktop is installed, the contents of style files (*.Style) can be displayed also. The SymbologyControl enables an end user to select an individual symbol that can be applied to part of an application, such as a layer's renderer or an element's symbol. See the following screen shot:
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 can be grouped into a 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 <install_location>\ArcGIS\<EngineVersion>\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 can have several groups of items organized into categories. For example, Precipitation is a style item that belongs to the Color Ramps style class and the Default Ramps category. See the following screen shot:
A style file is similar to a server style file, except it has a .Style extension rather than a .ServerStyle extension. Style files are available to ArcGIS for Desktop products only; server style files are available to all ArcGIS products.
Server style files can be loaded at design time through the SymbologyControl property pages (in development environments that support property page capability). Using a linking mechanism, the SymbologyControl reads the server style files whenever the SymbologyControl is created on the container. Custom server style files must be distributed when the application is deployed.
Alternatively, server style files can be loaded into the SymbologyControl programmatically using the LoadStyleFile method and removed using the RemoveFile method.
See the following code example:
[C#]
axSymbologyControl1.LoadStyleFile(@
"myInstallLocation\ArcGIS\Engine10.1\Styles\ESRI.ServerStyle");
[VB.NET]
AxSymbologyControl1.LoadStyleFile("myInstallLocation\ArcGIS\Engine10.1\Styles\ESRI.ServerStyle")
SymbologyStyleClass
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 in 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.
See the following code example:
[C#]
IStyleGalleryItem serverStyleGalleryItem = axSymbologyControl1.GetStyleClass
(axSymbologyControl1.StyleClass).GetSelectedItem();
System.Windows.Forms.MessageBox.Show(serverStyleGalleryItem.Name);
[VB.NET]
Dim serverStyleGalleryItem As IStyleGalleryItem
serverStyleGalleryItem = AxSymbologyControl1.GetStyleClass(AxSymbologyControl1.StyleClass).GetSelectedItem()
System.Windows.Forms.MessageBox.Show(serverStyleGalleryItem.Name)
When the contents of a server style file are 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 at which items are displayed in 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.
See Also:
Controls library overviewSample: Add map surrounds using the SymbologyControl
Sample: Update a legend format with SymbologyControl area and line patches
Sample: Retrieve a color ramp from the SymbologyControl
Sample: Update a frame's background, border, and shadow using the SymbologyControl
Sample: Change layer rendering using the SymbologyControl
Sample: Control text symbols using the SymbologyControl
| Development licensing | Deployment licensing |
|---|---|
| Engine Developer Kit | Engine |
| ArcGIS for Desktop Basic | |
| ArcGIS for Desktop Standard | |
| ArcGIS for Desktop Basic |