Creating a simple command

Terminology

Create a new class library

1. Open Visual Studio.
2. Click File, then New, and then Project.
3. Select the Visual C++ Folder and then the ATL sub folder. Click ATL Project, then enter the project name and location of the source files. The project name will be the name given to the project directory and COM Server file. Click OK.
   Project Wizard. This example uses the project name Walkthrough1VC8.
4. On the next dialog box, select "Application Settings" in order to view the settings.
   Project Wizard. Choosing the settings for the application.

5. The Solution tab in the workspace window will show that a C++ file (.cpp) has been created for the COM server, along with files to support precompiled header files and resources. The file has a module attribute that causes the following dll's to be automatically implemented for you:
   • DllMain
   • DllRegisterServer
   • DllUnregisterServer
     

Create a zoom-in command

1. With the COM Server code present the ATL COM objects can be added. This is done using the ATL Object wizard. Right click on the projectname "WalkthroughVC8" in the Solution tab in the workspace and then click Add and then Add Class... Select the ATL sub folder and then click on ATL Simple object. Click Add to define a simple object.
   
   ATL Object Wizard.
2. Give the object a name and confirm that the automatically generated names are concise but informative.
   
   Name allocation of the ATL Object Wizard. This example names the coclass ZoomIn.
3. Click the Options tab and set the Interface type to Custom. This ensures that the interface IZoomIn inherits directly from IUnknown and not IDispatch, which is the default - in this way it is the same as all the other ArcObjects interfaces. While this is not necessary, it reduces the size of the COM object when it is instantiated for better memory management.
   
   Object Properties Wizard. Defining the characteristics of your COM object.
4. Click Finish when finished. This creates two new files, ZoomIn.cpp and ZoomIn.h.

// IZoomIn
[object, uuid("297E96B4-D481-47C3-AEEB-CD526016DFDA"), helpstring(
  "IZoomIn Interface"), pointer_default(unique)]

// CZoomIn

[coclass, default(IZoomIn), threading(apartment), vi_progid(
  "Walkthrough1VC8.ZoomIn"), progid("Walkthrough1VC8.ZoomIn.1"), version(1.0),
  uuid("C77B6C59-2A8A-4E0C-9877-5FEA1F4C02B4"), helpstring("ZoomIn Class")
  ]class ATL_NO_VTABLE CZoomIn: public IZoomIn

5. Confirm that everything has been successful by building the solution.

Reference the ESRI object libraries

#pragma warning(push)
#pragma warning(disable : 4192) 
  //disables warning: automatically excluding 'name' while importing type library 'library'

//import esriSystem.olb
#import "libid:5E1F7BC3-67C5-4AEE-8EC6-C4B73AAC42ED" raw_interfaces_only
  raw_native_types no_namespace named_guids exclude("OLE_COLOR", "OLE_HANDLE", 
  "VARTYPE")

//import esriSystemUI.olb
#import "libid:4ECCA6E2-B16B-4ACA-BD17-E74CAE4C150A" raw_interfaces_only
  raw_native_types no_namespace named_guids exclude("OLE_HANDLE", "OLE_COLOR")

//import esriGeometry.olb
#import "libid:C4B094C2-FF32-4FA1-ABCB-7820F8D6FB68" raw_interfaces_only
  raw_native_types no_namespace named_guids exclude("OLE_HANDLE", "OLE_COLOR", 
  "ISegment")

//import esriDisplay.olb
#import "libid:59FCCD31-434C-4017-BDEF-DB4B7EDC9CE0" raw_interfaces_only
  raw_native_types no_namespace named_guids exclude("OLE_HANDLE", "OLE_COLOR")

//import esriGeoDatabase.olb
#import "libid:0475BDB1-E5B2-4CA2-9127-B4B1683E70C2" raw_interfaces_only
  raw_native_types no_namespace named_guids

//import esriCarto.olb
#import "libid:45AC68FF-DEFF-4884-B3A9-7D882EDCAEF1" raw_interfaces_only
  raw_native_types no_namespace named_guids exclude("UINT_PTR")

//import esriControls.olb
#import "libid:033364CA-47F9-4251-98A5-C88CD8D3C808" raw_interfaces_only
  raw_native_types no_namespace named_guids

#pragma warning(pop)

Implement the ICommand interface

1. Click the Class View tab in the Workspace browser on the left of the Visual Studio window.
2. Select the class CZoomIn and display the right-click context menu.
   
   Select Add and then click Implement Interface. This opens the Implement Interface Wizard.
3. Select Implement Interface from: Registry.
   
   From the Available type libraries combo box select ESRI SystemUI Object Library, which defines the ICommand interface.
4. From the Interfaces window select the ICommand interface and move it to the Implement interfaces window using the arrow button. Click Finish.
   
   
   Interface Implementation Wizard.The ICommand interface has been selected from the ESRI SystemUI Object Library.
   
   The wizard adds inherited methods of the ICommand interface that is implemented by CZoomIn. These methods should be moved to the CPP file, leaving only the function prototypes in the header file. The listing below shows the changes required for each function.
   
   The wizard creates this function in the header file.

STDMETHOD(get_Enabled)(VARIANT_BOOL *Enabled)
{
  return E_NOTIMPL;
}

STDMETHOD(get_Enabled)(VARIANT_BOOL *Enabled);

