Native Plugins

[Logic-gate]

Have a look at Path Completion Plugin for an example.

The Native Plugin API provides a small, stable ABI for trusted native plugins. Plugins interact with the editor through opaque host and command-context objects instead of accessing EditorWindow, EditorTab, or GTK internals directly.

This separation allows Graptos to change its internal editor implementation without unnecessarily breaking plugin source code.

API version

#define GRAPTOS_PLUGIN_API_VERSION 1u

Plugins should compare this value with the version returned by graptos_plugin_host_api_version() during registration and reject incompatible Graptos builds before registering commands or completion providers.

Header and dependency

#include <glib.h>
#include "plugin_api.h"

The API uses GLib types such as gboolean, guint, gpointer, and GPtrArray.

Core concepts

Object	Purpose
GraptosPluginHost	Opaque capability object supplied while a plugin registers its functionality
GraptosPluginCommandContext	Opaque execution context describing the active editor state when a command or completion provider runs
Plugin manifest	Declares plugin identity and permissions; native code supplies command behavior and visible labels

Plugins must use the public functions documented here and must not depend on Graptos or GTK implementation internals.

Ownership rules

• Strings described as owned must be released by the plugin with g_free().
• Strings returned without an ownership note remain owned by Graptos and must not be freed or modified.
• A plugin ID returned by graptos_plugin_host_plugin_id() remains valid only while the host object is alive. Copy it if it must be retained.
• Graptos copies completion candidate text before displaying it.
• A registered destroy callback is responsible for releasing the corresponding plugin-owned user_data.

Opaque types

GraptosPluginHost

typedef struct _GraptosPluginHost GraptosPluginHost;

The host capability object passed to native plugins during registration.

GraptosPluginCommandContext

typedef struct _GraptosPluginCommandContext GraptosPluginCommandContext;

The execution context passed to native command and completion callbacks. It provides controlled access to the active editor, selection, cursor, file, tabs, and project.

Callback types

Command callback

typedef void (*GraptosPluginCommandFunc)(
    GraptosPluginCommandContext *context,
    gpointer user_data
);

Called when a registered command is invoked from a menu, tool panel, shortcut, or another command surface.

Parameter	Description
context	Execution context for the current editor command
user_data	Plugin data supplied during command registration

Completion callback

typedef GPtrArray *(*GraptosPluginCompletionFunc)(
    GraptosPluginCommandContext *context,
    char **replace_prefix_out,
    gpointer user_data
);

Inspects the cursor context and returns insertable completion candidates. The provider determines whether it applies by returning candidates only for matching contexts.

Parameter	Description
context	Execution context for the current cursor
replace_prefix_out	Receives the owned prefix Graptos should replace when a candidate is accepted
user_data	Plugin data supplied during provider registration

Returns a GPtrArray of owned char * candidates, or NULL when no candidates are available.

Destroy callback

typedef void (*GraptosPluginDestroyFunc)(gpointer user_data);

Releases plugin-owned data supplied during command or provider registration.

Registration entry point

typedef gboolean (*GraptosPluginRegisterFunc)(GraptosPluginHost *host);

A shared library exports this entry point when it provides code-backed editor automation. Declarative-only plugins do not require a native entry point.

Returns TRUE when registration succeeds.

Host information

graptos_plugin_host_api_version

guint graptos_plugin_host_api_version(GraptosPluginHost *host);

Returns the plugin API version implemented by the host. Plugins can use it during registration to detect incompatible Graptos builds.

graptos_plugin_host_plugin_id

const char *graptos_plugin_host_plugin_id(GraptosPluginHost *host);

Returns the ID of the plugin currently being registered, or NULL when unavailable. The string is owned by Graptos and remains valid only while the host is alive.

Registration functions

Register a command implementation

gboolean graptos_plugin_host_register_command(
    GraptosPluginHost *host,
    const char *command_id,
    GraptosPluginCommandFunc callback,
    gpointer user_data,
    GraptosPluginDestroyFunc destroy
);

Registers command behavior without adding the command to editor line menus or the Plugins tool panel. Use graptos_plugin_host_register_editor_line_command() when those UI surfaces are required.

Parameter	Description
host	Host capability object supplied by Graptos
command_id	Command ID declared by the plugin manifest
callback	Native function invoked for the command
user_data	Plugin data passed to the callback
destroy	Optional callback that releases user_data

Returns TRUE when the command is accepted.

Register an editor line command

gboolean graptos_plugin_host_register_editor_line_command(
    GraptosPluginHost *host,
    const char *command_id,
    const char *label,
    GraptosPluginCommandFunc callback,
    gpointer user_data,
    GraptosPluginDestroyFunc destroy
);

Registers a command and exposes it in editor right-click menus and the Plugins tool panel.

Parameter	Description
host	Host capability object supplied by Graptos
command_id	Stable command ID owned by the plugin
label	Human-facing command label
callback	Native function invoked for the command
user_data	Plugin data passed to the callback
destroy	Optional callback that releases user_data

Returns TRUE when the command is accepted.

Register an editor line command with a shortcut

gboolean graptos_plugin_host_register_editor_line_command_with_shortcut(
    GraptosPluginHost *host,
    const char *command_id,
    const char *label,
    const char *shortcut,
    GraptosPluginCommandFunc callback,
    gpointer user_data,
    GraptosPluginDestroyFunc destroy
);

