Skip to main content

Modules

Modules can be used to extend the functionality of a saucer::application, saucer::window, or saucer::webview by accessing their native implementation details.
They are a really powerful tool that can be used to implement completely new features or to alter the current behavior of saucer.

Official Modules​

The following offical modules exist:

  • saucer/desktop

    Provides a File-Picker as well as functionality to open a given URI with the default system handler.

  • saucer/pdf

    Allows to print the current page to a PDF

Native Header​

tip

If you are using CMake, make sure you have module support enabled!
This can be achieved by setting saucer_modules to ON (enabled by default).

First, include the header that provides the stable native interface for your respective platform.

#include <saucer/modules/stable/webkitgtk.hpp>
// or
#include <saucer/modules/stable/qt.hpp>

Setup Module​

Now we will setup a basic webview-module. The modules constructor will receive a pointer to the class it aims to extend (e.g. saucer:webview or saucer::application) as the first parameter.

Example: Basic Module
class awesome_module
{
    saucer::webview *m_parent;

  public:
    awesome_module(saucer::webview *parent) : m_parent(parent)
    {
    }

    void mute(bool enabled)
    {
        m_parent->native().webview->page()->setAudioMuted(enabled);
    }
};

static_assert(saucer::Module<awesome_module, saucer::webview>);
note

When extending a saucer::webview it is possible to intercept IPC messages by defining a bool on_message(const std::string&) member function in your module. A return value of true means that the message has been handled.

tip

You can use the compile time macros SAUCER_QT5, SAUCER_QT6, SAUCER_WEBKITGTK, SAUCER_WEBVIEW2 and SAUCER_WEBKIT to find out which backend is currently used.

Use Module​

To use the module, call add_module on the saucer::webview or saucer::application you want to extend.

int main()
{
    auto app = saucer::application::init({
        .id = "modules",
    });

    saucer::smartview webview{{
        .application = app,
    }};

    auto& module = webview.add_module<awesome_module>();

    webview.set_url("https://github.com/saucer/saucer");
    webview.set_dev_tools(true);

    module.mute(true);
    // or...
    webview.module<awesome_module>()->mute(true);

    webview.show();
    app->run();

    return 0;
}