Erik's Open Tools API FAQ and Resources

If you have additions or corrections, please contact me. But, please do not send me questions about how to use the Open Tools API - instead, use the resources listed below.

What is the Open Tools API?

Where is the Open Tools API documented?

Where can I get help with my Open Tools API questions?

• <IdeRoot>\Source\ToolsAPI\ToolsAPI.pas
  A good place to learn about the Open Tools API is is the ToolsAPI.pas unit and the related files in that directory such as PaletteAPI.pas, StructureViewAPI.pas, and CodeTemplateAPI.pas. If you don't have any of those files, try reinstalling the IDE with all of the options, or maybe you need to upgrade to a higher-end IDE edition that includes the source files (Professional, Enterprise, Architect, etc.).All of the official OTA interfaces are defined in those files, and many of them have comments about their purpose and usage.
• Newsgroup Search Engines
  There are several free web services that allow you to search for answers to previously asked questions in the Open Tools API newsgroup. I recommend you search at least one of these before posting, as it generally gives multiple answers to the most common questions. Try one of the following:

  Search Site	Newsgroups	Date Range	Search Features	Speed
  Google Groups	All	May 1981 - Now	Good	Fast
  Delphi Newswhat	CodeGear, Programming	Google Search	Google Search	Google Search
  Tamarack Associates	CodeGear/Borland	Oct. 1997 - Now	Moderate	Moderate
  Mers (down?)	CodeGear/Borland	May 1997 - Now	Limited	Slow

  
  

• The Open Tools API Newsgroup
  CodeGear/Borland runs a newsgroup server that has an Open Tools API discussion group on it. Before posting, please read the newsgroup guidelines, and check the newsgroup search engines above and the previous messages in the group for answers to your questions. You can access the newsgroup at news://newsgroups.borland.com/borland.public.delphi.opentoolsapi
  
• Example Code
  
  • Delphi Super Page
    
  • Torry's Delphi Pages
    
• Other Web Sites
  • Mustang Peak OTA Tutorial - This site contains some step-by-step examples and documentation on creators, repository wizards, project/module interfaces, and other tutorials.
  • Ray Lischner's Open Tools Resources - Ray's web site is a bit out-of-date and only covers the interfaces through Delphi 3/4, but might still be useful to some people.
  • Open Tools Interfaces by Rappido - Descriptions of how to obtain some of the interfaces.

What is the "old" OTA and what is the "new" OTA? Which one should I use?

The "old" Open Tools API (OTA) was the preferred method for addins to interface with the IDE in Delphi 3 and older and was class-based. The "new" OTA is present in Delphi/BCB 4 or later and is interface-based. This FAQ only covers the new OTA, which consists mainly of the ToolsAPI.pas unit. Starting with Delphi 8 or greater, you will find a few more files that define the OTA such as PaletteAPI.pas, StructureViewAPI.pas, CodeTemplateAPI.pas, FileHistoryAPI.pas, DesignerTypes.pas and PropInspAPI.pas. The older OTA is depreciated and should no longer be used except to maintain compatibility with older IDE versions. Support for the old OTA will be completely dropped in a future version of Delphi, and existing bugs in it are not being fixed. The old Open Tools API consists of the following units: ExptIntf, FileIntf, IStreams, ToolIntf, VcsIntf, VirtIntf.

Where can I get a simple wizard/expert to customize?

Here is the Pascal source for the simplest "Hello World!" wizard using the Open Tools API. Just compile and install this package (DPK) into the IDE, and try out the new menu item on the Help menu.

Can I create wizards in C++Builder?

Can I install a Delphi-created wizard into C++Builder?

Yes, GExperts is one example of an expert written in Delphi that can be compiled and installed into C++Builder.

Should I ever call Release on an interface obtained from the IDE?

How can I add published properties to a TForm descendent?

• Add published properties to a regular TForm
  
• Add the form to the Object Repository (Project menu)
  
• Add the form to an existing design time package (such as Borland User Components) or to a new design-time package.
  
• Add DsgnIntf/DesignIntf to the implementation uses clause of a unit in the package, and add a register procedure as follows:

  procedure Register;
  begin
    RegisterCustomModule(TMyForm, TCustomModule);
  end;

