Scenarios and samples  

Creating an extension

This topic is relevant for the following:
Product(s): ArcGIS Desktop: All
Version(s): 9.2, 9.3
Language(s): Visual Basic 6
Experience level(s): All



In this topic

  1. Project description
  2. Concepts
  3. Requirements
  4. Additional resources
  5. Implementation

Project description

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.

Concepts

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.

Requirements

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.

Additional resources

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.

Implementation

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

  1. Start Visual Basic 6.

  2. Open the CommandsExtension project from the location you unzipped it to.

  3. 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.

  1. In the project window, right-click and click Add > Class Module. The Add Class Module dialog box appears.

  2. 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.

  3. Display the project properties for this class by clicking it in the Project window and pressing F4.

  4. Change the name of the class to Extension and make sure the instancing property is set to 5—Multiuse.

  5. 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.

  1. In VB6, click to display the empty Extension class Code window.

  2. Click Add-Ins > ESRI Interface Implementer. The ESRI Interface Implementer dialog box is displayed.

  3. In the dialog box, click Options and uncheck the Generate Error Handlers item.

  4. Click IExtension from the Application pulldown menu.

  5. 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.

[Visual Basic 6]
Option Explicit

Implements IExtension
Implements IExtensionConfig

Private m_pApp As IApplication
Private m_ExtensionState As esriExtensionState

Private Property Get IExtension_Name() As String
  ' Internal name of the extension
  IExtension_Name = "CommandExtension"
End Property

Private Sub IExtension_Startup(ByRef initializationData As Variant)
  ' Set the ArcMap application interface
  If (TypeOf initializationData Is IMxApplication) Then
    Set m_pApp = initializationData  ' Is ArcMap
  End If
End Sub

Private Sub IExtension_Shutdown()
  ' Release interface pointers
  Set m_pApp = Nothing
End Sub
Private Property Get IExtensionConfig_ProductName() As String
  ' Name in Extension Manager Dialog
  If (m_pApp Is Nothing) Then Exit Property
  IExtensionConfig_ProductName = "ArcMap Command Extension"
End Property

Private Property Get IExtensionConfig_Description() As String
  ' Description in Extension Manager Dialog
  If (m_pApp Is Nothing) Then Exit Property
IExtensionConfig_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 Get IExtensionConfig_State() As esriExtensionState
  ' Get the extension state
  If (m_pApp Is Nothing) Then Exit Property
  IExtensionConfig_State = m_ExtensionState
End Property

Private Property Let IExtensionConfig_State(ByVal ExtensionState As esriExtensionState)
  ' Set the extension state according to the check box in the ExtensionManager Dialog
  If (m_pApp Is Nothing) Then Exit Property
  m_ExtensionState = ExtensionState
End Property

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.

  1. In the ZoomIn class, declare a module-based variable to reference the extension state.

    [Visual Basic 6]
    Private m_pCommandExtension As IExtensionConfig
  2. Set the variable to Extension in the command's OnCreate method.

    [Visual Basic 6]
    Private Sub ICommand_OnCreate(ByVal hook As Object)
    	  If (TypeOf hook Is IMxApplication) Then  ' ArcMap
    	  Set m_pApp = hook
    	  Set m_pCommandExtension = m_pApp.FindExtensionByName("CommandExtension")
    	  End If
    	End Sub
  3. Set the Enabled property based on the extension state.

    [Visual Basic 6]
    Private Property Get ICommand_Enabled() As Boolean
    	  ' Check box in Extension Manager dialog box controls command enabled property
    	  If (Not m_pCommandExtension Is Nothing) Then
    	    If (m_pCommandExtension.State = esriESEnabled) Then
    	      ICommand_Enabled = True
    	    Else
    	      ICommand_Enabled = False
    	    End If
    	  Else
    	    ICommand_Enabled = False
    	  End If
    	End Property

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.

  1. 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.

For help using the Component Category Manager, see the topic Developing with ArcObjects.

You can make this step semiautomatic, making deployment much easier for you and users, by utilizing the ESRI Compile and Register add-in.

  1. In VB6, click Add-Ins > ESRI Compile and Register. The ESRI Compile and Register dialog box appears.

  2. In the Classes pane, click Extension; in the Component Categories pane, click ESRI Mx Extensions.

  3. In the Classes pane, click Toolbar; in the Component Categories pane, click ESRI Mx CommandBars.

  4. In the Classes pane, click ZoomIn; in the Component Categories pane, click ESRI Mx Commands.

  5. In the Classes pane, click ZoomOut; in the Component Categories pane, click ESRI Mx Commands.

  6. 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.

  1. Start ArcMap.

  2. 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.

  3. Open the Extensions dialog box via Tools > Extensions. The Extensions dialog box will be displayed.

  4. Click the ArcMap Command Extension item and read the description in the lower pane.

  5. Check the item and close the dialog box.

You should now see the two tools enabled.

Deployment

The resulting DLL can easily be deployed to other machines using the methods described in Licensing and deploying your solutions.