Tools API Fundamentals | C++Builder 5 Developers Guide

Before we jump into examples, it's important to understand the fundamentals of the Tools API. The Tools API provides a set of interfaces to access the IDE. Under C++Builder 6 there are 109 interfaces. If you're up on COM, you know that an interface is akin to an abstract class identifying properties and methods to a block box object. This means we're not privy to the implementation, we just know how to interface to the object containing the implementation. We can only affect the behavior contained within the implementation by what's provided through the interface methods . Like COM, Tools API interfaces are identified by a GUID, accessed using a query with an Interface ID (IID), and provide automatic reference counting for memory management.

The Tools API is really a combination of two basic categories of interfaces and services that are interrelated: the Open Tools API and the Native Tools API. In this chapter, we'll take a look at both of these APIs.

Open Tools API (OTA)

The Open Tools API (OTA) provides a set of abstract interfaces and services that allow extensions that can be applied to multiple versions of an IDE (for example, C++Builder 5, C++Builder 6, Delphi 6, and so on). You can use the OTA to write extensions that can access the source editor, the debugger, the message view, modules to a project, packages, to-do items, provide key bindings for the IDE, and much more.

The OTA is, to the core , very COM-like, which, theoretically, allows a single extension such as a wizard to work for multiple versions of C++Builder or Delphi because it is interface focused and not implementation focused ”the interface will not change across multiple versions. This also means that a wizard can be written either in Delphi or C++Builder and work for an environment representing the opposite language. In fact, any language that supports COM interfaces, which can also deal with Borland's __fastcall calling convention and the AnsiString data type, can potentially be used to write an IDE extension.

Native Tools API (NTA)

The Native Tools API (NTA) is a slightly different animal, but not by much. It provides a set of native interfaces and services into the IDE, enabling us to get directly at IDE elements (thus, some of the implementation elements). This includes components , the form designer, the menu bar, toolbar buttons , a project's action list(s) and images list(s), as well as the project's to-do list, code insight, and much more. It's pretty powerful, but keep in mind that custom extensions that use an NTA interface are often tied to the specific version of the IDE because the NTA is more implementation focused. Furthermore, because of the IDE dependency, extensions deployed as DLLs require the VCL package.

Although most discussions within newsgroups, on the Web, and in literature center primarily on the Open Tools API, make no mistake, discussion often includes aspects of the Native Tools API. That's because it's hard to focus and use the Open Tools API without also being tempted to use the Native Tools API to create IDE extensions. Basically, they are a matched pair ”like bread and butter. And, from this point forward, this chapter treats these two APIs as a combined pair.

Tools API Capabilities

To recap, the Tools API interfaces allow you to interact with, and control elements of, the IDE. These elements include the following:

main-menu bar
tool bars
action lists
image lists
source editor
keyboard macros and bindings
form editor
debugger
code completion
message view
modules
packages
To-Do list

We could go on. If you browse through the ToolsAPI.hpp file located in the Cbuilder6\source\Toolsapi folder on your system, you'll find a listing of all the available interfaces provided by the Tools API. Typically, we access and control these IDE elements through an extension we develop known as a wizard. In the example that we will build on, we'll be using many of these interfaces.

NAMING CONVENTIONS

You might have noticed, as you browsed through the Tools API header file, a number of acronyms that are used as prefixes for classes, interfaces, and data types. Table 23.1 provides a few of the more common ones used with the Tools API.

Table 23.1. Tools API Naming Convention Prefixes

Acronymn	Description
`IOTA`	Prefix representing an Open Tools API interface, which is COM-like. Custom extensions that use IOTA interfaces exclusively are not tied to the specific version of the IDE, allowing the extension to be useful for other versions of the Borland IDE.
`INTA`	Prefix representing a Native Tools API interface, which provides direct (native) access to IDE objects. Custom extensions that use a Native Tools interface are tied to the specific version of the IDE and require the VCL package for DLL implementations .
`_di_`	Prefix used to represent a Delphi Interface wrapper around an interface. In C++Builder, these data types are used in code for declaring variables to associate to an interface.
`IIDG`	Used to identify an Interface ID for an interface. ( COM programmers should know this one ).

As stated in the Borland Help, using the Tools API within an extension you might develop (that is, a wizard) is simply a matter of writing classes that implement certain interfaces, and calling on services provided by other interfaces. In fact, writing a Tools API class is similar to writing a property or component editor. The Tools API-based code you develop can be compiled and installed into the IDE as a design time VCL package. It's also possible to provide extensions to the IDE through a DLL, but the DLL has to be identified in the Windows Registry with the IDE for its extensions to take affect. We'll talk more about DLLs a little later in the chapter.

NOTE

If you're not familiar with VCL packages and registering components, you might want to review the material provided in Chapter 4, which focuses on VCL Components and Packages.

Top