Registers an editor line command with an optional keyboard shortcut. Graptos owns shortcut matching and invokes the registered command when the shortcut is pressed.

The shortcut uses a stable textual form such as Ctrl+Alt+P. Pass NULL when no shortcut is required.

Returns TRUE when the command is accepted.

Register a completion provider

gboolean graptos_plugin_host_register_completion_provider(
    GraptosPluginHost *host,
    const char *provider_id,
    const char *label,
    GraptosPluginCompletionFunc callback,
    gpointer user_data,
    GraptosPluginDestroyFunc destroy
);

Registers a native provider that participates in normal editor completion.

Parameter	Description
host	Host capability object supplied by Graptos
provider_id	Stable provider ID owned by the plugin
label	Human-facing source label
callback	Native completion callback
user_data	Plugin data passed to the callback
destroy	Optional callback that releases user_data

Returns TRUE when the provider is accepted.

Context metadata

Plugin ID

const char *graptos_plugin_context_plugin_id(
    GraptosPluginCommandContext *context
);

Returns the plugin ID associated with the command context, or NULL.

Command ID

const char *graptos_plugin_context_command_id(
    GraptosPluginCommandContext *context
);

Returns the command ID associated with the context, or NULL.

Target line

guint graptos_plugin_context_line(
    GraptosPluginCommandContext *context
);

Returns the targeted editor line as a one-based line number, or 0 when no editor line is available.

Reading editor state

Active file path

char *graptos_plugin_context_file_path(
    GraptosPluginCommandContext *context
);

Returns the active file path, or NULL for an unsaved editor. The returned string is owned by the caller and must be released with g_free().

Active editor text

char *graptos_plugin_context_text(
    GraptosPluginCommandContext *context
);

Returns all text in the active editor, or an empty string when unavailable. The returned string is owned by the caller and must be released with g_free().

Active selection

char *graptos_plugin_context_selection(
    GraptosPluginCommandContext *context
);

Returns the selected text, or an empty string when there is no selection. The returned string is owned by the caller and must be released with g_free().

Text from one line

char *graptos_plugin_context_line_text(
    GraptosPluginCommandContext *context,
    guint line
);

Returns the text from the requested one-based editor line, or an empty string when unavailable. The returned string is owned by the caller and must be released with g_free().

Text before the cursor

char *graptos_plugin_context_line_prefix(
    GraptosPluginCommandContext *context
);

Returns the text before the cursor on the active line, or an empty string when unavailable. The returned string is owned by the caller and must be released with g_free().

Editing the active buffer

Insert text

gboolean graptos_plugin_context_insert_text(
    GraptosPluginCommandContext *context,
    const char *text
);

Inserts text at the active cursor. Returns TRUE when the text is inserted.

Replace the selection

gboolean graptos_plugin_context_replace_selection(
    GraptosPluginCommandContext *context,
    const char *text
);

Replaces the active selection. If no text is selected, the supplied text is inserted at the cursor. Returns TRUE when the buffer is updated.

User-interface output

Show output in a dialog

void graptos_plugin_context_show_output(
    GraptosPluginCommandContext *context,
    const char *title,
    const char *heading,
    const char *body
);

Displays plugin-generated output in a Graptoss dialog.

Set the status text

void graptos_plugin_context_set_status(
    GraptosPluginCommandContext *context,
    const char *text
);

Sets the Graptos status text.

Show completions

void graptos_plugin_context_show_completions(
    GraptosPluginCommandContext *context,
    const char *replace_prefix,
    const char *source_label,
    GPtrArray *candidates
);

Shows plugin-supplied completion candidates.

Parameter	Description
context	Current command context
replace_prefix	Exact text immediately before the cursor that should be replaced
source_label	Visible completion-source heading
candidates	GPtrArray of owned or borrowed char * candidate strings

Graptos copies the candidate text before displaying the completion popup.

Tabs, projects, and files

Open tab count

guint graptos_plugin_context_tab_count(
    GraptosPluginCommandContext *context
);

Returns the number of open editor tabs.

First project root

char *graptos_plugin_context_project_root(
    GraptosPluginCommandContext *context
);

Returns the first open project root, or NULL when no project is open. The returned string is owned by the caller and must be released with g_free().

Open a file

gboolean graptos_plugin_context_open_file(
    GraptosPluginCommandContext *context,
    const char *path
);

Opens the file at path in Graptos. Returns TRUE when the file is opened.

Registration outline

A native plugin generally follows this sequence:

1. Export its registration entry point.
2. Read the host API version and verify compatibility.
3. Register commands, editor line actions, shortcuts, or completion providers.
4. Use only the supplied command context while handling an invocation.
5. Release caller-owned strings with g_free().

gboolean
graptos_plugin_register(GraptosPluginHost *host)
{
    if (graptos_plugin_host_api_version(host) !=
        GRAPTOS_PLUGIN_API_VERSION) {
        return FALSE;
    }

    return graptos_plugin_host_register_editor_line_command_with_shortcut(
        host,
        "example.transform-line",
        "Transform Line",
        "Ctrl+Alt+P",
        transform_line,
        NULL,
        NULL
    );
}

The exact exported symbol name and shared-library loading convention must match the Graptos plugin loader and plugin manifest specification.