Supported with: ArcGIS Engine

Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto, NetworkAnalyst, Location, NetworkAnalysis

The Controls library contains the MapControl, PageLayoutControl, TOCControl (Table of Contents), ToolbarControl, GlobeControl, SceneControl, LicenseControl and SymbologyControl together with a collection of Control Commands. The ArcGIS Engine Controls are high-level developer components that first enable you to build and extend Windows applications with ArcGIS functionality and second provide a graphical user interface (GUI). The control commands are a set of commands, tools, menus and palettes that work with the ArcGIS Engine Controls.

Note: In addition to the ArcGIS Engine Controls contained in this library, an ArcReaderControl and ArcReaderGlobeControl exist in the Publisher library.

The Controls library is grouped into a number of subareas. These areas are:

• LicenseControl
• MapControl
• PageLayoutControl
• GlobeControl
• SceneControl
• TOCControl
• ToolbarControl
• Control Commands
• SymbologyControl

However, before discussing the details of each of these areas, there are some common themes and concepts, applicable to each of the ArcGIS Engine Controls, that should be understood in order to effectively build applications using them.

Embeddable components

Each ArcGIS Control is an embeddable component that can be dropped within a container form or dialog box provided by a visual design environment. The ArcGIS Engine Controls can be embedded into an existing application to add additional 2D or 3D mapping capability, or can be used to create a new standalone application. Once within a container, each ArcGIS Control can be resized and repositioned along with other embeddable components, such as command buttons and combo boxes, to provide a user interface in the application.

The LicenseControl is visible within a visual design environment but is invisible at runtime, so unlike the other ArcGIS Engine Controls the LicenseControl does not provide any user interface in an application.

Property pages

Each ArcGIS Control has a set of property pages that is accessible in most visual design environments; once the control is embedded within a container, right-click on the control and choose Properties from the context menu. These property pages provide shortcuts to a selection of a controls properties and methods and allow a developer to build an application with little or no code.

Encapsulated ArcObjects

Each ArcGIS Control simplifies the development process by encapsulating coarse-grained ArcObjects, while still providing access to finer-grained ArcObjects. For example, the PageLayoutControl encapsulates the PageLayout object. This is the same PageLayout coclass found inside the ArcMap application. The PageLayout contains at least one MapFrame element containing a Map and the Map can contain multiple RasterLayer, FeatureLayer, or custom Layer objects. Each ArcGIS Control provides shortcuts to frequently used properties and methods on the ArcObjects component they encapsulate. For example, the MapControl has a SpatialReference property that is a shortcut to the SpatialReference property of the Map object. Each ArcGIS Control also has some helper methods that perform common tasks. For example, the MapControl has an AddShapeFile method. The ArcGIS Engine Controls are typically a starting point for developing applications not only because they provide user interface but also by providing a direct route into the object model.

Events

Each ArcGIS Control fires events in response to keyboard and mouse interactions by the end user. Other events fire in response to actions occurring within the controls. For example, when a map document is loaded into the MapControl the OnMapReplaced event is fired, or when an object is dragged over the MapControl via drag-and-drop the OnOleDrop event is fired.

Buddy controls

An individual ArcGIS Control can be embedded into an application, or the TOCControl and ToolbarControl can be used with another ArcGIS Control to provide part of the application's framework. The ToolbarControl and TOCControl each work in conjunction with one other "buddy control". Typically the buddy control is a MapControl, PageLayoutControl, GlobeControl, or SceneControl. The buddy control can be set at design-time though the control property pages (in development environments that support property page capability) or programmatically using the SetBuddyControl method. The TOCControl uses the buddy control to display an interactive tree view of its map, layer, and symbology contents, while the ToolbarControl hosts a panel of commands, tools, menus and palettes that work with the display of the buddy control.

TOCControl1.SetBuddyControl GlobeControl1

ToolbarControl1.SetBuddyControl GlobeControl1

AxTOCControl1.SetBuddyControl(AxGlobeControl1)

AxToolbarControl1.SetBuddyControl(AxGlobeControl1)

axTOCControl1.SetBuddyControl(axGlobeControl1);

axToolbarControl1.SetBuddyControl(axGlobeControl1);

Map authoring

The ArcGIS Desktop applications can be used to preauthor documents that can be loaded into the ArcGIS Engine Controls, to quickly produce high quality mapping. For example, ArcMap can be used to author map documents that can be loaded into the MapControl and PageLayoutControl; ArcGlobe to author globe documents that can be loaded into the GlobeControl; and ArcScene to author scene documents that can be loaded into the SceneControl. Preauthoring documents can save a substantial amount of time as it eliminates the need to programmatically create maps, renderers, and symbols, and set their properties. Once a document is loaded into an ArcGIS Control any layers, elements, and symbols can be accessed programmatically through the object model if their appearance needs changing.

The table below summarizes the types of document that can be loaded into applicable ArcGIS Engine Controls.

LicenseControl

