EDN: ESRI Developer Network
Supported with: ArcGIS Desktop
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto, NetworkAnalyst, Schematic, Location, NetworkAnalysis, Controls, GeoAnalyst, 3DAnalyst, GlobeCore, SpatialAnalyst, Framework, GeoDatabaseUI
The DisplayUI library provides user interfaces, including property pages, to support objects contained in the Display library. For example, the property pages for each symbol defined in the Display library are defined within this library. In addition, dialogs to manage styles and symbols are part of this library.
Developers extend this library when they create a UI to correspond with components they have created in the Display library.
The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:
The various coclasses that inherit from the StyleGallery abstract class encapsulate functionality, creating style items of the respective type.
The IStyleGalleryClass interface gives you access to the class name, description, and type of new objects that can be created with the class. Using this interface, you can create new style items using edit properties of an item, then draw a preview of the item to a window. The table below lists some of the properties exposed by IStyleGalleryClass for the coclasses that support it.
The code below illustrates how you can access the style gallery classes in a style:
Dim lClasses As Long Dim sObjTypeList As String Dim sObjType As String lClasses = pStyleGallery.ClassCount Dim pClass As IStyleGalleryClass Dim i As Long For i = 0 To (lClasses - 1) Set pClass = pStyleGallery.Class(i) sObjTypeList = pClass.Name & ":" Set pEnumBstr = pClass.NewObjectTypes sObjType = pEnumBstr.Next Do While Not sObjType = "" sObjTypeList = sObjTypeList & "," & sObjType sObjType = pEnumBstr.Next Loop Debug.Print sObjTypeList Next i
When you create a new symbol item using IStyleGalleryClass::NewObject, the argument has to be one of the strings reported by IStyleGalleryClass:: NewObjectTypes for that class. You can QueryInterface the returned object for an interface supported by the new style gallery item, then add this as an item to the style gallery using IStyleGalleryItem. This method of creating a new style gallery item is especially useful when you wish to create a new object based on your users choice of object type from a list of object types that you create using IStyleGalleryClass::NewObjectTypes.
'Create the new object
Dim pClass As IStyleGalleryClass
Dim pNewObject As IUnknown
Set pClass = New FillSymbolStyleGalleryClass
Set pNewObject = pClass.NewObject("Fill Symbol")
'Assign properties specific to the style class
If TypeOf pNewObject Is ISimpleFillSymbol Then
Dim pSimpleFillSymbol As ISimpleFillSymbol
Set pSimpleFillSymbol = pNewObject
pSimpleFillSymbol.Color = BuildRGB(55, 55, 200)
End If
'Create new style item using object, and add it to the target style
Dim pNewItem As IStyleGalleryItem
Set pNewItem = New StyleGalleryItem
pNewItem.Item = pNewObject
pNewItem.Name = "My Fill Symbol"
pStyleGallery.AddItem pNewItem
The StyleManagerDialog coclass is a dialog box that lets you manage the styles referenced by a map document and the style items in them. The StyleReferencesDialog coclass is a dialog box that lets you manage which style files ArcMap references.
Before calling IStyleDialog::DoModal, use IStyleManager::Title to change the title of the Style Manager dialog box.
Dim pMxDoc As IMxDocument Dim pStyleGallery As IStyleGallery Set pMxDoc = ThisDocument Set pStyleGallery = pMxDoc.StyleGallery Dim pStyleDialog As IStyleDialog Set pStyleDialog = New StyleManagerDialog pStyleDialog.DoModal pStyleGallery, Application.hWnd
The SymbolSelector coclass is ideal for presenting the user with a choice of symbols; marker, line, fill, or text symbols are available. The symbols in the selector are taken from all the currently referenced style files.
The AddSymbol method is used to define which type of symbols should be displayed in the SymbolSelector. For example, passing a MarkerSymbol will display all available MarkerSymbols. The AddSymbol method also determines which symbol is shown in the initial Preview frame when the dialog box opens.
The SelectSymbol method is used to display the dialog box; check the return value to determine if the user clicked OK (True) or Cancel (False).
Finally, the GetSymbolAt method is used to retrieve the selected symbol using an index of zero.
Dim pSymbolSelector As ISymbolSelector Set pSymbolSelector = New SymbolSelector Dim pMarker As ISimpleMarkerSymbol Set pMarker = New SimpleMarkerSymbol If Not pSymbolSelector.AddSymbol(pMarker) Then MsgBox "Could not add symbol" Else If pSymbolSelector.SelectSymbol(0) Then Dim pSymbol As ISymbol Set pSymbol = pSymbolSelector.GetSymbolAt(0) End If
The various coclasses that inherit from the PropertyPage abstract class encapsulate functionality, creating dialogs that contain only those controls that should be displayed for the respective type. The table below lists these coclasses.
Designing a custom symbol property page provides an integrated user interface for working with the custom symbol settings. The implementation strategy for this page will be similar to that followed when designing a custom renderer property page.
Define your custom symbol property page as a class that implements four interfaces: ISymbolPropertyPage, IComPropertyPage, IComPropertyPage2, and IPropertyPageContext. Register your custom symbol object in the proper custom symbol category, for example, Marker Symbols.
Register your custom property page object in the category Symbol Property Pages. Your custom property page will then become available in the Type pulldown menu on the ArcMap symbol property editor property sheet.
The ISymbolPropertyPage interface controls the measurement units that will appear on the page.
IComPropertyPage works with general property page settings. The typical behavior for a property page is to allow changes to a temporary object. Then if the Apply or OK button is pressed, the temporary object replaces the live object. If the Cancel button is pressed, then the temporary object is discarded.
The IComPropertyPage2 interface controls the Cancel operation on your page.
The SymbolEditor provides an ideal way to allow a user to edit all the properties of a specific, preexisting symbol.
The EditSymbol method takes an ISymbol parameter, which must be an existing object that supports ISymbol. This object is passed by reference and will be directly changed depending on the selections made in the dialog box. Its coclass may even change.
The EditSymbol method call will open the SymbolEditor dialog box. To determine if the user clicked Cancel or OK, check the return value.
Dim pSymbol As IMarkerSymbol Set pSymbol = New SimpleMarkerSymbol Dim pSymbolEditor As ISymbolEditor Set pSymbolEditor = New SymbolEditor pSymbolEditor.Title = "Edit My Marker" If Not pSymbolEditor.EditSymbol(pSymbol, 0) Then MsgBox "User pressed Cancel" Else 'Do something with the edited Symbol 'A multi-layer symbol will be returned Dim pnewSymbol As IMarkerSymbol Dim pMultiMarker As IMultiLayerMarkerSymbol Set pMultiMarker = pSymbol Set pnewSymbol = pMultiMarker.Layer(0) End If
Additionally, the TextSymbolEditor, TextBackgroundEditor, ChartSymbolEditor,
LineDecorationEditor, and DefaultLegendSymbolEditor are accessed in a similar fashion.