This document is archived and information here might be outdated.  Recommended version.


DisplayUI (ArcObjects .NET 10.5 SDK)

DisplayUI


Supported with:
  • ArcGIS for Desktop Basic
  • ArcGIS for Desktop Standard
  • ArcGIS for Desktop Advanced
Library dependencies: Version, System, SystemUI, Geometry, GraphicsCore, Display, Server, Output, Geodatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation, Maplex, Geoprocessing, NetworkAnalyst, Schematic, SpatialAnalyst, 3DAnalyst, GlobeCore, EngineCore, TrackingAnalyst, Framework, Desktop.Addins, GeoDatabaseUI

Additional library information: Contents, Object Model Diagram

The DisplayUI library provides user interfaces (UIs), 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 in the DisplayUI library. In addition, dialogs that 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.

See the following sections for more information about this namespace:

Style gallery classes

The various components 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 objects that can be created with the class. With this interface, you can create style items using edit properties of an item, then draw a preview of the item to a window. The following table lists some of the properties exposed by IStyleGalleryClass for the classes that support it:
Style gallery class
Name
New object types
Preview ratio
Description
Area patches
Area patch
2
Area patch—Geometry used to draw symbol patches
Backgrounds
Normal background
2
Background
Borders
Normal border
4
Border
Color ramps
Random color ramp, multipart color ramp, preset color ramp, algorithmic color ramp
4
Color ramps
Colors
RGB, CMYK, HSV, Gray, name
1
Colors
Fill symbols
Fill symbol
1
Fill symbols
Labels
Label
4
Labels—Text symbol and placement option for labeling
Legend items
Horizontal bar, nested, horizontal, vertical
2
Legend items—The part of the legend that corresponds to one layer
Line patches
Line patch
2
Line patch—Geometry used to draw symbol patches
Line symbols
Line symbol
1
Line symbols
Reference systems
Graticule, measured grid, index grid
3
Reference systems
Marker symbols
Marker symbol
1
Marker symbols
North arrows
North arrow
1
North arrows
Scale bars
Scale line, stepped scale line, hollow scale bar, single division scale bar, alternating scale bar, double alternating scale bar
6
Scale bars
Scale texts
Scale text
10
Scale texts—Display scale as formatted text
Shadows
Normal shadow
2
Drop shadow
Text symbols
Text symbol
3
Text symbols
The following code shows how you can access the style gallery classes in a style. It assumes you have an application variable as a reference to the application object.
[VB.NET]
'Parameter check.
If application Is Nothing Then
    Return
End If

Dim mxDoc As IMxDocument=TryCast(application.Document, IMxDocument)
Dim styleGallery As IStyleGallery
styleGallery=mxDoc.StyleGallery

Dim enumBstr As IEnumBSTR
Dim objTypeList As String
Dim objType As String
Dim numClasses As Integer=styleGallery.ClassCount
Dim styleGalleryClass As IStyleGalleryClass

For i As Integer=0 To (numClasses - 1)
    styleGalleryClass=styleGallery.Class(i)
    objTypeList=styleGalleryClass.Name & ":"
    enumBstr=styleGalleryClass.NewObjectTypes
    objType=enumBstr.Next
    
    Do While Not (objType="")
        objTypeList=objTypeList & "," & objType
        objType=enumBstr.Next
    Loop
    
    MsgBox(styleGalleryClass.Name)
    
