The Open Tools API using C++ Builder

So we will start with the declaration of the notifier object class we will use for all our objects:

 #ifndef CPPOTATemplateNotifierObjectH
 #define CPPOTATemplateNotifierObjectH

 #include <ToolsAPI.hpp>

class PACKAGE TDGHNotifierObject : public IOTANotifier {
  private:
    long ref_count;
    String FObjectName;
  protected:
    void __fastcall DoNotification(String strMessage);
    // IOTANotifier
    void __fastcall AfterSave();
    void __fastcall BeforeSave();
    void __fastcall Destroyed();
    void __fastcall Modified();
    // IInterface
    virtual HRESULT __stdcall QueryInterface(const GUID&, void**);
    virtual ULONG __stdcall AddRef();
    virtual ULONG __stdcall Release();
  public:
    __fastcall TDGHNotifierObject(String strObjectName);
    virtual __fastcall ~TDGHNotifierObject();
 };
 #endif

There are a number of things to consider here. The first is that all the header is defined between the #ifndef and #endif statements. With me not being a C++ guru it took me sometime to work out why this should be the case. For non-C++ people the header files are not quite the same as Delphi's interface sections and the #include statements are not the same as Delphi s uses statements. If you don't place your header declarations in the #ifndef section you will eventually end up with the compiler saying you are declaring some of your objects mulitple times, especially with the above base class which will be used multiple times.

The next thing was to include the ToolsAPI.hpp file however this is not enough to get your code to compile. You need to added $(BDSINCLUDE)\windows\vcl\design\ to your project's include list.

Next I've declared a field for the reference counting and methods I need to override for IInterface and IOTANotifier. One thing to be careful of is NOT to simply copy the methods from the ToolsAPI.hpp file as there are some modifiers that should not be present in your declarations like Virtual and HIDEBASE.

Finally I've added a number of of extra methods and fields so that the object can output messages to the message window and know what the class implementing this base class is called.

Below is the implementation of the above object:

#pragma hdrstop
#include "CPPOTATemplateNotifierObject.h"
#include "CPPOTATemplateMacros.h"
#include "Forms.hpp"
#pragma package(smart_init)

/* Notifer Implementation */

__fastcall TDGHNotifierObject::TDGHNotifierObject(String strObjectName) {
  ref_count = 0;
  FObjectName = strObjectName;
}

__fastcall TDGHNotifierObject::~TDGHNotifierObject() {
  // Do nothing destructor
}

ULONG __stdcall TDGHNotifierObject::AddRef() {
  return InterlockedIncrement(&ref_count);
}

ULONG __stdcall TDGHNotifierObject::Release() {
  ULONG result = InterlockedDecrement(&ref_count);
  if (ref_count == 0)
    delete this;
  return result;
}

HRESULT __stdcall TDGHNotifierObject::QueryInterface(const GUID& iid, void** obj) {
  QUERY_INTERFACE(IInterface, iid, obj);
  QUERY_INTERFACE(IOTANotifier, iid, obj);
  return E_NOINTERFACE;
}

void __fastcall TDGHNotifierObject::AfterSave() {
  DoNotification(FObjectName + "::AfterSave");
};

void __fastcall TDGHNotifierObject::BeforeSave() {
  DoNotification(FObjectName + "::BeforeSave");
};

void __fastcall TDGHNotifierObject::Destroyed() {
  DoNotification(FObjectName + "::Destroyed");
};

void __fastcall TDGHNotifierObject::Modified() {
  DoNotification(FObjectName + "::Modified");
};

void __fastcall TDGHNotifierObject::DoNotification(String strMessage) {
  _di_IOTAMessageServices MsgServices;
  if (BorlandIDEServices->Supports(MsgServices)) {
    // Make sure messages are not added when the IDE is being destroyed.
    if (Application->MainForm->Visible) {
      _di_IOTAMessageGroup MsgGrp = MsgServices->AddMessageGroup("C++ OTA Template");
      MsgServices->ShowMessageView(MsgGrp);
      MsgServices->AddTitleMessage(FObjectName + strMessage, MsgGrp);
    }
  }
}

