Plugin API — overview

All PluginApi types live in namespace MTE::plugin. The public headers may not include any Qt, Scintilla, or MTE-internal header — only the standard library.

The service locator

initialize() receives an IPluginContext, a service locator owned by the host. Do not store the context past initialize(); store the individual service references you need (each service outlives every plugin):

class IPluginContext {
public:
    virtual IEditorService&      editor()      = 0;
    virtual ICommandRegistry&    commands()    = 0;
    virtual IMenuRegistry&       menus()       = 0;
    virtual IDockRegistry&       docks()       = 0;
    virtual IEventBus&           events()      = 0;
    virtual ICompletionRegistry& completions() = 0;
    virtual ILogger&             log()         = 0;
    virtual std::filesystem::path pluginDataDir() const = 0;
    // plus statusBar(), settings(), appSettings(), settingsRegistry();
    // see the header for the full list.
};

Extending the API later means adding a new service interface and accessor; existing plugins stay source- and ABI-compatible.

IEditorService — the document model

The editor as seen by plugins — no Scintilla, no Qt. Documents are referenced by an opaque DocumentId (std::uint64_t, 0 = invalid):

DocumentId               activeDocument() const;
std::vector<DocumentId>  openDocuments() const;
std::string              text(DocumentId) const;
void                     setText(DocumentId, std::string_view);
std::string              selectedText(DocumentId) const;
void                     replaceSelection(DocumentId, std::string_view);
EditorPosition           caret(DocumentId) const;
void                     setCaret(DocumentId, EditorPosition);
DocumentId               openFile(std::filesystem::path);
bool                     saveDocument(DocumentId);
std::optional<std::filesystem::path> filePath(DocumentId) const;

It also exposes the split-view tab-group layout in backend-neutral terms (groupCount(), groupOf(), groupWeights(), moveDocumentToGroup(), setGroupWeights()), so a plugin can capture and restore pane arrangements without seeing Qt's splitter.

Other services

• ICommandRegistry / IMenuRegistry — register user-invocable commands and place them in menus.
• IDockRegistry — contribute dockable side panels via a factory (the host controls lifetime and threading).
• IEventBus — subscribe to editor events.
• ILogger — structured logging at Trace/Debug/Info/Warning/Error.

Versioning

MTE_PLUGIN_API_VERSION (currently 1) is defined in PluginApi/PluginInfo.h. A plugin must advertise the same value in both plugin.json and IPlugin::info().apiVersion, or the host refuses to load it.

Pre-release policy

Before the first public release the contract may still change without bumping MTE_PLUGIN_API_VERSION. After release, any backwards-incompatible change to an existing interface bumps the version.