Open Tools API Browser ------------------------ (c) 1997-2000 Lucian Wischik INSTALLATION Start up BCB5. Do Component|InstallPackage and select the OTABROWSE5.BPL package. It will install itself into your Help menu, and show a diagnostic log in lower corner. OVERVIEW The Open Tools API is the interface with which experts communicate with the IDE. You will find yourself using the Open Tools API when you write your own experts. This utility is designed to help you familiarise yourself with their behaviour and functionality. The Open Tools API are not well documented within C++Builder. The concepts are similar to the Tools Services in Delphi3 -- to learn about them, you should buy the book "Hidden Paths of Delphi3" by Ray Lischner. But the organization has changed a lot. You should visit Ray's web site to see how it was changed for Delphi4 (which is similar to BCB5). Or, you can look at the pascal file (cbuilder5\source\ toolsapi\toolapi.pas) yourself to try to figure out what they are doing. Most programmers of the OpenToolsAPI do it in Delphi. With documentation so sparse and incomplete and Pascalised, it's very useful to be able to see directly what facilities are available, and to play around with them interactively, and to have a complete C++ source code base to copy. This Open Tools API Browser aims to provide these things. This Browser also adds some extra tools services, including a property editor for a property that is the name of some other form in the project. (and if you rename or delete that other project, this property updates itself automatically). There is a sample component to demonstrate how to use these extra featres. USING OPEN TOOLS API BROWSER Do Help|OTABrowser. A dialog will pop up representing the IDEServices interfaces. About half of the functionality is implemented so far. Generally, each form corresponds to an interface, and each button corresponds to a function. Thus, when you click the ModuleServices button and it brings up a new form, then there in the code there is a function call GetModuleServices() which returns an interface to them. Generally, you first have to supply the arguments to a function in the fields to the left of the button; if it gives an answer, that answer is generally displayed to the right of the button. Some forms contain lists of things. For instance, the ModuleServices form contains a list of all currently open modules. This corresponds to the pair of functions GetModuleCount() and GetModule(i); they have been called already so you can see what's there. Double-click on one of the modules to open up its interface form. Note that you are instructed not to keep posession of the various interfaces for too long. I suspect that if you try to edit in the buffers while having the Browser up, bizarre things might happen. (The exception is that you can keep Notifier windows up!) There's lots of stuff in here! The following diagram shows most of the forms that have been implemented so far. For instance, to display and edit the properties of a component, you start with the OTABrowser. ModuleServices. Open a form module. GetModuleFileEditor. (In fact there are three module file editors - for file.h, file.cpp and file.dfm. Try each of them. You want the editor for file.dfm). Then open a component to see its properties, and you can set them. OTABrowser +-ActionServices (close file, open file, ...) +-PackageServices (list all installed packages and components) +-Services (information about the app itself) | +-AddNotifier (add a project notifier) | +-ProjectNotifier +-ModuleServices (list all modules, get a module, create a module, file-menu ops) | +-CreateModule, CreateProject, CreateProjectGroup | +-GetModule | +-GenericModuleOperations (close, save, set filename) | +-Notifiers (add a module notifier) | | +-ModuleNotifier | +-Constituents (get module file editor for files in this module, get owning project) | | +-GenericModuleEditor (get filename, mark modified, show) | | +-ResourceEditor (list of resources, get resource, create resource) | | | +-Resource Entry (display the resource, change name, type, contents) | | +-FormEditor (displays all components on form, get, create component, add notifier) | | +-Component (displays all properties of component, set any property) | | +-FormNotifier | +-Project (list modules that make up this project, add, remove file) | +-ProjectGroup (list projects that make up group, add, remove projects, get active proj) +-WatcherServices (keeps track of all live components in the IDE) +-General (notifications of all component and form renames/deletions) +-Specific (keep track of a single specified component on any form) +-Plonks (be alerted when a component is plonked down on a form) +-Props (keep track of every single instance of a property) TOOLS API PLUS A couple of useful functions have been included to extend the Tools API: - create/delete bitmaps or icons in the project resources - set the "Picture" property of a TImage - get or set the text value for any property - handy navigation functions between the various IOTA interfaces - RegisterPlonkVerb, to execute a particular verb whenever a component is inserted - RegisterPropertyWatcher, to be told of every instance of a property anywhere - NameNotification, to be told when a form or component anywhere is renamed - TFormScanner, to scan through all modules, forms, components in the project - TFormNamePropertyEditor, for text properties that are the names of forms in the project - TFormTypePropertyEditor, for text properties like "TForm1" - TComponentNamePropertyEditor, for text properties that are component names on any form - TSwappingComponentEditor, for a component that can substitute another one for itself Documentation is in the file toolsapiplus.h There's an example component, in the file sample.cpp, to demonstrate the new form-scanner, the Registers, and the property and component editors. I haven't provided a runtime for the sample component because there isn't any point. You can't use it in an end project. To see examples of using the other functions, see how they're called from within the OTABrowser. BUGS There's a bug somewhere OTABrowser's notifier forms. You'll get notifications okay, but it will crash sometimes. If you're looking for how to code notifiers yourself like the IOTAModuleNotifier, look in the source code for toolsapiplus.cpp VERSIONS 5.2 Rewrote The Watcher in a more elegant style to fix some IDE dangling pointers 5.1 Added The Watcher services and associated property editors and register funcs. 5.0 Updaged to BCB5. Upgraded from ToolsServices to OpenToolsAPI. 4.0 Upgraded to BCB4. Added ability to delete icon-group. 3.5 Added "Quick! straight to project resources" 3.4 Added resource things, including functions AddIconResource and AddBitmapResource 3.3 Added project notifiers. 3.2 Added module notifiers. 3.1 Added stuff to access the VCL components that make up the IDE itself: 3.0 Upgraded it to work with BCB3 1.0 Initial release -- Lucian Wischik, Queens' College, Cambridge CB3 9ET. www.wischik.com/lu