Extending Albert using C++

This page focuses on the practical aspects of extending Albert using C++ and its peculiarities. To get an overview of the API refer to the general extension section.

A native plugin is a Qt Plugin, i.e. a shared library providing an instance of the class PluginInstance.

Writing native C++ plugins

Albert provides C and CMake macros that implement conventions to streamline the plugin development process and reduce the boilerplate code required to a few lines of code. Read the documentation in the header of the Albert CMake module before you proceed.

A minimal CMakeLists.txt:

project(my_plugin VERSION 1.0)
find_package(Albert REQUIRED)
albert_plugin()

A minimal metadata.json:

{
    "name": "My Plugin",
    "description": "Do useful stuff",
    "authors": ["@myname"],
    "license": "MIT"
}

A plugin class has to be default-constructible, inherit QObject and PluginInstance and contain the ALBERT_PLUGIN macro in its body. However, if subclassing an extension interface, you’d rather inherit util::ExtensionPlugin for convenience. A minimal trigger query handler plugin:

#pragma once
#include <albert/extensionplugin.h>
#include <albert/triggerqueryhandler.h>

class Plugin : public albert::ExtensionPlugin,
               public albert::TriggerQueryHandler
{
    ALBERT_PLUGIN
    void handleTriggerQuery(albert::Query &query) override
    {
        // Handle query
    }
};

Next, skim through the API reference. For reference see the official plugins.

Plugin directories

  • Linux:
    • ~/.local/{lib,lib64}/albert
    • /usr/local/{lib,lib64}/albert
    • /usr/lib/${MULTIARCH_TUPLE}/albert
    • /usr/{lib,lib64}/albert
  • macOS:
    • ~/Library/Application Support/Albert/plugins
    • $BUNDLE_PATH/Contents/PlugIns