Working with the widgets

This group of articles outlines important tasks and functionality of the ArcGIS Engine controls, including 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.

Some themes and concepts common across all the controls are highlighted below.

Before discussing the details of each of the controls, there are some common themes and concepts that should be understood in order to effectively build applications using them.

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.

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 control’s properties and methods and allow a developer to build an application with little or no code.

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.

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.

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.

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.

	MapControl	PageLayoutControl	GlobeControl	SceneControl
Map document (*.mxd, *.mxt)	Yes	Yes	No	No
Layer files (*.lyr)	Yes	Yes1	No	No
Globe document (*.3dd, *.sdt)	No	No	Yes	No
Scene Document (*.sxd, *.sxt)	No	No	No	Yes
Published map files (*.pmf) with no permission to load in a customized application or restricted access to its contents	No	No	No	No
Published map files (*.pmf) with permission to load in a customized application and unrestricted access to its contents	Yes	Yes	No	No

¹ There are no properties available on the ArcGIS controls to directly load Layer (.lyr) files. However, they can be loaded indirectly via the MapDocument object.