Using the Winforms ArcGIS Engine controls

---

Each ArcGIS control is an embeddable component that can be dropped into a container form or onto a dialog box provided by a visual design environment. The ArcGIS Engine controls can be embedded into an existing application to add two-dimensional (2D) or three-dimensional (3D) mapping capability, or used to create a stand-alone application. Once in a container, each ArcGIS control can be resized and repositioned with other embeddable components, such as command buttons and combo boxes, to provide a user interface (UI) in the application.

The LicenseControl is visible within a visual design environment but is invisible at run time, so unlike the other ArcGIS Engine controls, the LicenseControl does not provide a UI 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 the control and click Properties. These property pages provide shortcuts to a selection of a control's properties and methods, and allow you to build an application with little or no code.

For more information on how to use the property pages to build fully functional applications, see the following topics:

Each ArcGIS control simplifies the development process by encapsulating coarse-grained ArcObjects, while still providing access to finer-grained ArcObjects. For example, PageLayoutControl encapsulates the PageLayout object. This is the same PageLayout coclass found inside the ArcMap application. 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, IMapControl 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, IMapControl has an AddShapeFile method. The ArcGIS Engine controls are typically a starting point for developing applications not only because they provide UIs but also because they provide 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 and dropped over the MapControl, the OnOleDrop event is fired.

An individual ArcGIS control can be embedded into an application, or TOCControl and ToolbarControl can be used with another ArcGIS control to provide part of the application's framework. 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 through 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. See the following code example:

axTOCControl1.SetBuddyControl(axGlobeControl1);
axToolbarControl1.SetBuddyControl(axGlobeControl1);

AxTOCControl1.SetBuddyControl(AxGlobeControl1)
AxToolbarControl1.SetBuddyControl(AxGlobeControl1)

ArcGIS for Desktop applications can be used to pre-author documents that can be loaded into the ArcGIS Engine controls to quickly produce high-quality mapping. For example, use ArcMap 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. Pre-authoring documents can save a substantial amount of time, as it eliminates the need to programmatically create maps, renderers, and symbols as well as to 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 following table summarizes the types of documents 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 permission to load in a customized application and unrestricted access to its contents	Yes	Yes	No	No
1There are no properties directly on this ArcGIS control to load layer files (.lyr); however, they can be loaded indirectly via the MapDocument object.