Next i
[C#]
//Parameter check.
if (application == null)
{
    return ;
}

IMxDocument mxDoc=application.Document as IMxDocument;
IStyleGallery styleGallery=null;
styleGallery=mxDoc.StyleGallery;

IEnumBSTR enumBstr=null;
string objTypeList=null;
string objType=null;
int numClasses=styleGallery.ClassCount;
IStyleGalleryClass styleGalleryClass=null;

for (int i=0; i <= (numClasses - 1); i++)
{
    styleGalleryClass=styleGallery.Class(i);
    objTypeList=styleGalleryClass.Name + ":";
    enumBstr=styleGalleryClass.NewObjectTypes;
    objType=enumBstr.Next();

    while (!(objType == ""))
    {
        objTypeList=objTypeList + "," + objType;
        objType=enumBstr.Next();
    }

    MessageBox.Show(styleGalleryClass.Name);
}
When you create a symbol item using IStyleGalleryClass.NewObject, the argument has to be one of the strings reported by IStyleGalleryClass.NewObjectTypes for that class. You can cast 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 style gallery item is useful when creating an object based on your choice of object type from a list of object types that you created using IStyleGalleryClass.NewObjectTypes. This process is shown in the following code.
[VB.NET]
'Create the new object.
Dim styleGalleryClass As IStyleGalleryClass
Dim newObject As stdole.IUnknown
styleGalleryClass=New FillSymbolStyleGalleryClass
newObject=TryCast(styleGalleryClass.NewObject("Fill Symbol"), stdole.IUnknown)
'Assign properties specific to the style class.
Dim simpleFillSymbol As ISimpleFillSymbol
If TypeOf newObject Is ISimpleFillSymbol Then
    simpleFillSymbol=TryCast(newObject, ISimpleFillSymbol)
    simpleFillSymbol.Color=BuildRGB(55, 55, 200)
End If
'Create a new style item using the object.
Dim newGalleryItem As IStyleGalleryItem=New StyleGalleryItem
newGalleryItem.Item=newObject
newGalleryItem.Name="My Fill Symbol"

Public Function BuildRGB(ByVal red As Int, ByVal green As Int, ByVal blue As Int) As IColor
    
    Dim rgbColor As IRgbColor=New RgbColorClass
    With rgbColor
        .Red=red
        .Green=green
        .Blue=blue
        .UseWindowsDithering=True
    End With
    Return rgbColor
    
End Function
[C#]
//Create the new object.
IStyleGalleryClass styleGalleryClass;
stdole.IUnknown newObject;
styleGalleryClass=new FillSymbolStyleGalleryClass();
newObject=styleGalleryClass.get_NewObject("Fill Symbol")as stdole.IUnknown;
//Assign properties specific to the style class.
ISimpleFillSymbol simpleFillSymbol=null;
if (newObject is ISimpleFillSymbol)
{
    simpleFillSymbol=newObject as ISimpleFillSymbol;
    simpleFillSymbol.Color=BuildRGB(55, 55, 200);
}

//Create a new style item using the object.
IStyleGalleryItem newGalleryItem=new StyleGalleryItem();
newGalleryItem.Item=newObject;
newGalleryItem.Name="My Fill Symbol";


private IColor BuildRGB(int red, int green, int blue)
{
    IRgbColor rgbColor=new RgbColorClass();
    rgbColor.Red=red;
    rgbColor.Green=green;
    rgbColor.Blue=blue;
    rgbColor.UseWindowsDithering=true;
    return rgbColor;
}
StyleManagerDialog and StyleReferencesDialog
The StyleManagerDialog class is a dialog box that lets you manage the styles referenced by a map document and the style items in them. The StyleReferencesDialog class 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 as shown in the following code:
[VB.NET]
Dim styleGallery As IStyleGallery=New StyleGallery
Dim styleDialog As IStyleDialog=New StyleManagerDialog
styleDialog.DoModal(styleGallery, Application.hWnd)
[C#]
IStyleGallery styleGallery=new StyleGallery();
IStyleDialog styleDialog=new StyleManagerDialog();
styleDialog.DoModal(styleGallery, Application.hWnd);
SymbolSelector
The SymbolSelector class is used for presenting the user with a choice of symbols: marker, line, fill, or text. The symbols in the selector are taken from the currently referenced style files.
The AddSymbol method is used to define the type of symbols that are displayed in the SymbolSelector. For example, passing a MarkerSymbol displays all available marker symbols. The AddSymbol method also determines the symbol that 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). The GetSymbolAt method is used to retrieve the selected symbol using an index of zero. This process is shown in the following code:
[VB.NET]
Dim symbolSelector As ISymbolSelector=New SymbolSelector
Dim markerSymbol As ISimpleMarkerSymbol=New SimpleMarkerSymbol

If Not symbolSelector.AddSymbol(CType(markerSymbol, ISymbol)) Then
    'Return a message here.
Else
    
    If symbolSelector.SelectSymbol(0) Then
        Dim symbol As ISymbol
        symbol=symbolSelector.GetSymbolAt(0)
    End If
    
End If
[C#]
ISymbolSelector symbolSelector=new SymbolSelector();
ISimpleMarkerSymbol markerSymbol=new SimpleMarkerSymbol();

if (!(symbolSelector.AddSymbol((ISymbol)markerSymbol)))
{
    //Return a message here.
}

else
{

    if (symbolSelector.SelectSymbol(0))
    {
        ISymbol symbol=null;
        symbol=symbolSelector.GetSymbolAt(0);
    }
}

Property pages

The various components that inherit from the PropertyPage abstract class encapsulate functionality, creating dialog boxes that contain only those controls that should be displayed for the respective type. These classes are listed as follows:
Creating a custom symbol property page
Designing a custom symbol property page provides an integrated UI for working with the custom symbol settings. The implementation strategy for this page is similar to that followed when designing a custom renderer property page. Define your custom symbol property page as a class that implements the following interfaces:
Register your custom symbol object in the proper custom symbol category—for example, Marker Symbols.
Register your custom property page object in the Symbol Property Pages category. Your custom property page will then be available in the Type pull-down 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 clicked, the temporary object replaces the current object. If the Cancel button is clicked, the temporary object is discarded.
The IComPropertyPage2 interface controls the Cancel operation on the page.
SymbolEditor dialog box
SymbolEditor provides an ideal way to edit 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 class can even change.
The EditSymbol method call opens the SymbolEditor dialog box. To determine if Cancel or OK was clicked, check the return value. This process is shown in the following code:
[VB.NET]
Dim markerSymbol As IMarkerSymbol=New SimpleMarkerSymbol
Dim symbolEditor As ISymbolEditor=New SymbolEditor
symbolEditor.Title="Edit My Marker"

If Not symbolEditor.EditSymbol(markerSymbol, 0) Then
    'Return a message here.
Else
    'Do something with the edited symbol.
    'A multi-layer symbol will be returned.
    
    Dim newSymbol As IMarkerSymbol
    Dim multiMarker As IMultiLayerMarkerSymbol
    multiMarker=TryCast(markerSymbol, IMultiLayerMarkerSymbol)
    newSymbol=multiMarker.Layer(0)
End If
[C#]
IMarkerSymbol markerSymbol=new SimpleMarkerSymbol();
ISymbolEditor symbolEditor=new SymbolEditor();
symbolEditor.Title="Edit My Marker";
if (!symbolEditor.EditSymbol(markerSymbol as ISymbol, 0))
{
    //Return a message here.
}

else
{
    //Do something with the edited symbol.
    //A multi-layer symbol will be returned.
    IMarkerSymbol newSymbol=null;
    IMultiLayerMarkerSymbol multiMarker=null;
    multiMarker=markerSymbol as IMultiLayerMarkerSymbol;
    newSymbol=multiMarker.get_Layer(0);
}
Other editor dialog boxes
TextSymbolEditor, TextBackgroundEditor, ChartSymbolEditor, LineDecorationEditor, and DefaultLegendSymbolEditor are accessed in a similar manner to that of SymbolEditor.