Commands and actions

​

Declare a command

[[contributes.commands]]
id = "count"                          # [a-z0-9][a-z0-9._-]*
title = "Word Tools: Count Words"
category = "Word Tools"               # group in Find Action and the keymap editor
when = "editorFocus"                  # optional enablement
# icon = "run"                        # API 1.4: built-in icon name or a package SVG

​

when clauses

• editorFocus: a text editor has focus.
• editorLangId == sql: the focused editor’s language id.
• workspaceContains:pom.xml: the open project contains that exact path (relative to the project root, no globs). In a workspace it is true when any project contains it, and it updates as files change. An IDE that doesn’t know the key treats it as false.
• plugin.<plugin-id>.<key>: a key the plugin set itself with host::set_context (below).

​

Run the command

use openidea_plugin::{Error, Invocation, NotificationLevel, Plugin, host, register_plugin};

#[derive(Default)]
struct WordTools;

impl Plugin for WordTools {
    fn run_command(&mut self, id: &str, ctx: &Invocation, _arg: Option<&str>) -> Result<Option<String>, Error> {
        let editor = ctx.editor().ok_or("no file is open")?;
        match id {
            "count" => {
                let words = editor.document()?.text.split_whitespace().count();
                host::notify(NotificationLevel::Info, "Word count", &format!("{words} words"));
                Ok(None)
            }
            // Every selection (a cursor: empty) in one undoable change.
            "shout" => {
                editor.transform_selections(|s| s.to_uppercase())?;
                Ok(None)
            }
            _ => Err(Error::NotFound(format!("command {id}"))),
        }
    }
}

register_plugin!(WordTools);

• Ok(Some(text)) is shown to the user; Ok(None) shows nothing.
• An error shows “<title> failed: …” and the plugin keeps running. "msg".into() is Error::Failed.
• Error::Cancelled (the user gave up) and Error::Denied (a capability is missing) are not counted as the plugin failing.

​

Arguments and selected files

• arg is an optional string. It is None when the command runs from Find Action or a shortcut, and set when another feature runs plugin.<plugin-id>.<command-id> with an argument, or when a notification button, code lens or gutter action passes one.
• ctx.selected_paths() lists the files and folders a Project view or editor tab menu ran the command on (the argument is then the first of them); it is empty otherwise.
• From problems.context and searchResults.context menus, selected_paths() holds the problem’s or match’s file and arg is JSON {"path": "…", "line": 0, "column": 0} (0-based line, UTF-16 column).

​

Limits

​

Keyboard shortcuts

[[contributes.keymaps]]
command = "count"
key = "Ctrl+Alt+C"
mac = "Meta+Alt+C"        # optional; macOS uses `key` as written when it is missing

• Modifiers: Meta, Ctrl, Alt, Shift. Keys: A–Z, 0–9, F1–F24, Enter, Escape, Tab, Space, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up, Down, Left, Right, Minus, Equal, Comma, Period, Slash, Semicolon, Quote.
• A chord is two strokes separated by a space: Meta+K Meta+C.
• Every stroke except a function key needs Ctrl, Alt or Meta: plain keys are for typing.
• Without mac, macOS gets key unchanged, so Ctrl stays Ctrl. Give mac with Meta when you want ⌘.
• A plugin shortcut is a default below the IDE’s: it is dropped when the keymap preset or the user already uses that keystroke, or when the action already has a binding. The user can rebind it in Settings › Keymap.

​

Menus

[[contributes.menus]]
menu = "editor.context"
command = "test-selection"
when = "editorLangId == markdown"   # optional

[[contributes.menus]]
menu = "editor.context"
command = "arthas.watch"
submenu = "Arthas"

[[contributes.menus]]
menu = "viewItem.context"
view = "pods"
command = "kube.logs"
when = "viewItemKind == pod"

​

Status bar items

[[contributes.statusBar]]
id = "branch"
text = "main"              # 1–128 bytes; code can replace it
tooltip = "Current branch" # up to 1 KiB
command = "refresh"        # one of the plugin's commands, run on click
align = "right"            # left or right (default right)
priority = 100             # 0–1000

• host::set_status_item(id, &StatusItem { text, tooltip, command }) shows or updates an item in every window (at most 8 per plugin; kept while the plugin is idle); remove_status_item(id) removes it.
• host::set_window_status_item(id, item) (API 1.4) overrides it in the invoking window only; remove_window_status_item(id) falls back to the global item. Only valid from a command or event of a window.

​

Context keys from code

host::set_context("ready", true)?;   // when = "plugin.acme.word-tools.ready"

​

Notifications with buttons

use openidea_plugin::{NotificationAction, NotificationLevel, host};

let retry = NotificationAction::new("Retry", "check").argument("again");
host::notify_with_actions(NotificationLevel::Warning, "Check failed", "The server did not answer.", &[retry])?;

​

Running other commands

​

Events

​

Commits

• A button above the message: a commit.message menu entry.
• Read the draft: host::pending_commit() (vcs.read) returns what Commit would commit now: per file its repository, path, status and a git diff of only the included changes (1 MiB in all, then truncated), plus the message, Amend and a revision. Unsaved editors of those files are saved first; nothing is staged.
• Write the message: host::set_commit_message(revision, text) (vcs.write) replaces it only while the draft is still at revision; otherwise it fails with Error::Stale and the user’s text is kept.

let draft = host::pending_commit()?.ok_or("no repository")?;
let message = ask_the_model(&draft.changes)?;
host::set_commit_message(draft.revision, &message)?;

use openidea_plugin::commit::{CommitChecks, CommitProblem};
use openidea_plugin::{CommitDraft, Error, Invocation};

impl CommitChecks for MyPlugin {
    fn check(&mut self, _check: &str, draft: &CommitDraft, _ctx: &Invocation) -> Result<Vec<CommitProblem>, Error> {
        if draft.message.lines().next().is_some_and(|l| l.len() > 72) {
            return Ok(vec![CommitProblem::new("The subject line is longer than 72 characters")]);
        }
        Ok(vec![])
    }
}

​

Related

• Manifest for the full plugin.toml reference.
• Views and decorations for tool windows whose buttons run code.
• API reference for every host function.