A ToolsAPI é um dos recursos mais poderosos do Delphi. Por meio dela é possível criar extensões que se integram diretamente ao ambiente de desenvolvimento, adicionando menus, janelas acopláveis (Dockable Forms), atalhos de teclado, refatorações de código e diversas outras funcionalidades.

Ferramentas amplamente conhecidas pela comunidade Delphi, como GExperts e CnPack, utilizam a ToolsAPI para ampliar os recursos da IDE sem modificar seu código interno.

Um erro bastante comum entre desenvolvedores que começam a trabalhar com plugins é manipular diretamente componentes visuais internos da IDE, como menus e popups. Embora essa abordagem possa funcionar inicialmente, ela costuma causar problemas de compatibilidade entre versões, vazamentos de memória e Access Violations durante o encerramento da IDE.

Neste artigo veremos a forma correta e suportada pela Embarcadero para adicionar menus e submenus à IDE Delphi utilizando as APIs oficiais da ToolsAPI.

O que é a ToolsAPI?

A ToolsAPI é um conjunto de interfaces disponibilizadas pela Embarcadero para permitir a extensão da IDE Delphi.

Ela possibilita acesso a diversos recursos internos, incluindo:

• Projetos carregados na IDE;
• Editor de código;
• Menus da IDE;
• Atalhos de teclado;
• Janelas dockáveis;
• Refatorações;
• Navegação entre módulos;
• Eventos da IDE.

Todas as interfaces principais estão definidas na unit:

ToolsAPI.pas

Localizada normalmente em:

$(BDS)\source\ToolsAPI

Menu Principal da IDE

Para adicionar itens ao menu principal da IDE devemos utilizar a interface:

INTAServices

O método responsável pela inclusão de novos itens é:

AddActionMenu

Exemplo:

uses
  ToolsAPI,
  Vcl.ActnList;

procedure AddMenu;
var
  NTAServices: INTAServices;
  Action: TAction;
begin
  if Supports(BorlandIDEServices, INTAServices, NTAServices) then
  begin
    Action := TAction.Create(nil);
    Action.Caption := 'Regys Tools';

    NTAServices.AddActionMenu(
      'ToolsMenu',
      nil,
      Action
    );
  end;
end;

Neste exemplo o menu será adicionado ao menu “Tools” da IDE.

Menu de Contexto do Editor

Quando desejamos adicionar opções ao menu exibido ao clicar com o botão direito dentro do editor de código, devemos utilizar:

INTAEditorLocalMenu

Essa interface foi criada especificamente para gerenciar o menu contextual do editor.

A obtenção da interface é feita da seguinte forma:

var
  EditorMenu: INTAEditorLocalMenu;
begin
  if Supports(BorlandIDEServices,
              INTAEditorLocalMenu,
              EditorMenu) then
  begin
    ...
  end;
end;

Criando Submenus Corretamente

Uma das funcionalidades menos conhecidas da ToolsAPI é a criação automática de submenus através da propriedade Category das actions.

A estrutura hierárquica é definida utilizando o caractere ponto (.).

Por exemplo:

RegysTools
RegysTools.Geradores
RegysTools.Geradores.Delphi
RegysTools.Geradores.React
RegysTools.Utilitarios

O Delphi interpretará automaticamente essa estrutura como:

Regys Tools
 ├─ Geradores
 │   ├─ Delphi
 │   └─ React
 │
 └─ Utilitários

Exemplo Completo

Criando uma ActionList:

var
  ActionList: TActionList;

Criando uma action:

var
  Act: TAction;
begin
  Act := TAction.Create(ActionList);

  Act.Name := 'actGerarClasse';
  Act.Caption := 'Gerar Classe Delphi';
  Act.Category := 'RegysTools.Geradores.Delphi';

  ActionList.AddAction(Act);
end;

Registrando a lista:

EditorMenu.RegisterActionList(
  ActionList,
  cEdMenuCatBase
);