• Finally, inherit from your form in the repository inside a project and the new published properties will show up. Remember to not try to link to the new designtime package when building your deployable application.

There is also a much more complex method involving writing a module creation expert, a repository expert, and using CreateModuleEx and different streams, but is much more error-prone and for most people, has no advantages.

Note that the IDE will not allow you to add both published properties and components to a custom module at the same time. The workaround is to create a form with your custom properties in a package, and then have a descendent form in the repository which adds the components you want there by default.

How do I obtain the current project (IOTAProject) interface?

function GetCurrentProject: IOTAProject;
var
  ModServices: IOTAModuleServices;
  Module: IOTAModule;
  Project: IOTAProject;
  ProjectGroup: IOTAProjectGroup;
  i: Integer;
begin
  Result := nil;
  ModServices := BorlandIDEServices as IOTAModuleServices;
  for i := 0 to ModServices.ModuleCount - 1 do
  begin
    Module := ModServices.Modules[i];
    if Supports(Module, IOTAProjectGroup, ProjectGroup) then
    begin
      Result := ProjectGroup.ActiveProject;
      Exit;
    end
    else if Supports(Module, IOTAProject, Project) then
    begin // In the case of unbound packages, return the 1st
      if Result = nil then
        Result := Project;
    end;
  end;
end;

How do I obtain the current project group (IOTAProjectGroup) interface?

function GetCurrentProjectGroup: IOTAProjectGroup;
var
  ModServices: IOTAModuleServices;
  ProjectGroup: IOTAProjectGroup;
  Module: IOTAModule;
  i: Integer;
begin
  Result := nil;
  ModServices := BorlandIDEServices as IOTAModuleServices;
  for i := 0 to ModServices.ModuleCount - 1 do
  begin
    Module := ModServices.Modules[i];
    if Supports(Module, IOTAProjectGroup, ProjectGroup) then
    begin
      Result := ProjectGroup;
      Break;
    end;
  end;
end;

How can I obtain the IOTAProjectResource interface for a given project?

function GetProjectResource(Project: IOTAProject): IOTAProjectResource;
var
  i: Integer;
  Editor: IOTAEditor;
begin
  Result := nil;
  for i:= 0 to (Project.GetModuleFileCount - 1) do
  begin
    Editor := Project.GetModuleFileEditor(i);
    if Supports(Editor, IOTAProjectResource, Result) then
      Break;
  end;
end;

How can I get a list of all installed components?

Is there any OTA support for creating type libraries or controlling the type library editor?

Is there any OTA support for parsing a source file or obtaining Code Insight information?

C#Builder, Delphi 8+, and BDS support obtaining the .NET CodeDom for C# and Delphi code using IOTACodeDomProvider, but older IDEs do not expose unit structure details or Code Insight information such as method parameter lists, symbol declaration locations, class members, and symbol table information. As a result, you will need to parse the source yourself or use an existing language parser such as those at Torry's Delphi Pages (search for mwDelPar or mwPasPar, for examples). Starting with Delphi 7, you can implement your own code completion and parameter hints via the IOTACodeInsight* interfaces, but the source parsing is still up to you.

Should I compile my wizard as a DLL or a Package?

Why does my wizard have to dynamically link to the VCL/DesignIde packages?

How do I get a hold of the designer for a DataModule?

How do a I get a reference to an IOTAXxxx interface?

Interface	Obtained From
INTAComponent	IOTAComponent
INTAFormEditor	IOTAFormEditor
IFormDesigner	INTAFormEditor
IOTAKeyboardDiagnostics	BorlandIDEServices
IOTAEditActions	IOTAEditView

How can I debug a DLL wizard?

1. Exit your IDE
2. Remove any registry entries which load the expert DLL into your IDE. Look in HKEY_CURRENT_USER\Software\Borland\Delphi\X.0\Experts.
3. Start your IDE, and verify the expert is not loaded.
4. Compile your expert DLL. In the project options, be sure to turn on debug information, stack frames, reference info, etc. Turn optimizations off.
5. Re-register the DLL with the IDE by adding an entry to HKEY_CURRENT_USER\Software\Borland\Delphi\X.0\Experts.
6. Select Run, Parameters from the IDE menu. Enter the IDE's executable as the host application for your DLL.
7. Run the host application (F9), and another copy of your IDE should appear with the expert loaded.
8. You can now debug the DLL as it were a normal program (watches, breakpoints, inspections, tooltip evaluation, etc.).
9. Note that package debugging does not work well in Delphi 4 and BCB 4. Both will lockup fairly often when debugging DLLs and packages. Later releases should work better.

