notesy::tools

Buttons of the plugin's own in the formatting bar over the editor, set and kept until it changes or removes them: nothing runs while they just sit there. Takes the ui permission.

A button names a command by its id and notesy runs it the way a shortcut does, so a button costs nothing beyond the command it already has.

rustuse notesy::{commands, editor, notices, tools, Icon};

pub fn ready() {
    let shout = commands::add("shout", "Shout the selection", |command| {
        match editor::selection() {
            Some(selection) => editor::replace(selection.start, selection.end, selection.text.to_uppercase()),
            None => notices::warn("Nothing selected"),
        }
    });
    // Among notesy's own marks, between bold and italic.
    let button = tools::add("shout");
    button.set(#{ icon: Icon::Bold, hint: "Shout it", command: shout.id(), group: "marks", order: 205 });
    // And one at the right end, where nothing notesy adds can push it along.
    let panel = tools::add("panel");
    panel.set(#{ icon: Icon::Plugin, hint: "Open the panel", command: "plugin.example.mine.open", zone: "right" });
    button.remove();
}
Function What it does
tools::add(key) A button of its own, shown once it's set; returns it.
button.set(object) Shows it, or changes it.
button.remove() Takes it out of the bar; set puts it back.

key names it: lowercase letters, digits, -, _ and ., starting with a letter.

A button object takes any of:

Field What it is
icon Its icon, by name; the plugin's own mark unless set.
text Shown in place of the icon: H1, Aa. Short — a button is a mark, not a sentence.
hint Shown under the pointer; the plugin's name unless set.
command The command it runs: a command's id(), or one of notesy's own (bold, heading_2, align_center, insert_image, table.delete). Without one it does nothing. The Keybindings page lists every one.
zone left (the default), center or right.
group Which cluster it draws with. Its own unless set, so it never lands inside one of notesy's by accident.
order Lower comes first within the zone.
on Drawn lit, as notesy's own are when the caret is already in what they do.
enabled false greys it out and it can't be pressed.
color Its icon's color: a theme color's key, or one of the plugin's own.

#Where a button goes

Three things decide it, and they don't overlap: the zone is which of the bar's three parts it sits in, the order is where it sits within that part, and the group only decides where the wider gap falls. Order alone decides position, so the two can never disagree.

notesy's own buttons leave a hundred between them, so there is room to land between any two of them rather than only at the ends:

Order notesy's
100 undo, redo
200 bold, italic, strikethrough, highlight, code, link, picture
300 the heading picker
400 bulleted, numbered, task
500 quote, code block, divider, table
600 align left, center, right

So order: 205 with group: "marks" puts a button between bold and italic, in the same cluster. Leaving group out makes it a cluster of its own with a gap either side, which is usually what a plugin wants.

The left zone is where notesy's own buttons are, and it is the one that gives way when the window is narrow: what doesn't fit is gathered into a picker at the end, taken from the far side first. A button in the centre or on the right is never gathered up, so that is where to put one that must stay in sight.

#What the bar's own buttons do

Every one of them names a command, so a plugin can run the same things from its own button, its own command, or a shortcut:

What Commands
Marks bold, italic, strikethrough, highlight, inline_code, link
Headings heading_1 … heading_6, run again to take the heading off
Lists bullet_list, numbered_list, toggle_task
Blocks quote, code_block, divider, insert_image
Alignment align_left, align_center, align_right — Pandoc's ::: center fences around the lines, run again to take them off
Tables table.row_above, table.delete_row, table.delete, table.align_left …

A button lights up (on) when the caret is already in what it does, and notesy's own do this by asking the note rather than remembering: pressing a lit button always takes that formatting off again. A plugin's button says its own on, so it can follow the same rule.

When the plugin stops, its buttons go with it.

Every page