Supported with:
Additional library information: Contents, Object Model Diagram
See the following sections for more information about this namespace:
- ArcGIS for Desktop Basic
- ArcGIS for Desktop Standard
- ArcGIS for Desktop Advanced
Additional library information: Contents, Object Model Diagram
The Framework library provides core components and software interfaces to support user interface (UI) 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 the Framework library that you can use when creating UIs for inclusion in an ArcGIS application—ComPropertySheet and MouseCursor are two examples—along with a set of dialog objects that support common UI operations in an ArcGIS application—ColorSelector, SymbolPickerDialog, and NumberDialog are three commonly used dialog objects.
The Framework library defines the software interfaces that you use when creating UIs for extending the ArcGIS system using property pages and dockable windows.
The Framework library is not extended by the developer; however, by implementing interfaces defined in the library, you can extend the ArcGIS architecture with UI components.
See the following sections for more information about this namespace:
Objects
Application
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 in the Framework library is an abstract class for the application. The interfaces shown here are those that are common to all the ArcGIS applications. Each 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 a number of properties including the following:
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.
The Application object implements the IVbaApplication interface, which allows you to programmatically insert, remove, and run Visual Basic for Applications (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.
Document
The Document object in the Framework library 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. Although ArcCatalog doesn't use documents, it has a document object associated with it called GxDocument. The document object in ArcScene is called SxDocument, and the document object in ArcGlobe is called GMxDocument.
The document object provides access to the UI 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 VBA project.
Templates
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—UI, 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. An ArcScene or ArcGlobe document is based on the Normal template; there are always two items 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 as well as the pathnames of those templates.
Accelerator
The Accelerator object is a mapping between a particular keyboard combination and a command or tool. When you press the combination of keys on the keyboard, the command is executed or the tool is activated. For example, Ctrl-C is a well-known accelerator for copying 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.
AcceleratorTable
The AcceleratorTable object contains a list of accelerator keys and the command identifiers associated with them. The IAcceleratorTable interface is used to add or find accelerators in AcceleratorTable. You can get a reference to the AcceleratorTable of a document using the IDocument.Accelerators property.
Dockable windows
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 unique identifier (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 the following methods:
- IsVisible—Indicates if the dockable window is visible
- Show—Displays or hides the window
- Dock—Docks the window in a particular location on the application
Use the IWindowPosition interface to size and position a dockable window.
To create your own dockable window, implement the IDockableWindowDef interface. This interface allows you to set properties such as Caption and Name. The ChildHWND property defines what the window will consist of by passing in an hWnd of a control, such as a form, list box, 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 dockable window.
Command bars
A CommandBar object represents a toolbar, menu bar, menu, or context menu. With the ICommandBar interface, you can modify a command bar in various ways, such as by adding a command, menu, or macro item to it.
The CommandBars collection object 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.
Custom toolbars and menus
There are two basic types of custom command bars that you can create: document command bars and Component Object Model (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 dynamic-link library (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 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 (also 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 the 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 Customize dialog box), implement both IMenuDef and IRootLevelMenu. IRootLevelMenu is an indicator interface that is used only to indicate to the application that the menu should be treated as a root menu.
Commands
The CommandItem class represents any item on a command bar. For example, button, tools, and menu items that appear on command bars are all command items. The ICommandItem interface allows you to get or set the properties of the command item such as caption, status bar message, tooltip, display style, help context ID, and more. You can obtain a reference to the command on which the item is based. The ICommandItem interface also provides methods to execute, delete, refresh, and reset the command item. Use either ICommandBar.Find or ICommandBars.Find to obtain a reference to a particular command item.
Custom commands
As a developer, you may want to add functionality to the ArcGIS applications by creating custom commands. Similar to custom command bars, there are two basic types of commands you can create: COM commands and document commands.
COM commands
The term COM command is used here to refer to the type of commands you create by implementing interfaces and compiling into DLLs. You can create the following types of commands:
- Buttons and menu items—The simplest types of commands. Buttons generally appear as icons on toolbars and menu items appear in menus. A simple action is performed when the button or menu item is clicked.
- Tools—Similar to buttons, tools also require interaction with the application's display. The Zoom In command is an example of a tool—you click or drag a rectangle over a map before the display is redrawn to show the map contents in more detail.
- Tool controls—Commands that act like combo boxes or edit boxes. Combo boxes let you choose an option from a drop-down list. For example, in ArcMap, you can choose the layers from which you are selecting features when working with a map. Edit boxes are editable text boxes where you can type in text.
- A MultiItem object is a dynamic command that appears when there are zero or more adjacent menu items on a menu, depending on the state of the application.
- A subtyped command object is a group of related commands that can share properties.
To create a custom COM command, you need to implement some of the ArcObjects interfaces that support commands, such as those listed here from the SystemUI library:
Document commands
Macro items and UIControls are document commands that can be created using the Customize dialog box and the Visual Basic Editor in the ArcGIS applications. These VBA-based document commands are stored in a specific document or template and can only be used in that document or template.