How can I debug a package wizard?

1. In the project options for your package, turn on debug information, stack frames, reference info, etc. Turn optimizations off.
2. Uncheck your package in the Project Options Packages tab, if necessary.
3. Build your package (don't install it).
4. Select Run, Parameters from the IDE menu. Enter the IDE's executable as the host application for your package.
5. Run the host application (F9), and another copy of your IDE should appear.
6. In the second copy of the IDE, open up the Project Options and load your expert package into the IDE.
7. You can now debug the package as it were a normal program (watches, breakpoints, inspections, tooltip evaluation, etc.).
8. Note that package debugging does not work well in Delphi 4 and BCB 4. Both will lockup fairly often when debugging DLLs and packages. Later releases should work better.

How do I implement an IDE notifier (IOTAIDENotifier)?

How do I implement an editor notifier (IOTAEditorNotifier)?

  TTestEditorNotifier = class(TNotifierObject, IOTAEditorNotifier)
  public
    procedure Destroyed; override;
    procedure ViewActivated(const View: IOTAEditView);
    procedure ViewNotification(const View: IOTAEditView; Operation: TOperation);
  end;

How do I implement a form notifier (IOTAFormNotifier)?

  TMyFormNotifier = class(TNotifierObject, IOTANotifier, IOTAFormNotifier)
  protected
    procedure FormActivated;
    procedure FormSaving;
    procedure ComponentRenamed(ComponentHandle: TOTAHandle;
        const OldName, NewName: string);
  end;

How can I get notified when a source file has changed?

Starting in Delphi 6, IOTAEditorNotifier works for this. In Delphi 4/5 IOTAEditorNotifier never fires, so instead, attach a module notifier using IOTAModule.AddNotifier and watch for IOTAModuleNotifier.Modified.

How can I get notified when a form designer or component is selected?

How can I add a menu item to the IDE's main menu?

How can I add a shortcut to my main menu item?

In Delphi 5+, you should register a shortcut for your menu item using the keybinding interfaces:

• Implement IOTAKeyboardBinding and make sure GetBindingType returns btPartial
• Add your binding to the IDE using IOTAKeyboardServices.AddKeyboardBinding
• In the IOTAKeyboardBinding.BindKeyboard callback, use the passed in IOTAKeyBindingServices reference to call BindingServices.AddKeyBinding for each menu item, as described below:
  • Pass in a TKeyBindingProc type procedure callback method for when your shortcuts are pressed
    procedure Callback(const Context: IOTAKeyContext; KeyCode: TShortcut; var BindingResult: TKeyBindingResult);
  • Pass in the menu item's name as the last parameter (the ill named "HotKey" in Delphi 5). The call should look similar to this:
    

    AddKeyBinding([ShortCut(Ord('G'), [ssCtrl])], Callback,
        nil, 0, '', 'MyMenuItem');

How can I paint the palette bitmap for a specific component?

LibIntf.DelphiIDE.GetPaletteItem(GetClass('TButton')).Paint

var
  PaletteItem: IPaletteItem;
  PalettePaint: IPalettePaint;
begin
  with ComponentDesigner.ActiveDesigner.Environment do
    PaletteItem := GetPaletteItem(
        TComponentClass(FindClass('TButton'))) as IPaletteItem;
  PalettePaint :=  PaletteItem as IPalettePaint;
  PalettePaint.Paint(ACanvas, X, Y);

How do I implement a module creator (IOTAModuleCreator/IOTAFormWizard)?

TGxModuleCreator = class(TInterfacedObject, IOTACreator, IOTAModuleCreator)

Here is sample code for a Delphi 6-2007 module creator that resides in the File, New, Other repository screen by implementing IOTARepositoryWizard and the other required interfaces.

How do I implement a project creator (IOTAProjectCreator)?

TGxProjectCreator = class(TInterfacedObject, IOTACreator, IOTAProjectCreator)

How can I save/load values to a project's desktop settings (.dsk) file?

How can I add menu items to the code editor's popup menu?

How does the native OTA deal with UNICODE strings in the editor?

How can I iterate over all units/forms in a project?

How can I do custom painting or drawing (colors, lines, etc.) in the IDE code editor?

How can I iterate over all units/forms in a project?

How can I publish a property of type T[Custom]Form?

It doesn't work very well, but you can try to publish the property normally. The problem is that only currently created forms will be shown in the property editor, and storing an internal reference to one of those forms will often cause AVs when the target form is later closed. As a workaround, you can create a custom property editor that uses IOTAProject as above to get the class names of all forms in the project and insert them into the dropdown list for the property editor. Then store the form reference internally as a class name string, and use something like GetClass and RegisterClass to map a class name to a class type. With the class type, you can create the form at runtime. If you are sure your target form will always exist at runtime, another option to map from classes to instances is to search the Screen.Forms array.

How can I create a form that docks into the IDE like the Object Inspector?

How can I obtain the currently active form editor (IOTAFormEditor)?

function GetActiveFormEditor: IOTAFormEditor;
var
  Module: IOTAModule;
  Editor: IOTAEditor;
  i: Integer;
begin
  Result := nil;
  Module := (BorlandIDEServices as IOTAModuleServices).CurrentModule;
  if Module <> nil then
  begin
    for i := 0 to Module.GetModuleFileCount - 1 do
    begin
      Editor := Module.GetModuleFileEditor(i);
      if Supports(Editor, IOTAFormEditor, Result) then
        Break;
    end;
  end;
end;

How can I obtain the current form designer interface (IFormDesigner)?

function GetActiveFormDesigner: IFormDesigner;
var
  FormEditor: IOTAFormEditor;
begin
  Result := nil;
  FormEditor := GetActiveFormEditor;
  if FormEditor <> nil then
    Result := (FormEditor as INTAFormEditor).FormDesigner;
end;

How can I get a form editor from a module interface?

function GetFormEditorFromModule(Module: IOTAModule): IOTAFormEditor;
var
  i: Integer;
  Editor: IOTAEditor;
begin
  Result := nil;
  if Module = nil then
     Exit;
  for i := 0 to Module.GetModuleFileCount - 1 do
  begin
    Editor := Module.GetModuleFileEditor(i);
    if Supports(Editor, IOTAFormEditor, Result) then
      Break;
  end;
end;

Is there a way to determine if the user is editing a form or working in the code editor?

How can I tell when a module was removed from a project?

How can I obtain the Name property of a form?

How can I create a method and then assign an event handler at design-time?

How can I force the code editor to show a specific file tab?

You can either use IOTASourceEditor.Show or call IOTAActionServices.OpenFile and pass in the full path and filename of the file tab to activate.

How can I determine the filename of the binary/exe/dll/bpl/ocx/etc. generated by a compile or build?

For Delphi 8 or greater, use IOTAProjectOptions.TargetName.

For earlier releases, the method is a lot more complex to implement because it involves potentially scanning for the $E directive that specifies the executable file extension for the project, and then looking for the binary file on the path specified by the "OptputDir" project option, or the project directory if that option is blank (among many other possibilities and complexities). The best way to implement such a tool might be to start with the sample code in CodeGear CodeCentral sample ID 19823.

Known bugs in the Delphi 2007 Open Tools API (most also apply to earlier releases):

• DLL experts can cause shutdown crashes under Vista and the Windows "This program has stopped working" dialog appears (QC 44578).
• If you try to delete a component from a form using IOTAComponent.Delete, and that component is inherited from an ancestor form, the following incorrect error appears "Cannot rename component Button1, the component was introduced on ancestor form." and then the IDE gives an infinite sequence of AVs when closing the module or trying to shut down the IDE (RAID 203770).
• The indexes used for values returned by IOTAComponent.GetPropName(i) for VCL.NET do not match the indexes needed by by IOTAComponent.SetProp(i, Value), so the Index versions of GetPropValue and SetProp are unusable, since there is no way to know the right index to pass in (RAID 204184).
• After changing the name of a created project using IOTAProject.FileName, the Project Manager does not properly update the full path/file name displayed for the project (RAID 205616).
• The IOTAProjectMenuCreatorNotifier method does not fire for the project group node (RAID 213512).
• IDesigner.GetProjectModules never fires the passed callback method (QC 20589).
• You must implement IOTARepositoryWizard80 for all of the repository wizards (File|New dialog items) or they will not show up in the IDE (QC 20898).
• SplashScreenServices.AddProductBitmap does nothing with only a single personality loaded (use SplashScreenServices.AddPluginBitmap instead) (QC 42320).

Known bugs in the BDS 2006 Open Tools API (most also apply to earlier releases):

• Calling IOTAActionServices.OpenProject on any .dpr file results in the error "Invalid at the top level of the document.". You have to use IOTAActionServices.OpenFile, even though this is a project (RAID 203690).
• IOTAProjectResource is no longer implemented by any of the project's editors (QC 15657)
• RemoveMenuCreatorNotifier does not actually remove the INTAProjectMenuCreatorNotifier from the project manager (QC 38098).
• Adding a project to the existing project group fails unless the project is a package (QC 38281).

Known bugs in the Delphi 2005 Open Tools API:

• If you register a custom module using RegisterCustomModule, you will be unable to use the embedded designer with that form. The designer will always float, and you must use F12 to focus the form (fixed in BDS 2006).

Known bugs in the Delphi 7 Open Tools API (most also apply to Delphi/BCB 6):

• IOTAComponent.GetParent always returns nil.
• Calling IOTAEditView.SetTempMsg makes the code editor's Diagram tab disappear when clicking back in the source code editor.
• Several of the IOTAProjectOptions do not work such as IncludeVersionInfo and ModuleAttribs. Also, some useful options are missing such as BreakOnException. Some options such as LibraryPath are not persisted across sessions.
• The HowMany parameter of IOTAEditPosition.Delete is ignored. As a result, the method always deletes one character.
• IOTASourceEditor.SetSyntaxHighlighter is deprecated and can no longer be used
• Setting IOTAEditView.CursorPos doesn't update the edit window's cursor position in the status bar.
• The IDE does not remove instances of IOTACustomMessage from the message view before unloading an expert. This can result in crashes as the IDE calls back into an unloaded library. The workaround is to call ClearToolMessages before your expert unloads, if it added custom messages.
• IOTAToDoManager.ProjectChanged is never called.
• You can't add a keyboard binding for keys like Ctrl+/ and Ctrl+K.
• IOTAResourceEntry.DataSize must be divisible by 4 (aligned to a 4-byte boundary), or you will get an RLINK32 error when compiling.

Known bugs in the Delphi 6 Open Tools API (most also apply to Delphi/BCB 5):

• TIModuleInterface.GetFormInterface is deprecated and always returns nil. You must use IOTAFormEditor instead.
• The Open Tools keybinding interfaces sometimes raise AVs when using IOTAKeyBoardServices.AddKeyboardBinding.
• IOTAEditView.PosToCharPos raises an AV in dfwedit.dll every time it is used.
• IOTAEditorServices.TopView raises an AV in the coride package if called with no files open.

Known bugs in the C++Builder 5.01 Open Tools API:

• Given a regular unit without an associated form, calling IOTAModule.GetModuleFileCount returns 2 but IOTAModule.GetModuleFileEditor called with index 1 results in an AV and index 2 returns the .H file.
• Setting the LibDir project option using IOTAProjectOptions.Values results in an AV.

Known bugs in the Delphi 5.01 Open Tools API:

• Calling IOTAModuleServices.OpenProject on a BPG file will crash the IDE. Instead, use IOTAModuleServices.OpenFile.
• When querying IOTAProjectGroup.FileName, you won't get a full pathname. Instead query the IOTAModule that implements IOTAProjectGroup for its FileName, and it will contain a full path.
• The project options MajorVersion, MinorVersion, Release, and Build don't update the project options dialog when set.
• You can not use the keybinding interfaces to bind actions to keystrokes such as Ctrl+Enter, Shift+Enter, and non-shifted alpha-numeric characters.
• When opening a BPG file, IOTAIDENotifier will send a blank filename parameter along with ofnFileOpened into the FileNotification method.
• The IDE AVs or produces an I/O Error when specifying a file name without a complete path when implementing IOTAProjectCreator.GetFileName.