Ao abrir o menu contextual do editor o submenu será criado automaticamente.

A Importância da Ordem das Actions

Um detalhe importante documentado pela Embarcadero é que a ordem das actions influencia diretamente na criação dos submenus.

A ordem correta é:

RegysTools
RegysTools.Geradores
RegysTools.Geradores.Delphi
RegysTools.Geradores.React

A ordem incorreta é:

RegysTools.Geradores.React
RegysTools
RegysTools.Geradores

Quando uma action filha é registrada antes do menu pai, o submenu pode não ser exibido.

Liberando Recursos Corretamente

Outro erro comum é esquecer de remover as actions registradas quando o plugin é descarregado.

Durante a finalização do package:

EditorMenu.UnregisterActionList(
  ActionList
);

Depois disso:

FreeAndNil(ActionList);

Essa etapa evita referências inválidas e Access Violations ao encerrar a IDE.

Boas Práticas

Ao desenvolver extensões para Delphi, recomenda-se:

• Utilizar sempre as interfaces oficiais da ToolsAPI;
• Evitar acessar componentes internos da IDE;
• Utilizar Supports antes de converter interfaces;
• Separar menus, ações e serviços em unidades distintas;
• Registrar e remover recursos corretamente;
• Testar em múltiplas versões do Delphi;
• Utilizar projetos como GExperts como referência arquitetural.

Estrutura Recomendada para Plugins

Uma organização simples e eficiente pode ser:

MeuPlugin
│
├── Wizard Principal
├── Menu Manager
├── Editor Manager
├── Keyboard Manager
├── Services
└── Shared Types

Essa abordagem facilita manutenção e evolução futura do plugin.

Conclusão

A ToolsAPI oferece uma forma segura, documentada e compatível de estender a IDE Delphi. Ao utilizar interfaces como INTAServices e INTAEditorLocalMenu, é possível adicionar menus, submenus e funcionalidades avançadas sem depender de hacks ou modificações internas da IDE.

Além de aumentar a estabilidade da solução, essa abordagem garante maior compatibilidade entre versões do Delphi, reduzindo problemas de manutenção e facilitando futuras atualizações.

Para desenvolvedores que desejam criar ferramentas profissionais para Delphi, compreender a arquitetura da ToolsAPI é um passo fundamental.

Referências Bibliográficas

EMBARCADERO TECHNOLOGIES. ToolsAPI.INTAEditorLocalMenu.RegisterActionList. Disponível em: https://docwiki.embarcadero.com/Libraries/Athens/en/ToolsAPI.INTAEditorLocalMenu.RegisterActionList. Acesso em: 4 jun. 2026.

EMBARCADERO TECHNOLOGIES. ToolsAPI Support for the Code Editor. Disponível em: https://docwiki.embarcadero.com/RADStudio/Athens/en/ToolsAPI_Support_for_the_Code_Editor. Acesso em: 4 jun. 2026.

EMBARCADERO TECHNOLOGIES. Adding an Item to the Main Menu of the IDE. Disponível em: https://docwiki.embarcadero.com/RADStudio/Athens/en/Adding_an_Item_to_the_Main_Menu_of_the_IDE. Acesso em: 4 jun. 2026.

EMBARCADERO TECHNOLOGIES. Extending the IDE Using the Tools API. Disponível em: https://docwiki.embarcadero.com/RADStudio/Athens/en/Extending_the_IDE_Using_the_Tools_API. Acesso em: 4 jun. 2026.

EMBARCADERO TECHNOLOGIES. ToolsAPI Reference. Disponível em: https://docwiki.embarcadero.com/Libraries/Athens/en/ToolsAPI. Acesso em: 4 jun. 2026.

GEXPERTS DEVELOPMENT TEAM. GExperts. Disponível em: https://github.com/gexperts/gexperts. Acesso em: 4 jun. 2026.