Plugins

Plugins go in the plugins data directory, each plugin must have its own sub-directory and a plugin.json file that describes the plugin.

The plugin will be identified by the name of the directory it's in.

plugin.json

This file describes the plugin and its functionality.

It's a JSON file with the following keys:

Name	Required	Type	Description
name		string	Name shown in the list of plugins. If omitted it will be the plugin id.
description		string	Longer description of what the plugin does.
version		number	Plugin version number, used to resolve multiple installations of the same plugin
engine	Required	string	Script engine to use. (Currently must be python)
author		string	Name of the plugin author.
icon		string	See Icons
services	Required	array	Array of services.

Icons

icon fields can use a file name relative to the plugin directory:

{
    "icon": "my_icon.svg"
}

If the field value starts with "theme:" it will load an icon from the icon theme:

{
    "icon": "theme:image-gif"
}

Theme icons follow the Freedesktop icon naming specs.

There are also several icons not in the specs available in the default theme, you can use this icon searcher to find them.

Services

A service is defined ad a JSON object, which must have a type field and additional fields based on the service type.

Action

Action services show an entry on the "Plugins" menu, and are triggered when the user clicks on one of the actions.

The service JSON object has the following fields:

Name	Required	Type	Description
type	Required	string	action
script	Required	object	Script object to execute
label		string	Text shown in the menu
tooltip		string	Menu item tooltip
icon		string	See Icons

The script function will be invoked with these arguments:

• The application window
• The open document
• A dict with the settings values.

Format

Format services services add support for opening and saving to more file formats.

They will be visible in the open and save dialogs.

The service JSON object has the following fields:

Name	Required	Type	Description
type	Required	string	format
name		string	Text shown in the dialog
open		object	Script object to execute on open
save		object	Script object to execute on save
extensions	Required	array	Array of file extensions (without the dot)
slug		string	Format identifier, defaults to the first value in extensions
auto_open		bool	If set to false, the file will not be opened before the plugin invocation

At least one between open and save must be present.

open and save will be invoked with the following arguments:

• The application window
• The document to read from / write into
• A file-like object to perform io operations on
• The name of the file
• An ImportExport object to report back
• A dict with the settings values

Scripts

A plugin script is defined as a JSON object that provides information on how to run the plugin.

It has the following fields:

Name	Required	Type	Description
module	Required	string	Python module to load
function	Required	string	Function within module to execute
settings		object	Settings object

Settings

Settings provide parameters to pass the invoked function. The user will be shown a dialog with all these settings before the script execution.

If you need more advanced control over the dialog, see the dialog example.

They are defined as a JSON array os settings objects:

Name	Required	Type	Description
name	Required	string	Name, will be used as dict keys for values
type	Required	string	Setting type
label		string	Form label (defaults to the setting name)
description		string	Extra description
default		(any)	Default value for the setting
min		number	Minimum value (for int and float)
max		number	Maximum value (for int and float)
choices		array	Available choices (for choice)

Setting types

• info Just displays the description without any input.
• bool Shows a checkbox.
• int Shows a spin box.
• float Shows a spin box.
• string Shows a line edit.
• choice Shows a combo box.

Example

Example file structure:

plugins/
    MyPlugin/
        plugin.json
        hello_world.py

The above plugin will have an ID of MyPlugin.

plugin.json:

{
    "name": "Hello World Plugin",
    "description": "Shows a greeting",
    "author": "Glax",
    "engine": "python",
    "services": [
        {
            "type": "action",
            "label": "Hello world",
            "tooltip": "Does nothing useful",
            "script": {
                "module": "hello_world",
                "function": "main",
                "settings": [
                    {
                        "name": "greeting",
                        "label": "Type a greeting:",
                        "type": "string",
                        "default": "Hello World"
                    }
                ]
            }
        }
    ]
}

hello_world.py:

def main(window, document, settings):
    window.warning(
        settings["greeting"]
    )