So in the above the constructor initialises the reference counting to zero and stores the name passed to the constructor for later use in outputting messages so that you know which object is outputting messages.

The method AddRef() calls the windows function InterlockedIncrement() to increment the reference counter in a thread safe manner and returns the resulting incremented value. Likewise Release() decrements the reference count in a similar manner. If the count gets to zero the Release() frees the object.

QueryInterface is where the most work is done. Embedded in this method are 2 calls to a macro which determines whether the passed object implements a specific interface. The difference here is that you MUST implement this function with the checks for the interfaces you are implementing for you code to work. Secondly, the macro is used as this is a pattern that will be used numerous times in the application. The macro is defined as below (Note: I've put my macros in their own unit):

#define QUERY_INTERFACE(T, iid, obj)   \
  if ((iid) == __uuidof(T)) {          \
    *(obj) = static_cast<T*>(this);    \
    static_cast<T*>(*(obj))->AddRef(); \
    return S_OK;                       \
  }

This checks that the passed interface is of the type given and if so returns the cast object reference. Note: Macros in C++ are replaced in-line and are not the same as functions.

The BeforeSave(), AfterSave(), Destroyed() and Modified() methods simply return a notification message if they are called.

Finally the DoNotification() method outputs a message to the message view in a new group. Here is where C++ OTA code differs from Object Pascal. Since C++ does not have interfaces you have to implement them using macros that are defined in the ToolsAPI.hpp file. So for instance I need a IOTAMessageServices interface from the BorlandIDEServcies interface. First I declare my variable using the macro _di_IOTAMessageServcies where the _di_ stands for Delphi Interface. I can then ask BorlandIDEServices if it supports the interface and if so I can then call the appropriate methods.

So here I've implemented a menu wizard. I've done this before here (Chapter 1: Starting an Open Tools API Project) so if you want to understand the OTA interfaces please have a read.

Here's my C++ declaration below:

 #ifndef CPPOTATemplateMainWizardH
 #define CPPOTATemplateMainWizardH

 #include <ToolsAPI.hpp>
 #include <CPPOTATemplateNotifierObject.h>

class PACKAGE TCPPOTATemplateWizard : public TDGHNotifierObject, public IOTAMenuWizard {
  typedef TDGHNotifierObject inherited;
  private:
  protected:
    // IOTAWizard
    virtual UnicodeString __fastcall GetIDString();
    virtual UnicodeString __fastcall GetName();
    virtual TWizardState  __fastcall GetState();
    virtual void __fastcall Execute();
    // IOTAMenuWizard
    virtual UnicodeString __fastcall GetMenuText();
    // IOTANotifer
    void __fastcall BeforeSave();
    void __fastcall AfterSave();
    void __fastcall Destroyed();
    void __fastcall Modified();
    // IInterface
    virtual HRESULT __stdcall QueryInterface(const GUID& iid, void** obj);
    virtual ULONG __stdcall AddRef();
    virtual ULONG __stdcall Release();
    // Non-interface methods
  public:
    __fastcall TCPPOTATemplateWizard(String strObjectName);
    __fastcall ~TCPPOTATemplateWizard();
};
 #endif

So here we create a class that is inherited from our notifier object and IOTAMenuWizard. In C++ you do not need to inherited from all the chain of interfaces like you do in Delphi as the interfaces are implemented as classes and therefore this is happening anyway.

Below is the implementation of the wizard:

#pragma hdrstop
#include <CPPOTATemplateMainWizard.h>
#include <Dialogs.hpp>
#include <CPPOTATemplatePkgDLLInit.h>
#include "CPPOTATemplateMacros.h"
#pragma package(smart_init)

/* TCPPOTATemplateWizard Implementation */

__fastcall TCPPOTATemplateWizard::TCPPOTATemplateWizard(String strObjectName) :
  TDGHNotifierObject(strObjectName) {
  // Do nothing constructor
}

__fastcall TCPPOTATemplateWizard::~TCPPOTATemplateWizard() {
  // Do nothing destructor
}

ULONG __stdcall TCPPOTATemplateWizard::AddRef() {
  return inherited::AddRef();
}

ULONG __stdcall TCPPOTATemplateWizard::Release() {
  return inherited::Release();
}

HRESULT __stdcall TCPPOTATemplateWizard::QueryInterface(const GUID& iid, void** obj) {
  QUERY_INTERFACE(IOTAMenuWizard, iid, obj);
  QUERY_INTERFACE(IOTAWizard, iid, obj);
  return inherited::QueryInterface(iid, obj);
}

UnicodeString __fastcall TCPPOTATemplateWizard::GetIDString() {
  return "CPP.OTA.Template.Wizard";
}

UnicodeString __fastcall TCPPOTATemplateWizard::GetName() {
  return "CPP OTA Temaple";
}

TWizardState  __fastcall TCPPOTATemplateWizard::GetState() {
  TWizardState result;
  result << wsEnabled;
  return result;
}

void __fastcall TCPPOTATemplateWizard::Execute() {
  DoNotification("... Hello Dave!");
  MessageDlg("Hello Dave... How are you...", mtInformation, TMsgDlgButtons() << mbOK, 0);
}

UnicodeString __fastcall TCPPOTATemplateWizard::GetMenuText() {
  return "My CPP OTA Template Menu";
}

void __fastcall TCPPOTATemplateWizard::BeforeSave() {
  inherited::BeforeSave();
}

void __fastcall TCPPOTATemplateWizard::AfterSave() {
  inherited::AfterSave();
}

void __fastcall TCPPOTATemplateWizard::Destroyed() {
  inherited::Destroyed();
}

void __fastcall TCPPOTATemplateWizard::Modified() {
  inherited::Modified();
}

Most of the methods just call their inherited versions or the DoNotification() method to output a message to the message view however the QueryInterface() method checks for the IOTAWizard and IOTAMenuWizard interfaces before calling the inherited method.

Below is the declaration which is similar to the wizard that has gone before. Note also that I've declared 2 methods to install and remove the notifier.

#ifndef CPPOTATemplateIDENotifierH
#define CPPOTATemplateIDENotifierH

#include <ToolsAPI.hpp>
#include <CPPOTATemplateNotifierObject.h>

class PACKAGE TCPPOTATemplateIDENotifier : public TDGHNotifierObject, public IOTAIDENotifier80 {
  typedef TDGHNotifierObject inherited;
  public:
    __fastcall TCPPOTATemplateIDENotifier(String strObjectName);
    __fastcall  TCPPOTATemplateIDENotifier();
    // IOTAIDENotifier
    void __fastcall FileNotification(TOTAFileNotification NotifyCode,
      const System::UnicodeString FileName, bool &Cancel);
    void __fastcall BeforeCompile(const _di_IOTAProject Project, bool &Cancel);
    void __fastcall AfterCompile(bool Succeeded);
    // IOTAIDENotifier50
    void __fastcall BeforeCompile(const _di_IOTAProject Project,
      bool IsCodeInsight, bool &Cancel);
    void __fastcall AfterCompile(bool Succeeded, bool IsCodeInsight);
    // IOTAIDENotifier80
    void __fastcall AfterCompile(const _di_IOTAProject Project,
      bool Succeeded, bool IsCodeInsight);
    // IOTANotifer
    void __fastcall BeforeSave();
    void __fastcall AfterSave();
    void __fastcall Destroyed();
    void __fastcall Modified();
  protected:
    // IInterface
    virtual HRESULT __stdcall  QueryInterface(const GUID&, void**);
    virtual ULONG __stdcall  AddRef();
    virtual ULONG __stdcall  Release();
  private:
};

int __fastcall AddIDENotifier();
void __fastcall RemoveIDENotifier(int iIDENotifierIndex);
#endif

Below is the implementation of the class:

#pragma hdrstop
#include <CPPOTATemplateIDENotifier.h>
#include "CPPOTATemplateMacros.h"
#include <SysUtils.hpp>
#pragma package(smart_init)

__fastcall TCPPOTATemplateIDENotifier::TCPPOTATemplateIDENotifier(String strObjectName) :
  TDGHNotifierObject(strObjectName) {
  // Do nothing constructor
}

__fastcall TCPPOTATemplateIDENotifier:: TCPPOTATemplateIDENotifier() {
  // Do nothing deconstructor
}

void __fastcall TCPPOTATemplateIDENotifier::FileNotification(
  TOTAFileNotification NotifyCode, const System::UnicodeString FileName, bool &Cancel) {
  const String strNotifyCode[11] = {
    "ofnFileOpening",
    "ofnFileOpened",
    "ofnFileClosing",
    "ofnDefaultDesktopLoad",
    "ofnDefaultDesktopSave",
    "ofnProjectDesktopLoad",
    "ofnProjectDesktopSave",
    "ofnPackageInstalled",
    "ofnPackageUninstalled",
    "ofnActiveProjectChanged",
    "ofnProjectOpenedFromTemplate"
  };
  DoNotification(
    Format("FileNotification: NotifyCode(%d): %s, FileName: %s",
      ARRAYOFCONST((
        NotifyCode,
        strNotifyCode[NotifyCode],
        ExtractFileName(FileName)
      ))
    )
  );
}

void __fastcall TCPPOTATemplateIDENotifier::BeforeCompile(const _di_IOTAProject Project,
  bool &Cancel) {
  DoNotification(
    Format("::BeforeCompile: Project: %s",
      ARRAYOFCONST((ExtractFileName(Project->FileName)))
    )
  );
}

void __fastcall TCPPOTATemplateIDENotifier::AfterCompile(bool Succeeded) {
  DoNotification(
    Format("::AfterCompile: %s",
      ARRAYOFCONST((
        Succeeded   "True" : "False"
      ))
    )
  );
}

void __fastcall TCPPOTATemplateIDENotifier::BeforeCompile(const _di_IOTAProject Project,
  bool IsCodeInsight, bool &Cancel) {
  DoNotification(
    Format("50::BeforeCompile: Project: %s, IsCodeInsight: %s",
      ARRAYOFCONST((
        ExtractFileName(Project->FileName),
        IsCodeInsight   "True" : "False"
      ))
    )
  );
}

void __fastcall TCPPOTATemplateIDENotifier::AfterCompile(bool Succeeded,
  bool IsCodeInsight) {
  DoNotification(
    Format("50::AfterCompile: Succeeded: %s, IsCodeInsight: %s",
      ARRAYOFCONST((
        Succeeded   "True" : "False",
        IsCodeInsight   "True" : "False"
      ))
    )
  );
}

void __fastcall TCPPOTATemplateIDENotifier::AfterCompile(const _di_IOTAProject Project,
  bool Succeeded, bool IsCodeInsight) {
  DoNotification(
    Format("80::AfterCompile: Project: %s, Succeeded: %s, IsCodeInsigh: %s",
      ARRAYOFCONST((
        ExtractFileName(Project->FileName),
        Succeeded   "True" : "False",
        IsCodeInsight   "True" : "False"
      ))
    )
  );
}

void __fastcall TCPPOTATemplateIDENotifier::BeforeSave() {
  inherited::BeforeSave();
  DoNotification("::BeforeSave");
}

void __fastcall TCPPOTATemplateIDENotifier::AfterSave() {
  inherited::AfterSave();
  DoNotification("::AfterSave");
}

void __fastcall TCPPOTATemplateIDENotifier::Destroyed() {
  inherited::Destroyed();
  DoNotification("::Destroyed");
}

void __fastcall TCPPOTATemplateIDENotifier::Modified() {
  inherited::Modified();
  DoNotification("::Modified");
}

HRESULT __stdcall TCPPOTATemplateIDENotifier::QueryInterface(const GUID& iid, void** obj) {
  QUERY_INTERFACE(IOTAIDENotifier50, iid, obj);
  QUERY_INTERFACE(IOTAIDENotifier80, iid, obj);
  QUERY_INTERFACE(IOTAIDENotifier, iid, obj);
  return inherited::QueryInterface(iid, obj);
}

ULONG __stdcall TCPPOTATemplateIDENotifier::AddRef() {
  return inherited::AddRef();
}

ULONG __stdcall TCPPOTATemplateIDENotifier::Release() {
  return inherited::Release();
}

In the above most methods either call their inherited method or output a notification to show the method has been called. As before with the wizard the QueryInterface method uses the macro QUERY_INTERFACE to dispatch incoming calls for each of the 3 notifier interfaces else allow the inherited version to be called. It should also be noted that unlike Delphi all versions of the overloaded methods are called not just the latest implementation. This is different behaviour to Delphi.

The below method is used to install the notifier into the IDE. This should be installed in the wizard's constructor.

int __fastcall AddIDENotifier() {
  _di_IOTAServices IDEServices;
  if (BorlandIDEServices->Supports(IDEServices)) {
    return IDEServices->AddNotifier(new TCPPOTATemplateIDENotifier("TCPPOTATemplateIDENotifier"));
  }
  return -1;
}

The below method is used to uninstall the notifier from the IDE. This should be uninstalled in the wizard's destructor.

void __fastcall RemoveIDENotifier(int iIDENotifierIndex) {
  _di_IOTAServices IDEServices;
  if (BorlandIDEServices->Supports(IDEServices)) {
    if (iIDENotifierIndex > -1) {
      IDEServices->RemoveNotifier(iIDENotifierIndex);
    }
  }
}

For more information on this notifier please refer to Chapter 7: IDE Compilation Events.

Below is the declaration of an Add-in Options class to allow the IDE to create and interact with our options frame for the AutoSave functionality. Also declared below are 2 methods to install and uninstall the dialogue from the IDE.

#ifndef CPPOTATemplateAddinOptionsH
#define CPPOTATemplateAddinOptionsH

#include <ToolsAPI.hpp>
#include "CPPOTATemplateAppOptionsFrame.h"#
#include "CPPOTATemplateAppOptions.h"#
#include "CPPOTATemplateNotifierObject.h"

class PACKAGE TCPPOTATemplateAddInOptions : public TDGHNotifierObject, public INTAAddInOptions {
  typedef TDGHNotifierObject inherited;
  private:
    TCPPOTATemplateOptions* FOptions;
    TframeAppOptions* FAppOptionsFrame;
  protected:
    // IOTANotifier
    void __fastcall BeforeSave();
    void __fastcall AfterSave();
    void __fastcall Destroyed();
    void __fastcall Modified();
    // IInterface
    virtual HRESULT __stdcall QueryInterface(const GUID& iid, void** obj);
    virtual ULONG __stdcall AddRef();
    virtual ULONG __stdcall Release();
    // INTAAddinOptions
    UnicodeString __fastcall GetArea();
    UnicodeString __fastcall GetCaption();
    TCustomFrameClass __fastcall GetFrameClass();
    void __fastcall FrameCreated(TCustomFrame* AFrame);
    void __fastcall DialogClosed(bool Accepted);
    bool __fastcall ValidateContents();
    int __fastcall GetHelpContext();
    bool __fastcall IncludeInIDEInsight();
  public:
    TCPPOTATemplateAddInOptions(String strObjectName, TCPPOTATemplateOptions* Options);
};

TCPPOTATemplateAddInOptions* __fastcall AddOptionsFrameToIDE(TCPPOTATemplateOptions* Options);
void __fastcall RemoveOptionsFrameFromIDE(TCPPOTATemplateAddInOptions* IDEOptions);

 #endif

Below is the implementation of the above class:

pragma hdrstop
include "CPPOTATemplateAddinOptions.h"#
include "CPPOTATemplateMacros.h"#
pragma package(smart_init)

TCPPOTATemplateAddInOptions::TCPPOTATemplateAddInOptions(String strObjectName,
  TCPPOTATemplateOptions* Options) : TDGHNotifierObject(strObjectName) {
  FOptions = Options;
}

UnicodeString __fastcall TCPPOTATemplateAddInOptions::GetArea() {
  return "";
}

UnicodeString __fastcall TCPPOTATemplateAddInOptions::GetCaption() {
  return "C++ OTA Template.AutoSave Options";
}

TCustomFrameClass __fastcall TCPPOTATemplateAddInOptions::GetFrameClass() {
  return __classid(TframeAppOptions);
}

void __fastcall TCPPOTATemplateAddInOptions::FrameCreated(TCustomFrame* AFrame) {
  FAppOptionsFrame = dynamic_cast<TframeAppOptions*>(AFrame);
  if (FAppOptionsFrame  = NULL) {
    FAppOptionsFrame->LoadFrame(FOptions);
  }
}

void __fastcall TCPPOTATemplateAddInOptions::DialogClosed(bool Accepted) {
  Accepted = true;
}

bool __fastcall TCPPOTATemplateAddInOptions::ValidateContents() {
  if (FAppOptionsFrame  = NULL) {
    FAppOptionsFrame->SaveFrame(FOptions);
  }
  return true;
}

int __fastcall TCPPOTATemplateAddInOptions::GetHelpContext() {
  return 0;
}

bool __fastcall TCPPOTATemplateAddInOptions::IncludeInIDEInsight() {
  return true;
}

void __fastcall TCPPOTATemplateAddInOptions::BeforeSave() {
  inherited::BeforeSave();
}

void __fastcall TCPPOTATemplateAddInOptions::AfterSave() {
  inherited::AfterSave();
}

void __fastcall TCPPOTATemplateAddInOptions::Destroyed() {
  inherited::Destroyed();
}

void __fastcall TCPPOTATemplateAddInOptions::Modified() {
  inherited::Modified();
}

HRESULT __stdcall TCPPOTATemplateAddInOptions::QueryInterface(const GUID& iid, void** obj) {
  QUERY_INTERFACE(INTAAddInOptions, iid, obj);
  return inherited::QueryInterface(iid, obj);
}

ULONG __stdcall TCPPOTATemplateAddInOptions::AddRef() {
  return inherited::AddRef();
}

ULONG __stdcall TCPPOTATemplateAddInOptions::Release() {
  return inherited::Release();
}

Most of the above is the same as you would for Delphi. The QueryInterface method has an additional statement to handle this classes interface (IOTAAddInOptions). The only other note worthy method is the one that returns the frame class reference, this is achieved using the __classid() method.

The below method installs the dialogue into the IDE and should be called from the wizard's constructor.

TCPPOTATemplateAddInOptions* __fastcall AddOptionsFrameToIDE(TCPPOTATemplateOptions* Options) {
  _di_INTAEnvironmentOptionsServices EnvOpServices;
  if (BorlandIDEServices->Supports(EnvOpServices)) {
    TCPPOTATemplateAddInOptions* IDEOptions =
      new TCPPOTATemplateAddInOptions("TCPPOTATemplateAddInOptions", Options);
    EnvOpServices->RegisterAddInOptions(IDEOptions);
    return IDEOptions;
  }
  return NULL;
}

The below method uninstalls the dialogue from the IDE and should be called from the wizard's destructor.

void __fastcall RemoveOptionsFrameFromIDE(TCPPOTATemplateAddInOptions* IDEOptions) {
  _di_INTAEnvironmentOptionsServices EnvOpServices;
  if (BorlandIDEServices->Supports(EnvOpServices) && (IDEOptions  = NULL))  {
    EnvOpServices->UnregisterAddInOptions(IDEOptions);
  }
}

For more information on creating options dialogues for the IDE please refer to Chapter 17: Options Page(s) inside the IDE's Options Dlg.