add-a-command.md

Recipe: add a command

A command is an action the user can run from the command palette (Ctrl+K), a keyboard shortcut, a toolbar button, or a menu.

Extension point: colibri.ui.ide.commands.CommandExtension Working example: the Hello From Plugin command in ExamplePlugin.ts.

Pattern

Add a CommandExtension in registerExtensions. Its constructor takes a function that receives the CommandManager:

reg.addExtension(new colibri.ui.ide.commands.CommandExtension(manager => {

    manager.addCategory({ id: CAT_EXAMPLE, name: "Example Plugin" });

    manager.add({
        command: {
            id: CMD_HELLO,                 // "myplugin.example.hello"
            category: CAT_EXAMPLE,
            name: "Hello From Plugin",
            tooltip: "Example custom command."
        },
        handler: {
            executeFunc: args => { alert("Hello!"); },
            // optional: only enabled when testFunc returns true
            // testFunc: args => args.activeEditor instanceof MyEditor,
        },
        keys: { control: true, alt: true, key: "H" }   // optional Ctrl+Alt+H
    });
}));

Define the ids as namespaced constants:

export const CAT_EXAMPLE = "myplugin.example";
export const CMD_HELLO = "myplugin.example.hello";

The handler args

executeFunc(args) and testFunc(args) receive a HandlerArgs with the active part, editor, selection, and window. Grep types/colibri.d.ts for HandlerArgs to see the fields. A common testFunc scopes a command to your editor:

testFunc: args => args.activeEditor instanceof MyEditor

Reusing a built-in command

To make a global command (e.g. Delete) do something in your editor, pass its id as the second argument to manager.add(...) with just a handler — see how TodoEditor reuses colibri.ui.ide.actions.CMD_DELETE in TodoEditor.ts.

Putting a command on a toolbar

Inside an editor, override createEditorToolbar(parent) and use a ToolbarManager:

const manager = new colibri.ui.controls.ToolbarManager(parent);
manager.addCommand(CMD_ADD_TASK, { showText: true, text: "Add Task" });
return manager;

Checklist

• Ids are namespaced (<pluginId>.<Name>).
• Registered via reg.addExtension(new CommandExtension(...)).
• npm run build passes.