Settings and uses

Settings of the plugin's own, and telling the program a project needs the plugin.

Plugin settings

A plugin's own settings are a list of fields. A gear appears beside the plugin's switch in the list of plugins. It opens them in a window with Reset, Cancel and Save, and they are kept from one run to the next.

// ...in the plugin (its id is 'my-plugin'):
settings: [
  { key: 'look', label: 'A heavy tree is looked at', usual: 'By itself', choices: ['By itself', 'Whole', 'Half', 'Quarter'] },
  { key: 'play', label: 'Play when the view opens', usual: true, toggle: true },
  { key: 'frames', label: 'Frames in a new loop', usual: 12, low: 2, high: 120, step: 1 },
],
commands: [{
  label: 'Say my settings',
  run(api) {
    const { look, play, frames } = api.prefs('my-plugin');
    api.say(`${look}, ${play ? 'plays' : 'waits'}, ${frames} frames`);
  },
}],

from rassam import Plugin, choice, slider, toggle

plugin = Plugin('my-plugin', 'My plugin')
plugin.settings(
    choice('look', 'A heavy tree is looked at', ['By itself', 'Whole', 'Half', 'Quarter'], 'By itself'),
    toggle('play', 'Play when the view opens', True),
    slider('frames', 'Frames in a new loop', 2, 120, 12),
)


@plugin.command('Say my settings')
def say_settings(app):
    mine = app.prefs('my-plugin')
    app.say(f"{mine.look}, {'plays' if mine.play else 'waits'}, {int(mine.frames)} frames")

Use plugin settings for what the user sets once. What is asked each time belongs where it is used: an export's fields, a tool's, a window.

Uses

uses says whether a project has something of this plugin's in it. When such a project is opened while the plugin is off, the program offers to turn it on.

uses: (doc) => doc.layers.some((layer) => String(layer.made?.by ?? '').startsWith('my-plugin:')),

@plugin.uses
def uses(doc):
    return any(str((layer.get('made') or {}).get('by', '')).startswith('my-plugin:') for layer in doc['layers'])