Creating Plugins

This tutorial will walk you through all the steps to required to write a basic plugin. It assumes that you've already installed Uranium with a working application layer (such as Cura).

If you want to create a Cura plugin you can find more information here.

The basics

Uranium has an extensive plugin system that enables third party developers to add new features to applications created with it. Some of the basic functionality (such as loading stl files, logging, etc) of Uranium is already a plugin.

A plugin is a single folder inside the plugin directory of the application, which must contain a __init__.py file, which in turn must contain both a getMetaData() and a register(app) function. The getMetaData must return a JSON dict. The register function is called by the application when it tries to enable the plugin. It is assumed to return a dict with types (strings) paired to objects.

A plugin can have multiple types and thus multiple objects.

Meta data

The meta data is formed by a json, which holds multiple json objects. It must always have a 'plugin' object, which needs to have the following fields: "name", "author", "version", "description" and "supported_sdk_versions" (or the deprecated "api"). Example:

"plugin": 
{
    "name": "Hello world",
    "author": "John Doe",
    "version": "0.1",
    "description": "This is my first plugin!",
    "supported_sdk_versions": ["6.0.0"]
}

Apart from that, every type returned by register can also have its own object in the metadata. For instance, if the plugin is a view, the metadata can have a "view" object, which can have fields such as "name", "view_panel" and "visible".

"view": 
{
    "name": "Hello world view",
    "view_panel": "HelloWorld.qml",
    "visible": False
}

Registering

If we continue with our hello world example, which at least needs to have a view. The register function is quite simple, as it only needs to return a single entry.

def register(app):
    return { "view": HelloWorldView() }

Translation

Uranium has a built-in translation system. It is possible for plugins to register the strings that they use, so they can be translated.

from UM.i18n import i18nCatalog
i18n_catalog = i18nCatalog("plugins")
print(i18n_catalog.i18n("Hello world!"))
print(i18n_catalog.i18nc("Hello world text", "Hello World!"))

This can and should also be used in the metadata of plugins. Types do not need to be registered in such a way, as this information is not directly exposed to the user.