The LicenseControl is used to initialize an application with a suitable license(s) in order for it to run successfully on any machine it is deployed on to. The LicenseControl will configure the licenses at application start time when the form or dialog containing the LicenseControl is loaded. Use the LicenseControl to automatically perform license initialization within simple graphical user interface applications using the MapControl, PageLayoutControl, TOCControl, ToolbarControl, GlobeControl or SceneControl. If greater control is required over license initialization, particularly when checking out and in extension licenses (the LicenseControl will check out extension licenses for the duration of an application's life) use the AoInitialize object in the System library to programmatically perform license initialization.

The LicenseControl is visible within a visual design environment, but is invisible at runtime, so unlike the other controls the LicenseControl does not provide any user interface in an application. In design time the LicenseControl property pages must be used to configure the application with product and extension licenses. The LicenseControl is only available with the COM (ActiveX Control) and .NET (Windows Control) APIs.

Products

Select at least one product license the application can be initialized with. By default the LicenseControl will try to initialize the application with the ArcGIS Engine product license. If the product you require is not licensed you may optionally initialize the application with a higher product license. For example, if you select the ArcGIS Engine license and the ArcView license, the LicenseControl will initially try to initialize the application with an ArcGIS Engine license (the lower license). If that license is not available the LicenseControl will try to initialize the application with an ArcView license (the next higher level license selected). If no product licenses are available then the application will fail to initialize. Note, that once an application is initialized with a product license it is not possible to re-initialize the application for the duration of the applications life.

Extensions

Select the extension licenses required by the application. Not every extension license is available with every product license, as such the list of available extension licenses will change as different product licenses become selected. If the ArcGIS Engine product license is selected and an ArcGIS Desktop product is selected, only the ArcGIS Engine extension licenses will display. The availability of each extension license is checked in conjunction with the product license that the application will ultimately be initialized with. If any of the selected extensions are not available the application will fail to initialize. The LicenseControl will check out extensions directly after the application is initialized and will check in extensions when the application is shutdown.

If a GlobeControl or SceneControl (requiring the 3D Analyst extension) is embedded within the same container as the LicenseControl, the 3D Analyst extension will automatically be checked.

Shutdown

Set whether the LicenseControl will automatically shut down the application if license initialization fails. If the LicenseControl handles license initialization failure a 'License Failure' dialog box will be displayed to the user before the application is shutdown. If the developer handles license initialization failure the ILicenseControl interface members can be used to obtain information on the nature of the failure before the application is programmatically shut down.

MapControl

The MapControl corresponds to the data view of the ArcMap desktop application and encapsulates the Map object. Map documents preauthored with the ArcMap application can be loaded into the MapControl eliminating the need to programmatically compose the cartography.

Loading map documents

The map document can be set at design-time though the MapControl property pages (in development environments that support property page capability) and the MapControl can be set to "link" or "contain" the map document. When linking, the MapControl will read the map document whenever the MapControl is created on the container and display the most recent updates to the map document. When containing, the MapControl will copy the contents of the map document into the MapControl but will not display any further updates made to the map document from that point onwards. Containing increases the size of the application executable containing the MapControl.

Alternatively, a map document can be loaded into the MapControl programmatically using the CheckMxFile method to determine whether the document is valid and the LoadMxFile method to load in the map document. The ReadMxMaps can be used in conjunction with the LoadMxFile method to load a specific Map from a map document into the MapControl.

Dim sFilePath As String
sFilePath = "C:\Temp\myDocument.mxd"
If MapControl1.CheckMxFile(sFilePath) Then MapControl1.LoadMxFile sFilePath

Dim sFilePath As String
sFilePath = "C:\Temp\myDocument.mxd"
If AxMapControl1.CheckMxFile(sFilePath) Then AxMapControl1.LoadMxFile(sFilePath)

string filePath = @"C:\Temp\myDocument.mxd";
if (axMapControl1.CheckMxFile(filePath)) axMapControl1.LoadMxFile(filePath,Type.Missing,Type.Missing);

Saving map documents

As well as reading map documents, the MapControl can also write map documents (*.mxd). The MapControl implements the IMxdContents interface that enables the MapDocument object to write the contents of the MapControl to a new map document.

Layers

Display

The display area of the MapControl can be altered by using the VisibleRegion property to change the shape of the display area and the Rotation property to alter the angle at which data is drawn on the display. Helper methods such as TrackRectangle, TrackPolygon, TrackLine, and TrackCircle exist on the MapControl for tracking or "rubber banding" shapes on the display. For example, to zoom in on the display set the Envelope returned from TrackRectangle method into the Extent property. Shapes can be drawn on the display with the DrawShape, DrawText, and FlashShape methods typically in the IMapControl2::OnAfterDraw event.

Private Sub MapControl1_OnMouseDown(ByVal button As Long, ByVal shift As Long, ByVal x As Long, ByVal y As Long, ByVal mapX As Double, ByVal mapY As Double)
  MapControl1.Extent = MapControl1.TrackRectangle 'Zoom in
End Sub

Private Sub AxMapControl1_OnMouseDown(ByVal sender As System.Object, ByVal e As ESRI.ArcGIS.MapControl.IMapControlEvents2_OnMouseDownEvent) Handles AxMapControl1.OnMouseDown
  AxMapControl1.Extent = AxMapControl1.TrackRectangle() 'Zoom in
End Sub

private void axMapControl1_OnMouseDown(object sender, ESRI.ArcGIS.MapControl.IMapControlEvents2_OnMouseDownEvent e)
{
  axMapControl1.Extent = axMapControl1.TrackRectangle(); //Zoom in
}

PageLayoutControl

The PageLayoutControl corresponds to the "layout" view of the ArcMap desktop application and encapsulates the PageLayout object. Map documents authored with the ArcMap application can be loaded into the PageLayoutControl eliminating the need to programmatically compose the cartography.

Loading map documents

The map document can be set at design-time though the PageLayoutControl property pages (in development environments that support property page capability) and the PageLayoutControl can be set to "link" or "contain" the map document. When linking, the PageLayoutControl will read the map document whenever the PageLayoutControl is created on the container and display the most recent updates to the map document. When containing, the PageLayoutControl will copy the contents of the map document into the PageLayoutControl and will not display any further updates made to the map document from that point onwards. Containing increases the size of the application executable containing the PageLayoutControl.

Alternatively, a map document can be loaded into the PageLayoutControl programmatically using the CheckMxFile method to determine whether the document is valid and the LoadMxFile method to load in the map document.

Saving map documents

As well as reading map documents, the PageLayoutControl can also write map documents (*.mxd). The PageLayoutControl implements the IMxdContents interface that enables the MapDocument object to write the contents of the PageLayoutControl to a new map document.

Dim pMapDocument As IMapDocument
Set pMapDocument = New MapDocument
pMapDocument.New "C:\Temp\myDocument.mxd"
pMapDocument.ReplaceContents PageLayoutControl1.object
pMapDocument.SetActiveView PageLayoutControl1.ActiveView
pMapDocument.Save True, True

Dim pMapDocument As IMapDocument
pMapDocument = New MapDocument
pMapDocument.New("C:\Temp\myDocument.mxd")
pMapDocument.ReplaceContents(AxPageLayoutControl1.Object)
pMapDocument.SetActiveView(AxPageLayoutControl1.ActiveView)
pMapDocument.Save(True, True)

IMapDocument mapDocument = new MapDocumentClass();
mapDocument.New(@"C:\Temp\myDocument.mxd");
mapDocument.ReplaceContents((IMxdContents) axPageLayoutControl1.Object);
mapDocument.SetActiveView(axPageLayoutControl1.ActiveView);
mapDocument.Save(true, true);

Elements

The PageLayoutControl provides shortcuts to frequently used members such as the GraphicsContainer, and AddElement, and helper methods such as FindElementByName and LocateFrontElement to manage individual elements in the PageLayout.

Printing

The PageLayoutControl provides shortcuts to frequently used members on the PageLayout object such as Page and Printer, and helper members such as PrinterPageCount and PrintPageLayout to assist with printing tasks.

GlobeControl

The GlobeControl corresponds to the '3D View' of the ArcGlobe desktop application and provides a 3D view of data on a globe surface in true geodetic location. Note the GlobeControl requires the ArcGIS Engine 3D Analyst Extension.

Globe objects

The GlobeControl encapsulates an object implementing IGlobeViewer. This is the same IGlobeViewer object found inside the ArcGlobe application. The IGlobeViewer object contains a GlobeDisplay and the GlobeDisplay contains a Globe. The GlobeControl provides shortcuts to frequently used properties and methods on the object it encapsulates. For example, the GlobeControl has GlobeCamera, Globe, GlobeDisplay and GlobeViewer properties. For more information about these objects see the GlobeCore library.

Loading Globe Documents

The globe document can be set at design time through the GlobeControl property pages (in development environments that support property page capability). The GlobeControl will attempt to load this document when it is created. Alternatively, a globe document can be loaded into the GlobeControl programmatically using the Check3dFile method to determine whether the document is valid and the Load3dFile method to load in the globe document.

Dim sFilePath As String
sFilePath = "C:\Temp\MyGlobeDocument.3dd"
If GlobeControl1.Check3dFile(sFilePath) Then GlobeControl1.Load3dFile sFilePath

Dim sFilePath As String
sFilePath = "C:\Temp\MyGlobeDocument.3dd"
If AxGlobeControl1.Check3dFile(sFilePath) Then AxGlobeControl1.Load3dFile(sFilePath)

string filePath = @"C:\Temp\MyGlobeDocument.3dd";
if (axGlobeControl1.Check3dFile(filePath))  axGlobeControl1.Load3dFile(filePath);

Navigation

The GlobeControl has built in navigation functionality that can be switched on at design time through the GlobeControl property pages or programmatically with the Navigate property. The functionality enables the end user to use the left mouse button to navigate backwards and forwards and to the left and right of the display, and the right mouse button to zoom in and out on the display.

SceneControl

The SceneControl corresponds to the '3D View' of the ArcScene desktop application and provides a way to view and investigate spatial data layers in 3D. Note the SceneControl requires the ArcGIS Engine 3D Analyst Extension.

Scene objects

The SceneControl encapsulates an object implementing ISceneViewer. This is the same ISceneViewer object found inside the ArcScene application. The ISceneViewer object contains a Camera and the Camera contains an Observer and Target position. The SceneControl provides shortcuts to frequently used properties and methods on the object it encapsulates. For example, the SceneControl has Camera, Scene, SceneGraph and SceneViewer properties. For more information about these objects see the 3DAnalyst library.

Loading Scene Documents

The scene document can be set at design time through the SceneControl property pages (in development environments that support property page capability). The SceneControl will attempt to load this document when it is created. Alternatively, a scene document can be loaded into the SceneControl programmatically using the CheckSxFile method to determine whether the document is valid and the LoadSxFile method to load in the scene document.

Dim sFilePath As String
sFilePath = "C:\Temp\MySceneDocument.sxd"
If SceneControl1.CheckSxFile(sFilePath) Then SceneControl1.LoadSxFile sFilePath

Dim sFilePath As String
sFilePath = "C:\Temp\MySceneDocument.sxd"
If AxSceneControl1.CheckSxFile(sFilePath) Then AxsceneControl1.LoadSxFile(sFilePath)

string filePath = @"C:\Temp\MySceneDocument.sxd";
if (axSceneControl1.CheckSxFile(filePath))  axSceneControl1.LoadSxFile(filePath);

Navigation

The SceneControl has built in navigation functionality that can be switched on at design time through the SceneControl property pages or programmatically with the Navigate property. The functionality enables the end user to use the left mouse button to navigate backwards and forwards and to the left and right of the display, and the right mouse button to zoom in and out on the display.

TOCControl

The TOCControl works in conjunction with a "buddy control". The buddy control can be a MapControl, PageLayoutControl, GlobeControl, or SceneControl. The buddy control can be set at design-time though the TOCControl property pages (in development environments that support property page capability) or programmatically using the SetBuddyControl method when the container hosting the TOCControl is displayed.

TOCControl1.SetBuddyControl MapControl1

AxTOCControl1.SetBuddyControl(AxMapControl1)

axTOCControl1.SetBuddyControl(axMapControl1);

Each TOCControl buddy control implements the ITOCBuddy interface and can fire methods on the ITOCBuddyEvents interface. The TOCControl uses the buddy control to display an interactive tree view of its map, layer, and symbology contents and to keep its contents synchronized with the buddy control. For example, if the TOCControl has a MapControl as its buddy, and a map layer is removed from the MapControl, the map layer will also be removed from the TOCControl. Likewise, if the end user interacts with the TOCControl to uncheck a map layer's visibility, the layer will no longer be visible within the MapControl.

Layer drag and drop

The TOCControl can support the dragging and dropping of layers within the control when the ITOCControl2::EnableLayerDragDrop property is set. Layers can be moved or copied (by using the CTRL key) in the following ways: within a map; within, to and from group layers; between maps; between maps in different TOCControl's; and from ArcMap.

Selected item

An item can be selected in the TOCControl, either interactively by the end user clicking on the TOCControl, or programmatically using ITOCControl2::SelectItem method. The ITOCControl2::GetSelectedItem method returns the selected item.

Dim pMap As IMap, player As ILayer, pLegendGroup As ILegendGroup
Dim pIndex As Long, pItem As esriTOCControlItem
TOCControl1.GetSelectedItem pItem, pMap, player, pLegendGroup, pIndex
If pItem = esriTOCControlItemLayer Then MsgBox "Map: " & pMap.Name & " Layer: " & player.Name

Dim map As IMap, layer As ILayer, legendGroup As Object
Dim index As Object, item As esriTOCControlItem
map = New MapClass
layer = New FeatureLayerClass
legendGroup = New Object
index = New Object
item = New esriTOCControlItem

AxTOCControl1.GetSelectedItem(item, map, layer, legendGroup, index)
If item = esriTOCControlItem.esriTOCControlItemLayer Then MessageBox.Show("Map: " & map.Name & " Layer: " & layer.Name)

IBasicMap map = new MapClass();
ILayer layer = new FeatureLayerClass();
object legendGroup = new object();
object index = new object();
esriTOCControlItem item = new esriTOCControlItem();

axTOCControl1.GetSelectedItem(ref item, ref map, ref layer, ref legendGroup, ref index);
if (item == esriTOCControlItem.esriTOCControlItemLayer) MessageBox.Show("Map: " + map.Name + " Layer: " + layer.Name);

ToolBarControl

The ToolbarControl works in conjunction with a "buddy control". The buddy control can be a MapControl, PageLayoutControl, GlobeControl or SceneControl. The buddy control can be set at design-time though the ToolbarControl property pages (in development environments that support property page capability) or programmatically using the SetBuddyControl method when the container hosting the ToolbarControl is displayed. The ToolbarControl hosts a panel of commands, tools, tool controls, menus and palettes that work with the display of the buddy control.

ToolbarControl1.SetBuddyControl PageLayoutControl1

AxToolbarControl1.SetBuddyControl(AxPageLayoutControl1)

axToolbarControl1.SetBuddyControl(axPageLayoutControl1);

Each ToolbarControl buddy control implements the IToolbarBuddy interface. This interface is used to set the CurrentTool property of the buddy control. For example, imagine a ToolbarControl that is hosting a Page Zoom In tool and has a PageLayoutControl as its buddy. When the end user clicks on the Page Zoom In tool on the ToolbarControl it will become the CurrentTool of the PageLayoutControl. The implementation of the Page Zoom In tool will query the ToolbarControl to access its buddy control (the PageLayoutControl) and retrieve the PageLayout. It will then provide the implementation for displaying the rectangle dragged by the end user and changing the extent of the PageLayout.

The ToolbarControl is typically used with a selection of the Control Commands and a buddy control to quickly provide a functional GIS application. The ToolbarControl is not only providing a part of the user interface, it is also providing a part of the application's framework. ArcGIS desktop applications like ArcMap, ArcGlobe, and ArcScene have a powerful and flexible framework that includes user interface components such as toolbars, commands, menus, dockable windows, and status bars. This framework enables the end user to customize the application by allowing them to reposition, add, and remove most of these user interface components.

Many development environments provide some pieces of a framework in the form of simple dialog boxes, forms, and multiple docking interface (MDI) applications. They also provide generic user interface components like buttons, status bars, and list boxes. However, a substantial amount of coding can still be required to provide toolbars, menus and palettes that host commands, especially if they need to be customized by the end user. The ToolbarControl and the objects within its library can supply pieces of a framework similar to the ArcGIS Desktop application framework. The developer can use some or all of these framework pieces when building an application with the ToolbarControl.

Commands

ArcGIS Engine provides several suites of Control Commands that work with the ArcGIS Engine Controls to perform some specific action. You can extend this suite of control commands by creating your own customized commands that perform some specific piece of work. All of these Command objects implement the ICommand interface that is used by the ToolbarControl to call methods and access properties at appropriate times.

The ICommand::OnCreate method is called shortly after the Command object is hosted on the ToolbarControl. The method is passed a handle or "hook" to the application that the command will work with. The implementation of a command normally tests to see if the hook object is supported (that is, the command tests to see that the hook is an object that the command can work with). If the hook is not supported the command will disables itself. If the hook is supported the command stores the hook for later use. For example, if an Open Map Document command is to work with the MapControl or PageLayoutControl and they are passed to the OnCreate method as the hook, the command will store the hook for later use. If the ToolbarControl is passed to the OnCreate event as the hook, the command would normally check the type of buddy control being used in conjunction with the ToolbarControl using the Buddy property. For example, if a command hosted on the ToolbarControl only works with the GlobeControl and the ToolbarControl's buddy is a MapControl, the command should disable itself.

The ICommand::OnClick method is called when the end user clicks on a command item hosted on the ToolbarControl. Depending on the type of command, it will typically do some work using the hook to access the required objects from the buddy control. There are three types of commands:

• A command item implementing the ICommand interface that responds to a single click. A click results in call to the ICommand::OnClick method, and some action is performed. By changing the ICommand::Checked value simple command items can behave like a toggle.
• A command item or tool implementing both the ICommand and ITool interfaces that requires end user interaction with the display of the buddy control. The ToolbarControl maintains one CurrentTool. When the end user clicks the tool on the ToolbarControl it becomes the CurrentTool and the previous tool is deactivated. The ToolbarControl will set the CurrentTool of the buddy control. While the tool is the CurrentTool it will receive mouse and key events from the buddy control.
• A command item or tool control implementing both the ICommand and IToolControl interfaces. This is typically a user interface component like a Listbox or ComboBox hosted on the ToolbarControl. The ToolbarControl hosts a small window supplied by a window handle from the IToolControl::hWnd property. Only a single instance of a particular tool control can be added to the ToolbarControl.

Commands can be added to ToolbarControl either programmatically or at design-time by clicking Add on the Items property page to display commands, toolsets, menus and palettes registered in the various ArcGIS Engine Controls-related component categories. Commands can be added programmatically, by specifying a UID object that uniquely identifies a command (using a globally unique identifier, or GUID) to the AddItem method, or by supplying an instance of an existing Command object to the AddItem method. Where possible commands should be added to the ToolbarControl by specifying a UID. If a UID is supplied, the ToolbarControl can identify whether this command has previously been added, and if so can reuse its previous instance. When an existing instance of a Command object is added to the ToolbarControl there is no unique identifier for the command and multiple instances of the same command can exist on the ToolbarControl.

ToolbarControl1.SetBuddyControl MapControl1
ToolbarControl1.AddItem "esriControls.ControlsOpenDocCommand", , , False, , esriCommandStyleIconAndText
ToolbarControl1.AddItem "esriControls.ControlsMapZoomInTool", , , True, , esriCommandStyleIconOnly
ToolbarControl1.AddItem "esriControls.ControlsMapZoomOutTool", , , False, , esriCommandStyleIconOnly
ToolbarControl1.AddItem "esriControls.ControlsMapFullExtentCommand", , , False, , esriCommandStyleIconOnly

AxToolbarControl1.SetBuddyControl(AxMapControl1)
AxToolbarControl1.AddItem("esriControls.ControlsOpenDocCommand", , , False, , esriCommandStyles.esriCommandStyleIconAndText)
AxToolbarControl1.AddItem("esriControls.ControlsMapZoomInTool", , , True, , esriCommandStyles.esriCommandStyleIconOnly)
AxToolbarControl1.AddItem("esriControls.ControlsMapZoomOutTool", , , False, , esriCommandStyles.esriCommandStyleIconOnly)
AxToolbarControl1.AddItem("esriControls.ControlsMapFullExtentCommand", , , False, , esriCommandStyles.esriCommandStyleIconOnly)

axToolbarControl1.SetBuddyControl(axMapControl1);
axToolbarControl1.AddItem("esriControls.ControlsOpenDocCommand",-1,-1,false,0,esriCommandStyles.esriCommandStyleIconAndText);
axToolbarControl1.AddItem("esriControls.ControlsMapZoomInTool",-1,-1,true,0,esriCommandStyles.esriCommandStyleIconOnly);
axToolbarControl1.AddItem("esriControls.ControlsMapZoomOutTool",-1,-1,false,0,esriCommandStyles.esriCommandStyleIconOnly);
axToolbarControl1.AddItem("esriControls.ControlsMapFullExtentCommand",-1,-1,false,0,esriCommandStyles.esriCommandStyleIconOnly);

ToolbarItem

A ToolbarItem is a single command, menu or palette hosted on a ToolbarControl, ToolbarMenu or ToolbarPalette. The IToolbarItem interface has properties to determine the appearance of the item to the end user. For example, whether the item has a vertical line to its left signifying that it begins a Group and whether the Style of the item displays with a bitmap, a caption, or both. The Command, Menu, Palette and MultiItem properties return the actual command, menu, palette or multi-item that the ToolbarItem represents. Note that a MultiItem object can only exist on a ToolbarMenu.

Updating commands

By default the ToolbarControl updates itself automatically every half a second. This ensures that the appearance of each ToolbarItem hosted on the ToolbarControl is synchronized with the Enabled, Bitmap, Checked, and Caption properties of its underlying Command. Changing the UpdateInterval property can alter the frequency of the update. An UpdateInterval of 0 will stop any updates from happening automatically and you will then need to call the Update method programmatically to refresh the state of each ToolbarItem.

The first time the Update method is called in an application, the ToolbarControl will check whether the ICommand::OnCreate method of each ToolbarItems underlying Command has been called. If the method has not been called the ToolbarControl is automatically passed as the hook to the ICommand::OnCreate method.

ToolbarMenu

ToolbarControl1.AddMenuItem "esriControls.ControlsMapViewMenu", -1, False

AxToolbarControl1.AddMenuItem("esriControls.ControlsMapViewMenu", -1, False)

axToolbarControl1.AddMenuItem("esriControls.ControlsMapViewMenu", -1, false, -1);

The IToolbarMenu2 interface provides an AddMultiItem method that enables IMultiItem objects to be appended to an existing ToolbarMenu. The IMultiItem object allows a single object to act like several adjacent menu items. For example, a list of most recently loaded map documents or a list of the spatial bookmarks within a map.

ToolbarPalette

Dim pToolbarPalette As IToolbarPalette
Set pToolbarPalette = New ToolbarPalette
pToolbarPalette.AddItem "esriControlCommands.ControlsSelectTool"
pToolbarPalette.AddItem "esriControlCommands.ControlsNewLineTool"
pToolbarPalette.AddItem "esriControlCommands.ControlsNewPolygonTool"
ToolbarControl1.AddItem pToolbarPalette, , 0, False, , esriCommandStyleIconAndText

Dim toolbarPalette As IToolbarPalette
toolbarPalette = New ToolbarPalette
toolbarPalette.AddItem("esriControlCommands.ControlsSelectTool")
toolbarPalette.AddItem("esriControlCommands.ControlsNewLineTool")
toolbarPalette.AddItem("esriControlCommands.ControlsNewPolygonTool")
AxToolbarControl1.AddItem(toolbarPalette, , 0, False, , esriCommandStyles.esriCommandStyleIconAndText)

IToolbarPalette toolbarPalette = new ToolbarPaletteClass();
toolbarPalette.AddItem("esriControlCommands.ControlsSelectTool",-1,-1);
toolbarPalette.AddItem("esriControlCommands.ControlsNewLineTool",-1,-1);
toolbarPalette.AddItem("esriControlCommands.ControlsNewPolygonTool",-1,-1);
axToolbarControl1.AddItem(toolbarPalette,-1,0,false,0,esriCommandStyles.esriCommandStyleIconAndText);

CommandPool

Each ToolbarControl, ToolbarMenu and ToolbarPalette has a CommandPool that is used to manage the collection of Command objects that it is using. Normally, as a developer, you won't interact with the CommandPool. When a command is added to the ToolbarControl, either through the property pages of the ToolbarControl or programmatically, the command is automatically added to the CommandPool. Command objects are added to the CommandPool either as a UID object that uniquely identifies the Command (using a GUID) or as an existing instance of a Command object.

If an existing instance of a Command object is added there is no unique identifier for the command and multiple instances of the same command can exist in the CommandPool. If a UID object is supplied, the CommandPool can identify whether the Command already exists in the CommandPool, and, if so, can reuse the previous instance of the command. The CommandPool manages this by tracking whether the OnCreate method of a command has been called. If the OnCreate method has been called it will reuse the command and increment its UsageCount.

For example, if a Zoom In tool is added to a ToolbarControl twice, with the UID supplied, when one of the Zoom In items on the ToolbarControl is selected and appears "pressed", the other Zoom In item will also appear pressed because they are both using the same Command object. When an application contains multiple ToolbarControls, ToolbarMenus or ToolbarPalettes you should ensure each ToolbarControl, ToolbarMenu and ToolbarPalette uses the same CommandPool; this prohibits more than one instance of a command being created in the application.

Customization

The ToolbarControl has a Customize property that can be set to True to put the ToolbarControl into customize mode. This changes the behaviour of the ToolbarControl and allows the end user to rearrange, remove, and add items as well as change their appearance.

• Use the left mouse button to select an item on the ToolbarControl, either drag the selected item to a new position or drag-and-drop the item off the ToolbarControl to remove it.
• Use the right mouse button to select an item and display a customize menu. The customize menu can be used to remove the item or change the Style (bitmap, caption, or both) and Group properties of the ToolbarItem.

While the ToolbarControl is in customize mode you can programmatically launch the modeless CustomizeDialog. The CustomizeDialog lists all of the Control Commands, together with any custom commands, toolsets, menus and palettes. It does this by reading entries from the ESRI Controls Commands, ESRI Controls Toolbars, ESRI Controls Menus and ESRI Controls Palettes component categories. If required you can change the CustomizeDialog to use alternative component categories with CommandsCategory, ToolbarsCategory, MenusCategory and PalettesCategory properties. The end user can add these commands, toolsets, menus and palettes to the ToolbarControl either by dragging-and-dropping them on to the ToolbarControl or double-clicking them.

The CustomizeDialog is modeless to allow the user to interact with the ToolbarControl. When the CustomizeDialog is launched with the StartDialog method, the method call returns immediately while the CustomizeDialog remains open on the screen. In order to keep a reference to the CustomizeDialog while it is open, it is sensible practice to store a class level variable to the CustomizeDialog and to listen to its ICustomizeDialogEvents.

Use the IToolbarControl2::SaveItems method to save out the contents of a ToolbarControl after it has been customized by an end user at runtime. The IToolbarControl2::LoadItems method can be used to reload the contents back into a ToolbarControl.

Operation Stack

The ToolbarControl has an OperationStack that is used to manage undo and redo functionality. Operations are added to the operation stack by each ToolbarItems underlying command, so that the operation can be rolled forward and then rolled back as desired. For example, when a graphic element is moved, the operation can be undone by moving the graphic back to its original location. Whether or not a command makes use of an OperationStack depends upon its implementation. Typically, as a developer, you create a single ControlsOperationStack for an application (by default the OperationStack property is Nothing) and set it into each ToolbarControl. Undo and Redo commands can be added to the ToolbarControl that step through the OperationStack. The Undo and Redo commands of the ArcGIS Engine Controls exist in the Control Commands. Any extent changes in an ActiveView are added to the IActiveView::ExtentStack and not an OperationStack.

Appearance

The appearance of the ToolbarControl can be controlled by members of the IToolbarControl2 interface. The orientation of a ToolbarControl can be set to either horizontal or vertical using the Orientation property. The BackColor, FadeColor and FillDirection properties control the background shading of the ToolbarControl. Alternatively, the Transparent property can set the background to be transparent. The ShowHiddenItems property determines whether any hidden items on the ToolbarControl are visible on a 'hidden items menu' indicated to the end user by two chevrons.

Control Commands

The Control Commands are commands, tools, toolcontrols, toolsets, menus and palettes that work with the ArcGIS Engine Controls to perform some specific action. For example, there is a suite of map navigation, map inquiry, feature selection, graphic element, feature editing and ink commands that work with the MapControl and PageLayoutControl; a suite of globe commands that work with the GlobeControl; a suite of scene commands that work with the SceneControl; and a suite of network and schematics commands that work with the Network Analyst and Schematics extensions respectively. You can extend this suite of control commands by creating your own customized commands that perform some specific piece of work.

For a full list of the control commands, including a description of each, its associated GUID, the ArcGIS Engine Controls the command works with, and any extension required, see the article Built-in commands, menus, palettes, multi-items and toolsets.

Control Commands with the ToolbarControl

For applications using the ToolbarControl in conjunction with a buddy control, these commands can be added to the ToolbarControl in one of three ways:

• Through the ToolbarControl property pages at design-time
• Programmatically using the AddItem, AddMenuItem, and AddToolbarDef methods. The commands can be added to a ToolbarMenu using the AddItem and AddSubMenu methods, and the commands can be added to a ToolbarPalette using the AddItem method.
• By the end user if the ToolbarControl is in customize mode.

Control Commands without the ToolbarControl

While building applications with the ToolbarControl can quickly provide pieces of a framework similar to the ArcGIS Desktop application framework, there are times when the ToolbarControl is not required for an application: the visual appearance of the ToolbarControl may not match that of the application; the overhead of implementing Command objects for the ToolbarControl is not required; or there is an existing application framework present in the application.

The Control Commands can work directly with the MapControl, PageLayoutControl, GlobeControl and SceneControl by programmatically creating a new instance of a Command and passing either the MapControl, PageLayoutControl, GlobeControl and SceneControl to the ICommand::OnCreate method. The developer becomes responsible for calling ICommand::OnCreate and ICommand::OnClick methods at the appropriate times and reading properties on the ICommand interface to build up the user interface as follows:

• A new instance of a Command is created programmatically and the individual ArcGIS Control is passed to the OnCreate event. For example, if the Zoom FullExtent command is to work with the MapControl, the MapControl must be passed as the hook to the OnCreate method.
• A developer can use the CommandPool object without the ToolbarControl in order to manage the commands used by an application. The CommandPool will provide support for calling the OnCreate method of each command based on its Hook property.
• If the command only implements the ICommand interface you can call the OnClick method at the appropriate time to perform the specific action. If the command is a tool that implements both the ICommand and ITool interfaces you must set the tool to be the CurrentTool in the ArcGIS Control. The ArcGIS Control will send any keyboard and mouse events to the tool.
• A commands Enabled, Caption, and Bitmap properties can be read and set into the properties of a command button supplied by the development environment to build up the user interface of the application.

Dim pCommand As ICommand
Set pCommand = New esriControls.ControlsSelectFeaturesTool
pCommand.OnCreate MapControl1.Object
Set MapControl1.CurrentTool = pCommand

Dim pCommand As ICommand
pCommand = New ControlsSelectFeaturesTool
pCommand.OnCreate(AxMapControl1.Object)
AxMapControl1.CurrentTool = pCommand

ICommand command = new ControlsSelectFeaturesToolClass();
command.OnCreate(axMapControl1.Object);
axMapControl1.CurrentTool = (ITool) command;

Creating custom commands

Rather than adding code into an ICommand::OnCreate method to determine the type of hook passed to the command, the HookHelper, GlobeHookHelper and SceneHookHelper objects handles this.

• The HookHelper object is used to hold onto the hook and the IHookHelper interface it implements can return the ActiveView, PageLayout, and Map regardless of the type of hook that is passed.

• The GlobeHookHelper object is used to hold onto the hook and the IGlobeHookHelper interface it implements can return the Camera, Globe, GlobeDisplay and ActiveViewer regardless of the type of hook that is passed.
• The SceneHookHelper object is used to hold onto the hook and the ISceneHookHelper interface it implements can return the SceneViewer, Scene, SceneGraph and Camera regardless of the type of hook that is passed.

Public NotInheritable Class Command1
    Inherits BaseCommand

    Private m_pHookHelper As IHookHelper

    Public Overrides Sub OnCreate(ByVal hook As Object)
        If (m_pHookHelper Is Nothing) Then m_pHookHelper = New HookHelperClass
        m_pHookHelper.Hook = hook
    End Sub
End Class

public sealed class Command1 : BaseCommand
{
    private IHookHelper m_pHookHelper;

    public override void OnCreate(object hook)
    {
        if (m_pHookHelper == null) m_pHookHelper = new HookHelperClass();
        m_pHookHelper.Hook = hook;
    }
}

When a change is made to the HookHelper, GlobeHookHelper and SceneHookHelper objects the IHookHelperEvents::OnHookUpdated event is fired. For example, the event is fired in repsonse to the IToolbarControlEvents::OnBuddyChanged event and the IPageLayoutControlEvents::OnPageLayoutReplaced event. Use the event to re-synch any member variables storing IHookHelper, IGlobeHookHelper, and ISceneHookHelper properties, and to re-synch any event listeners such as IActiveViewEvents.

The HookHelper and GlobeHookHelper both implement the IHookActions interface, which provides methods to flash, pan or zoom, and create graphics, labels and callouts on the specified IPoint, IEnvelope, IPolyline and IPolygon objects. For example, the DoActionOnMultiple method could be used to zoom to the extent of the selected features in the Map.

Public Overrides Sub OnClick()
    Dim myArray As ESRI.ArcGIS.esriSystem.Array = New ESRI.ArcGIS.esriSystem.Array
    Dim selection As ISelection = m_pHookHelper.FocusMap.FeatureSelection
    Dim enumFeature As IEnumFeature = selection, feature As IFeature

    'Add the selected features geometry to the array
    enumFeature.Reset()
    feature = enumFeature.Next
    Do Until feature Is Nothing
        myArray.Add(feature.Shape)
        feature = enumFeature.Next
    Loop

    'If zooming is supported zoom to the selected features
    Dim hookActions As IHookActions = m_pHookHelper
    If (hookActions.ActionSupportedOnMultiple(myArray, esriHookActions.esriHookActionsZoom) = True) Then
        hookActions.DoActionOnMultiple(myArray, esriHookActions.esriHookActionsZoom)
    End If
End Sub

public override void OnClick()
{
    ESRI.ArcGIS.esriSystem.Array myArray = new ESRI.ArcGIS.esriSystem.Array();
    ISelection selection = m_pHookHelper.FocusMap.FeatureSelection;
    IEnumFeature enumFeature = (IEnumFeature)selection; IFeature feature;

    //Add the selected features geometry to the array
    enumFeature.Reset();
    feature = enumFeature.Next();
    do
    {
        myArray.Add(feature.Shape);
        feature = enumFeature.Next();
    }
    while (feature != null);

    //If zooming is supported zoom to the selected features
    IHookActions hookActions = (IHookActions) m_pHookHelper;
    if (hookActions.get_ActionSupportedOnMultiple(myArray, esriHookActions.esriHookActionsZoom) == true)
        hookActions.DoActionOnMultiple(myArray, esriHookActions.esriHookActionsZoom);
}

Singleton Objects

The are several singleton objects that only support one instance of the object within an application that are used by the Control Commands. You can make use of these objects in your own custom commands too.

• The CommandEnvironment object implements the IGraphicProperties and ILayerEffectProperties interfaces. The members of IGraphicProperties manage the default MarkerSymbol, LineSymbol and FillSymbol used by the Control Commands.
• The EngineEditor object implements the IEngineEditProperties, IEngineEditProperties2 and IEngineSnapEnvironment interfaces. The members of these interfaces manage the properties of edit sessions and snap agents.
• The EngineInkEnvironment object implements the IEngineInkEnvironment and IEngineInkEnvironmentEvents interfaces. The members of these interfaces manage the ink collection and manage tablet properties.
• The EngineNetworkAnalystEnvironment object implements the IEngineNetworkAnalystEnvironment, IEngineNetworkAnalystEnvironmentEvents and IEngineNetworkAnalystHelper interfaces. The members of these interfaces manage the collection of network layers, the current network layer, solving and getting directions.
• The MyPlaceCollection object implements the IEnumPlace and IPlaceCollection interfaces. The members of these interfaces manage the addition and removal of Place objects to the place collection.

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.

Loading Server Style Files

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.

A Style file is similar to a Server Style file, except is has a .Style extension rather than a .ServerStyle extension. Style files are available to ArcGIS Desktop products only, whereas 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) 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.

SymbologyControl1.LoadStyleFile "myInstallLocation\ArcGIS\Styles\ESRI.ServerStyle"

AxSymbologyControl1.LoadStyleFile("myInstallLocation\ArcGIS\Styles\ESRI.ServerStyle")

axSymbologyControl1.LoadStyleFile(@"myInstallLocation\ArcGIS\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 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.

Dim pServerStyleGalleryItem As IStyleGalleryItem
Set pServerStyleGalleryItem = SymbologyControl1.GetStyleClass(SymbologyControl1.StyleClass).GetSelectedItem
MsgBox pServerStyleGalleryItem.Name

Dim serverStyleGalleryItem As IStyleGalleryItem
serverStyleGalleryItem = AxSymbologyControl1.GetStyleClass(AxSymbologyControl1.StyleClass).GetSelectedItem()
System.Windows.Forms.MessageBox.Show(serverStyleGalleryItem.Name)

IStyleGalleryItem serverStyleGalleryItem = axSymbologyControl1.GetStyleClass(axSymbologyControl1.StyleClass).GetSelectedItem();
System.Windows.Forms.MessageBox.Show(serverStyleGalleryItem.Name);

When the contents of a server style file is loaded into the SymbologyControl with 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.