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
The Framework library provides core components and software interfaces to support user interface components and the ArcGIS applications. A number of the objects in the Framework library are used internally by the ArcGIS applications to support their customization environment. There are a number of helper objects in Framework that developers can use when creating user interfaces for inclusion in one of the ArcGIS applications; ComPropertySheet, ModelessFrame, MouseCursor are three examples, along with a set of dialogs that support common UI operations within an ArcGIS application; ColorSelector, NumberDialog, are 2 commonly used dialogs.
The Framework library defines the software interfaces that developers use when creating user interfaces for extending the ArcGIS system using property pages and dockable windows.
The Framework library is not extended by the developer, but by implementing interfaces defined in the library developers can extend the ArcGIS architecture with UI components.
The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:
The Application object is the core object that represents an ArcGIS application (ArcMap, ArcCatalog, or other). Through this object, you can access properties and methods for the application and navigate to other elements, such as the document, window handle, and status bar.
The Application object represented here in the Framework library is an abstract class for the application. The interfaces shown here are those that are common to all of the ArcGIS applications. Each running ArcGIS application is represented by an instance of an Application object—ArcCatalog by Application from the ArcCatalog library, and ArcMap by Application in the ArcMap library, for example.
The Application object's primary interface is IApplication. This interface provides access to the Document object, the StatusBar object, the Templates object, the currently selected tool, and the Visual Basic Editor. There are several methods that allow you to open, save, and print documents, lock and unlock the application from user customizations, display dialogs, and exit the application. When working within the integrated VBA environment, the Application object is exposed globally. That means you can directly access the properties and methods of the application from any routine without first obtaining a reference to that object.
The Application object implements the IVbaApplication interface, which allows you to programmatically insert, remove, and run VBA code without actually opening the Visual Basic Editor.
The IWindowPosition interface has methods to move and resize a window. Any window object can implement this interface. All the ArcGIS application windows implement this interface.
The Templates object is a collection of the templates that are currently loaded in the application. A template is a document that is used as a starting point for creating new documents. It carries customizations of several types—user interface, VBA project, and application-specific data. ArcMap has two or three templates loaded with an application. If the document is based on the Normal template, two items are in the templates collection. If the document is based on a project template, three items are in the templates collection. ArcCatalog always has one item in the templates collection; this item represents Normal.gxt. The ITemplates interface allows you to get a count of the loaded templates and get the pathnames of those templates.
This Document object only represents the generic document properties common to all ArcGIS applications. Each application has its own document object. The document object in ArcMap is called MxDocument; for further discussion, see the ArcMapUI library. The document object in ArcCatalog is called GxDocument; for further discussion, see the ArcCatalog library. Even though ArcCatalog doesn't use documents, it has a document object associated with it. The document provides access to the user interface elements and the VBA project. Use the Document property of the IApplication interface to get a reference to the document. The IDocument interface provides access to the document's title, type, accelerator table, command bars collection, parent application, and Visual Basic for Applications project.
An Accelerator is a mapping between a particular keyboard combination and a command. When you press the combination of keys on the keyboard, the command is executed. For example, Ctrl-C is a well-known accelerator for copying something in Windows. Some commands in the application already have accelerators assigned to them but you can also assign additional accelerators to these commands. The IAccelerator interface defines the properties of an accelerator. Use the IAcceleratorTable.Add method to create an accelerator.
The AcceleratorTable is an object that contains a list of accelerator keys and the command identifiers associated with them. The IAcceleratorTable interface is used to add or find accelerators in an AcceleratorTable. You can get a reference to the AcceleratorTable of a document using IDocument.Accelerators.
A dockable window is a window that can exist in a floating state or be attached to the main application window. The Table of Contents in ArcMap and the Tree View in ArcCatalog are examples of dockable windows. The Application object implements the IDockableWindowManager interface that is used to get access to a particular dockable window. The GetDockableWindow method finds a dockable window using the UID of the dockable window. You can use the IDockableWindow interface to query the properties of a dockable window such as the Caption, Name, and ID. This interface also has methods to return whether the window is currently visible, to display the window, and to dock the window in a particular location on the application. Use the IWindowPosition interface to size and position your dockable window.
To create your own dockable window, implement the IDockableWindowDef interface. This interface allows you to set properties, such as caption and name. You use the ChildHWND property to define what the window will consist of by passing in an hWnd of a control, such as a form, listbox, and so on.
The class you create is a definition for a dockable window; it is not actually a dockable window object. Once your class is registered in one of the dockable window component categories, the application uses the definition of the dockable window in your class to create the actual dockable window.
A CommandBar object represents a toolbar, a menubar, menu, or a context menu. With the ICommandBar interface you can modify a command bar such as adding a command, menu, or macro item to it.
CommandBars is a collection of the command bars associated with a document. The ICommandBars interface allows you to set properties for the command bars and to create, find, or hide command bars. Use IDocument.CommandBars to get a reference to the command bars collection.
There are two basic types of custom command bars that you can create—document command bars and COM command bars. Document command bars can be created using built-in functionality in the applications. COM command bars can be created by implementing menus or toolbars in any COM-compliant language and compiling them into a DLL.
You can create custom document command bars using the Customize dialog box in the ArcGIS applications. To create a custom toolbar, use the New button on the Toolbars panel. To create a custom menu, go to the New Menu category on the Commands panel and drag the New Menu command to any toolbar or menu. These types of toolbars and menus are stored in a specific document or template and can only be used in that document or template.
The command bars collection uses command bar definitions (either ToolBarDef or MenuDef) to create command bars. For example, a class that implements IToolbarDef is only a definition for a toolbar; it is not actually a toolbar object. Once this class is registered in one of the command bar component categories, the command bars collection uses the definition of the toolbar in your class to create the actual command bar.
To create a custom toolbar, implement IToolbarDef found in the SystemUI library. The IToolbarDef interface is used to define the properties of a custom toolbar. You can set the caption and name of the toolbar and specify what command items are on the toolbar.
To create a custom menu, implement IMenuDef found in the SystemUI library. The IMenuDef interface is identical to the IToolbarDef interface except that it is used to indicate to the application that this is a menu. If you are creating a context menu, implement both IMenuDef and IShortcutMenu. IShortcutMenu is an indicator interface that is used only to indicate to the application that this menu should be treated as a context menu. If you are creating a root menu (a menu that will appear in the Menus command category in the the Customize dialog box), implement both IMenuDef and IRootLevelMenu. IRootLevelMenu is an indicator interface that is used only to indicate to the application that this menu should be treated as a root menu.
A CommandItem is any item on a command bar. For example, button, tools, and menu items that appear on command bars are all commanditems. The ICommandItem interface allows you to get or set the properties of the commanditem such as caption, button image, statusbar message, tooltip, display style, help context ID, and more. You can obtain a reference to the command on which this item is based. The ICommandItem interface also provides methods to execute, delete, refresh, and reset the commanditem. Use either ICommandBars.Find or ICommandBar.Find to obtain a reference to a particular commanditem.
As a developer you may want to add functionality to the ArcGIS applications by creating custom commands. There are three basic types of commands that you can create:
The term COM command is used here to refer the type of commands you create by implementing interfaces and compiling into dlls. You can create the following types of commands:
A subtyped command object is a group of related commands that can share properties.
To create a custom COM command you would implement some of the ArcObjects interfaces that support commands such as SystemUI.ICommand, SystemUI.ITool, SystemUI.IToolControl, SystemUI.ICommandSubType, and SystemUI.IMultiItem. Refer to the SystemUI library for more information on these interfaces.
Macro Items are VBA-based commands. This means that they are created using the Visual Basic environment that is embedded in the applications. Macros are simple Sub procedures written in the Visual Basic Editor. Macro items can be created from these macros by dragging them onto any toolbar.
UIControls are also VBA-based. To create a new UIControl, use the Customize dialog box in the ArcGIS applications. You can create the following types of UIControls: