This library contains several helpers and classes to make working with the ToolsAPI much easier. It's so much fun to extend the IDE with your own tools and options, but it is sometimes very hard to find out how to do it. With this library we will contribute to the Delphi community and make it more simple to build your own IDE extensions.
Project group and projects (incl. build, environment options, module sync)
IDE extensions run inside the Delphi IDE, so the library is used from a package (.dpk) project:
- Clone this repository
- Add the repository root to the search path of your package project, or add the units you need directly
- Make sure your package requires
DesignIDE, like the includedGdkToolsApiHelper.dpk - Create a
TToolsApiHelperinstance and explore the examples below
The included GdkToolsApiGroupProject.groupproj contains the library package and the DUnitX unit tests (UnitTesting folder).
- Delphi 10.3 Rio or later (the code uses inline variable declarations)
With the Logger functionality you can add messages to the message tool window.
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
var Logger := Helper.Logger;
// Log just a message
Logger.Log('This is an example logging');
// Log a message with formatting
Logger.Log('This is a message for project: %s', [Project.Name]);
Or start the Logger with your own group name. This creates a separate tab in the message tool window with that name.
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
var Logger := Helper.Logger('MyLogTab');Use the custom option to create message with different colors or referencing to a file. In that case double clicking the message will open the file.
var CustomMessage := Logger.Custom;
// Setup
CustomMessage.TextColor := clGreen;
CustomMessage.SetFileReference(FilePath, LineNumber);
// Show message
CustomMessage.Add('[%s] Error on line %d', [FilePath, LineNumber]);Get the loaded project group as follows:
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
var ProjectGroup := Helper.ProjectGroup;For a project the IToolsApiProject interface is used. This interface groups a list of project related features. This interface can be received in two ways: for the active project or for the given project
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
// Get the active projectvar ProjectHelper := Helper.Project;
var ActiveProject: IOTAProject := ProjectHelper.Get;
// Get the interface for a given projectvar ProjectHelper := Helper.Project(OTAProject);With the IToolsApiProject interface you have access to the project options and the build configurations.
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
// Get the active projectvar ProjectHelper := Helper.Project;
// Get the project options to figure out the platforms used, the active platform, etc.var ProjectOptions: IOTAProjectOptionsConfigurations := ProjectHelper.ProjectConfigurations;The build configurations are wrapped in IToolsApiBuildConfigurations and IToolsApiBuildConfiguration. With a specific build configuration interface it's easy to get and change the search paths for a project.
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
// Get the active projectvar ProjectHelper := Helper.Project;
// Get the base build configurationvar BaseBuildConfig: IToolsApiBuildConfiguration := ProjectHelper.BuildConfigurations.Base;
// Get the search pathsvar SearchPaths: TArray<string> := BaseBuildConfig.SearchPaths;
// Change the paths
SearchPaths := SearchPaths + [NewFilePath];
BaseBuildConfig.SearchPaths := SearchPaths;The Build function builds the project with the IDE compiler, like Project > Build. It returns True when the build succeeded.
By default the IDE shows the compile progress dialog. When a build fails, that dialog stays open as a modal dialog until the user dismisses it, and Build only returns after that. For unattended builds (for example builds triggered by an IDE plugin) pass HideProgressDialog := True: the "Show compiler progress" option is then disabled during the build and restored afterwards, so a failing build returns immediately. The compiler messages still appear in the message tool window.
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
// Build the active project without blocking on the progress dialogvar Succeeded := Helper.Project.Build(True);The IDE environment options (Tools > Options) are wrapped in IToolsApiEnvironmentOptions. Option names can differ between IDE versions, so TryFindOptionName looks up the exact registered name first.
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
var EnvironmentOptions := Helper.EnvironmentOptions;
var ExactName: string;
if EnvironmentOptions.TryFindOptionName('ShowCompilerProgress', ExactName) thenbeginvarValue := EnvironmentOptions.GetOption(ExactName);
EnvironmentOptions.SetOption(ExactName, False);
end;A file open in the IDE can be newer in memory than on disk (or vice versa when an external tool edits it). IToolsApiModule exposes IsDirty, MatchesDisk and SyncWithDisk to reason about this. SyncWithDisk reloads the module from disk when the buffer is unmodified, and raises EToolsApiModuleOutOfSync when both sides changed (a real conflict).
varModule: IToolsApiModule := THelper.Module;
ifnotModule.MatchesDisk thenModule.SyncWithDisk; // reloads if safe, raises on conflictIToolsApiProject.CreateFormUnit creates a new form unit through IOTAModuleServices.CreateModule, adds it to the project and opens the designer. The unit and .dfm source are generated by the library (not left to the IDE default template, which mangles the class name), so the class is exactly T<FormName>. AncestorName is without the leading T (empty means TForm).
varHelper: IToolsApiHelper := TToolsApiHelper.Create;
Helper.Project.CreateFormUnit('C:\proj\FMain.pas', 'MainForm', 'TForm');IToolsApiModule.FormDesigner returns an IToolsApiFormEditor for component-level access to an open form designer, like the palette and Object Inspector:
var Designer := THelper.Module.FormDesigner;
// Inspectforvar Component in Designer.Components do
; // Component.Name, .ClassName, ...var Events := Designer.AssignedEvents(Designer.Root); // ['OnClick=Button1Click', ...]// Add a control to a named container (forced to the exact parent, e.g. a TabSheet)var Edit := Designer.AddComponent('TEdit', 'pnlDetail', 8, 8, 200, 23);
// Set published properties by text, including nested paths, sets, events and// component references:
Designer.SetComponentProperty('Edit1', 'Text', 'hello');
Designer.SetComponentProperty('Edit1', 'Font.Size', '12');
Designer.SetComponentProperty('Button1', 'OnClick', 'Button1Click'); // binds/creates handler
Designer.SetComponentProperty('PageControl1', 'ActivePage', 'TabSheet1'); // component referenceAddComponent captures the native container before creating and forces the new control's Parent, so it lands on exactly the requested tab/page (not the active one). Any installed component class works (VCL, TMS, DevExpress, ...).
IToolsApiFormEditor.CaptureImage renders the designed form to a PNG (via TCustomForm.GetFormImage), returned as TBytes.
IToolsApiHelper.Debugger returns an IToolsApiDebugger around IOTADebuggerServices: source breakpoints, process control (continue/step/pause/terminate), expression evaluation (deferred-aware) and the call stack.
var Debugger := THelper.Debugger;
Debugger.AddBreakpoint('C:\proj\FMain.pas', 42);
// ... run the project ...if Debugger.State = TToolsApiProcessState.Stopped thenbeginvarValue := Debugger.Evaluate('Customer.Name');
forvar Frame in Debugger.CallStack do
; // Frame.Header, .FileName, .LineNumberend;The TToolsApiUsesManager class is located in GDK.ToolsAPI.UsesManager.pas and provides the following methods:
WithSource: sets the source code of the unit to be parsedFindUses: searches the source code for the interface and implementation sections, as well as the uses clause, and returns the results as aTUsesResultrecordFindWord: searches the source code for a given word and returns the first match as aTMatchobjectFindPositionToAdd: searches the source code for the position where a new unit should be added to the uses clause, and calls a callback function with the position and a Boolean indicating whether the uses clause is currently empty
The TToolsApiUsesManager class also defines some private methods for finding the positions of certain keywords in the source code.
The IToolsApiUsesManager interface is used to define the public methods of the TToolsApiUsesManager class. The interface includes the same methods as the class.
MIT License, see the LICENSE file for details.
Contributions are welcome! Please open an issue or submit a pull request.
This library is MIT licensed and free to use. For companies that depend on it commercially we offer support and maintenance agreements with guaranteed response times, and sponsored development of features you need. Contact us at gdksoftware.com/contact-us or open an issue to get in touch.