In this topic
This scenario is for ArcGIS Desktop developers who want to create an extension. The example used in this scenario is a simple extension that enables some tools on an existing toolbar.
The emphasis in this scenario is how you create the components that plug into the framework rather than any particular ArcObjects solution.
Extensions provide the developer with a powerful mechanism for extending the core functionality of the ArcGIS applications. An extension can provide a toolbar with new tools, listen for and respond to events, perform feature validation, and so on.
Extensions act as a central point of reference for developers when they are creating commands and tools for use within the applications. Often these commands and tools must share data or access common UI components. An extension is the logical place to store this data and develop the UI components. The main reason for this is that there is only ever one instance of an extension per running application and, given an IApplication interface, it is always possible to locate the extension and work with it.
Any extension that is registered with an application is automatically loaded and unloaded by the application; the end user does nothing to load or unload. For example, an extension that has been added to the ESRI Mx Extensions component category will be started when ArcMap is started and will be shut down when ArcMap is shut down.
To create your own extension, implement the IExtension interface. This interface allows you to set the name of the extension and specify what action takes place when the extension is started or shut down.
If you want your extension to be exposed in the Extensions dialog box, you should implement the IExtensionConfig interface. The Extensions dialog box allows users to turn extensions on and off. The IExtensionConfig interface provides the Extension dialog box with the name of the extension and a description of the extension; it also specifies the state of the extension.
The IExtensionConfig interface is independent of ESRI's licensing approach, so as a developer, you can incorporate a custom licensing solution. Alternatively, if your extension doesn't work with a license manager, you don't have to worry about requesting and releasing a license. You can implement IExtensionConfig to enable and disable the tools on your extension's toolbar accordingly.
For additional information on extensions and their use in extending the desktop applications, see the discussion about Extending the User Interface in the Extending ArcObjects section.
The requirements for working through this scenario are that you have ArcGIS Desktop installed and running.
The IDE used for this example is Visual Basic 6, and all IDE-specific steps will assume this is the IDE you are using.
It is also recommended that you read the information about working with Visual Basic in the within Programming against ArcObjects with COM section.
The completed code for this scenario can be found in ArcGIS Developer Help under ArcGIS Desktop > Developer Guide > Developer Scenarios and on disk in the \DeveloperKit\samples\Developer_Guide_Scenarios\Commands_and_ExtensionsVisual_Basic zip file.
In this example you will create an extension for ArcMap that enables controls on a toolbar. The code for the toolbar, controls, and extension all reside in a single project. The project for containing the toolbar has already been provided; this scenario will add the extension code.
The code for this example is written in Visual Basic 6.
Before you begin this exercise, browse to the \DeveloperKit\samples\Developer_Guide_Scenarios directory under your ArcGIS install directory and unzip the Commands_and_ExtensionsVisual_Basic file to your local machine. You will use resources in this file during the following exercise.
Opening the existing project
- Start Visual Basic 6.
- Open the CommandsExtension project from the location you unzipped it to.
- Take some time to examine the project and the classes that create the toolbar, zoom in, and zoom out tools. Compare this with the VB .NET code from the previous scenario.
Creating a new class for the extension
You need to create a new class for the extension code. All components that plug into the desktop framework are required to be classes. The UI controls that you see in ArcGIS Desktop are instances of these classes.
- In the project window, right-click and click Add > Class Module. The Add Class Module dialog box appears.
- On the New tab in the Add Class Module dialog box, click Class Module and click OK. A new empty class called class1 is created.
- Display the project properties for this class by clicking it in the Project window and pressing F4.
- Change the name of the class to Extension and make sure the
instancing property is set to 5Multiuse.
- Save the extension class by right-clicking the class in the Project window and clicking Save.
Implementing extension interfaces
You now need to implement the IExtension and IExtensionConfig interfaces in the Extension class. The easiest way to do this is to use the ESRI Interface Implementer add-in.
- In VB6, click to display the empty Extension class Code window.
- Click Add-Ins > ESRI Interface Implementer. The ESRI Interface Implementer dialog box is displayed.
- In the dialog box, click Options and uncheck the Generate Error Handlers item.
- Click IExtension from the Application pulldown menu.
- Click IExtensionConfig from the lower window and click OK to close the dialog box.
The ESRI Interface Implementer adds the Implements statement and stubs out all the members of those interfaces in the Code window. It will also add the appropriate library references to the project if they don't exist.
If you don't use the add-in, you will have to manually add the project references, type in the Implements statement, and manually stub out each interface member in the Code window.
Adding to the Extension class
Add the following code to the procedures in the Extension class.
Option Explicit ImplementsIExtension
Private Property GetIExtension_Name()
' Internal name of the extensionIExtension_Name = "CommandExtension"
End Property Private SubIExtension_Startup(
' Set the ArcMap application interface
Then Setm_pApp = initializationData
' Is ArcMap
End If End Sub Private SubIExtension_Shutdown()
' Release interface pointers
Nothing End Sub Private Property GetIExtensionConfig_ProductName()
' Name in Extension Manager Dialog
Then Exit PropertyIExtensionConfig_ProductName = "ArcMap Command Extension"
End Property Private Property GetIExtensionConfig_Description()
' Description in Extension Manager Dialog
Then Exit PropertyIExtensionConfig_Description = "ArcMap Command Extension Version 1.0 " & vbCrLf & _ "Copywrite/Company/Date" & vbCrLf & vbCrLf & "Controls the enabled property of zoom in and out commands."
End Property Private Property GetIExtensionConfig_State()
' Get the extension state
Then Exit PropertyIExtensionConfig_State = m_ExtensionState
End Property Private Property LetIExtensionConfig_State(
' Set the extension state according to the check box in the ExtensionManager Dialog
Then Exit Propertym_ExtensionState = ExtensionState
Enabling the ZoomIn tool with the extension
The ZoomIn class needs to be modified to listen to the extension configuration state. When the extension is turned on, the tool will be enabled.
- In the ZoomIn class, declare a module-based variable to reference the
[Visual Basic 6]
- Set the variable to Extension in the command's
[Visual Basic 6]
Setm_pApp = hook
Setm_pCommandExtension = m_pApp.FindExtensionByName("CommandExtension")
End If EndSub
- Set the Enabled property based on the extension state.
[Visual Basic 6]
Private Property GetICommand_Enabled()
' Check box in Extension Manager dialog box controls command enabled property
Then If(m_pCommandExtension.State = esriESEnabled)
True ElseICommand_Enabled =
False End If ElseICommand_Enabled =
False End If EndProperty
The same steps should be applied to the ZoomOut class to enable the ZoomOut tool based on the extension state.
Compiling the project
You are now ready to compile your project.
- In VB6, click File, then click Make CommandsExtensions.dll.
This creates a single DLL that you can deploy. The next step is to register the DLL with the operating system, then use the Component Category Manager to place the individual components within the DLL into the correct component categories, for example, the ZoomIn and ZoomOut classes are registered with the MxCommands component category, and so forth.
You can make this step semiautomatic, making deployment much easier for you and users, by utilizing the ESRI Compile and Register add-in.
- In VB6, click Add-Ins > ESRI Compile and Register. The ESRI Compile and Register dialog box appears.
- In the Classes pane, click Extension; in the Component Categories pane, click ESRI Mx Extensions.
- In the Classes pane, click Toolbar; in the Component Categories pane, click ESRI Mx CommandBars.
- In the Classes pane, click ZoomIn; in the Component Categories pane, click ESRI Mx Commands.
- In the Classes pane, click ZoomOut; in the Component Categories pane, click ESRI Mx Commands.
- Click Compile, click Read, and click OK on the dialog boxes that follow.
This add-in creates a Windows registry merge file, CommandsExtensions.reg, that can register the components in the correct component categories.
To register the components using the merge file, first register the DLL with the operating system if you have not done so already, then right-click the .reg file and click Merge.
Using the extension in ArcMap
You are now ready to use the extension in ArcMap.
- Start ArcMap.
- Add the ArcMap Command Extension toolbar either through the Customize dialog box or by right-clicking an empty area of the ArcMap frame and clicking the ArcMap Command Extension toolbar item. The toolbar will appear with the two tools. These will be disabled.
- Open the Extensions dialog box via Tools > Extensions. The Extensions dialog box will be displayed.
- Click the ArcMap Command Extension item and read the description in the lower pane.
- Check the item and close the dialog box.
You should now see the two tools enabled.
The resulting DLL can easily be deployed to other machines using the
methods described in Licensing and deploying your solutions.