Getting inside the IDE
by Allen Bauer, Staff Engineer/Delphi&C++Builder R&D Manager

The second mechanism is one that I prefer because the it allows an IDE extension to be loaded and unloaded on demand by the user.  This involves creating a design-time package as if one were creating components to be added to the IDE's tool palette.  The other very good reason to use the package approach is that accessing the internals of the IDE is much easier since the boundaries between the package and the IDE are much less.  For instance, it is possible to actually create a new TMenuItem component and simply insert it into the IDE's main menu.  This is made possible by the fact that both the core of the IDE and the add-in package both must share the exact same in-memory copy of both the RTL and VCL.  Also in future articles when I cover creation of a dockable IDE add-in forms, this mechanism is essential.
While the flexibility of using packages is great, it does place a burden on the programmer in that they must be prepared to be removed from memory at any time.  This means that everything done when the add-in was initialized, must now be undone and in many cases in the reverse order.   You should not really view this as a burden, but simply enforcement of good programming practices.

The Open Tools API is divided into different sub-systems loosely referred to as "Services."  For example, if you look in ToolsAPI.pas, you will see several interfaces named IOTAxxxxServices.  These interfaces provide the top-level access to each of the specific subsystems.  Many of these you'll recognize, like IOTADebuggerServices, IOTAKeyboardServices or IOTAMessageServices.  From one of these interfaces, a lot of information can be accessed.  You can also attach "notifier" interfaces to these sub-systems in order for your add-in to be notifications of important events as they occur within the IDE.
So how do I get one of these "Services" interfaces?  If you again refer to ToolsAPI.pas, you'll notice that immediately above the implementation keyword there is a global variable called BorlandIDEServices.  If you notice, the type of this variable is simply IUnknown.  That isn't very interesting...or is it? You see, the key here is the QueryInterface method.  Or, as the interface savvy Delphi programmer would notice, as is the key.

var
  DebuggerServices: IOTADebuggerServices;
begin
  DebuggerServices := BorlandIDEServices as IOTADebuggerServices;
  ...
end;

Remember, since the ToolsAPI unit is also used by the IDE, it actually resides in VCL40 or VCL50.  You won't get anywhere if you simply compile ToolsAPI.pas into your application since the BorlandIDEServices variable is initialized deep in the core of the IDE.

To start this off right, we need a package.  I usually just use the File|New dialog and select Package.  This creates a Package1.dpk.  You should go ahead and save this new project and give it a meaningful name, like SillyOTAExample.dpk.

Now we need a place to put our code.  Since this is going to be a design-time package, a unit with a global procedure named Register must exist in the package in order for things to work correctly.  By using the Register procedure, the precise moment when it is safe to "muck" with things is guaranteed because the IDE ensures things are ready when it calls this procedure.  Since there is no corresponding Unregister procedure, the unit finalization section will be used for any cleanup that may be necessary.  I'm going to cheat a little and use the New Component Wizard to generate this for me.  Click the little Add Button, on the package manager and enter information similar to the following.... (Note you can ignore the path information since that is specific to my machine and happens to be ahem.... my C++Builder IDE dev tree.. ;-)

unit SillyOTAObject;

interface

procedure Register;

implementation

uses
  Windows, SysUtils, Classes, ToolsAPI;

type
  TSillyOTAObject = class(TNotifierObject)
  private
    { Private declarations }
  protected
    { Protected declarations }
  public
    { Public declarations }
  end;

procedure Register;
begin
end;

end.

type
  TSillyOTAObject = class(TNotifierObject, IOTANotifier, IOTAIDENotifier)
  private
    { Private declarations }
  protected
    procedure FileNotification(NotifyCode: TOTAFileNotification;
      const FileName: string; var Cancel: Boolean);
    procedure BeforeCompile(const Project: IOTAProject; var Cancel: Boolean); overload;
    procedure AfterCompile(Succeeded: Boolean); overload;
  public
    { Public declarations }
  end;

{ TSillyOTAObject }

procedure TSillyOTAObject.AfterCompile(Succeeded: Boolean);
begin
  { Not interested in AfterCompile at this time }
end;

procedure TSillyOTAObject.BeforeCompile(const Project: IOTAProject;
var Cancel: Boolean);
begin
  { Not interested in BeforeCompile at this time }
end;

procedure TSillyOTAObject.FileNotification(
NotifyCode: TOTAFileNotification; const FileName: string;
var Cancel: Boolean);
begin
end;


Now let's get this notifier into the right place...  The fun really starts in the Register procedure.  Here's how it looks:

var
  Index: Integer;

procedure Register;
begin
  Index := (BorlandIDEServices as IOTAServices).AddNotifier(TSillyOTAObject.Create);
end;

initialization
finalization
  (BorlandIDEServices as IOTAServices).RemoveNotifier(Index);
end.


Another item to note here is that I hold no reference to the TSillyOTAObject class.   This is because at this point there is no need to.  In fact it could be dangerous to do so because since this object implements interfaces and is fully lifetime managed, explicitly freeing the object could have disastrous consequences.  All that is needed is the index value returned from the AddNotifier method.  Make sure that the index value received is the only value used in the call to RemoveNotifier.  I'm sure other OTA developers would not appreciate having their notifier interface removed by some errant OTA extension without their knowledge...  

procedure TSillyOTAObject.FileNotification(
  NotifyCode: TOTAFileNotification; const FileName: string;
  var Cancel: Boolean);
begin
  case NotifyCode of
    ofnFileOpened: (BorlandIDEServices as IOTAMessageServices).AddTitleMessage(
      Format('%s Opened', [FileName]));
    ofnFileClosing: (BorlandIDEServices as IOTAMessageServices).AddTitleMessage(
      Format('%s Closed', [FileName]));
  end;
end;

Now comes the moment of truth.  Press the Install Button on the package manager window.  This will compile the package and install the package into the IDE.  If all went as planned you should see no noticeable change.  It things didn't go so well... you may have crashed the IDE...  Well, that is one of the pitfalls of developing an OTA extension.  Since you are playing around in the IDE's sandbox (or process space), it is now at the mercy of whatever code you decide to put in your extension.  By the same token, that is also where the full power of the OTA is realized.
Assuming that things went OK, try opening a file.. say ToolsAPI.pas.  Right click on the editor and select Message View.  There should now be at least one message in the message view that indicates what file was opened.  Congratulations, you have just built an OTA IDE extension!

With the holidays fast approaching, this will probably be my last article until the new year (millennium or century,  unless you want to treat 2001 as the new century/millennium...;-).

Happy Holidays.

Allen Bauer.