STDMETHODIMP CZoomIn::get_Enabled(VARIANT_BOOL *Enabled)
{
  if (Enabled == NULL)
    return E_POINTER;

  return E_NOTIMPL;
}

Adding a Bitmap

1. In the Resource View of the workspace window right click the project Walkthrough1VC8, select Add and then click Add Resource.
   
   
   
2. Click the import button and navigate to the .bmp file you wish to use as the ZoomIn icon. There is a suitable file in the \Bin\Icons directory of your ArcGIS install called Zoom_in_tool_2.bmp. Copy this into your project, typically these resources go in a "res" subfolder of the project. Click Open when finished. Using the properties for the resource, set the name of the resource to "IDB_ZOOMIN". Add the following member variable to the ZoomIn.h header file.

private:
  HBITMAP m_hBitmap;

CZoomIn::CZoomIn()
{
  m_hBitmap=::LoadBitmap(_AtlBaseModule.GetResourceInstance(),
    MAKEINTRESOURCE(IDB_BITMAP2));
}

CZoomIn::~CZoomIn()
{
  DeleteObject(m_hBitmap);
}

IHookHelperPtr m_ipHookHelper;

STDMETHODIMP CZoomIn::get_Enabled(VARIANT_BOOL *Enabled)
{
  if (Enabled == NULL)
    return E_POINTER;

  *Enabled=VARIANT_TRUE; // Enable the tool always

  return S_OK;
}

STDMETHODIMP CZoomIn::get_Name(BSTR *Name)
{
  if (Name == NULL)
    return E_POINTER;

  *Name=::SysAllocString(L "ZoomIn x 0.5 VC8");
  return S_OK;
}

STDMETHODIMP CZoomIn::get_Caption(BSTR *Caption)
{
  if (Caption == NULL)
    return E_POINTER;

  *Caption=::SysAllocString(L "ZoomIn x 0.5 VC8");
  return S_OK;
}

STDMETHODIMP CZoomIn::get_Category(BSTR *Category)
{
  if (Category == NULL)
    return E_POINTER;

  *Category=::SysAllocString(L "Developer Samples");
  return S_OK;
}

STDMETHODIMP CZoomIn::get_Bitmap(OLE_HANDLE *Bitmap)
{
  if (Bitmap == NULL)
    return E_POINTER;

  *Bitmap=(OLE_HANDLE)m_hBitmap;

  return S_OK;
}

STDMETHODIMP CZoomIn::OnCreate(IDispatch *hook)
{
  m_ipHookHelper.CreateInstance(CLSID_HookHelper);
  HRESULT hr=m_ipHookHelper->putref_Hook(hook);

  return hr;
}

STDMETHODIMP CZoomIn::OnClick()
{
  // HRESULT checking omitted for clarity
  IActiveViewPtr ipActiveView;
  m_ipHookHelper->get_ActiveView(&ipActiveView);

  IEnvelopePtr ipEnv;
  ipActiveView->get_Extent(&ipEnv);
  ipEnv->Expand(0.5, 0.5, VARIANT_TRUE);
  ipActiveView->put_Extent(ipEnv);
  ipActiveView->Refresh();

  return S_OK;
}

Adding COM category registration functionality

[coclass, threading("apartment"), vi_progid("Walkthrough1VC8.ZoomIn"), progid(
  "Walkthrough1VC8.ZoomIn.1"), version(1.0), uuid(
  "E86E1877-82F5-4560-AF99-1987E23047CD"), helpstring("ZoomIn Class"), 

implements_category(__uuidof(CATID_MxCommands)), implements_category(__uuidof
  (CATID_ControlsCommands))]

Use the command in ArcMap

1. Start ArcMap, and open a map document which has some data layers.
2. Click Tools, Customize and select the Developer Samples category.
   
3. In the right-hand pane, select the "ZoomIn x 0.5 VC8"  command, and drag it on to an ArcMap toolbar. Close the Customize dialog box.
4. Click the new command button to zoom in to the map.
5. Save the document, and then close ArcMap.

Use the command with the ToolbarControl

1. Paste the ToolbarControl and MapControl onto a VC++ dialog.
2. Right-click on the MapControl to open the property page, then from the General tab select a suitable map document.
3. Right-click ToolbarControl to open the property page, then from the General tab choose the MapControl from the BuddyControl list
4. Select the Items tab and click the Add button.
5. Select the Developer Samples category on the commands tab of the ControlsCommands dialog.
   
   
   
6. In the right-hand pane, select the "ZoomIn x 0.5 VC8" command, and either double click or drag it on to the toolbar. Close the ControlsCommands dialog box and press the OK button on the property pages.
7. Build and run the application.
8. Click the new command button to zoom in to the map.

Stepping through the command with the debugger

1. Return to the Visual Studio environment.
2. In the Solutions View of the Workspace browser , right-click the Walkthrough1VC8 project, and click Properties.
3. In the Debugging category, add ArcMap.exe as the executable for debug session:
   
   
4. Close the Project Property dialog box.
5. In the code window, find the class constructor method, put the cursor on the first line of code and press F9 to set a breakpoint.
6. Press F5 to begin a debug session. The buttons on the debug toolbar can then be used to step through the code one line at a time.

Walkthrough References