Events

On this page you'll learn about the available events and how to use them.

Basics

Events are simply callbacks which are invoked for specific actions and can, in certain circumstances, even alter the behavior of the application.

Register Callback

To register an event callback simply call the on method of your webview.
You'll need to pass the event-type as the template parameter and the callback as the function argument.

Every call to on() will return an id which can later be used to remove the same callback.

Example Callback (Resize Window)

smartview.on<saucer::window_event::resize>([](int width, int height)
{
   // ...
});

tip

If you only need an event to be called once, you can also use the once method.

Example Once Callback (Resize Window)

smartview.once<saucer::window_event::resize>([](int width, int height)
{
   // Fired once, then automatically removed.
});

Remove Callback

As previously mentioned you can unregister callbacks by saving their id.
To remove a callback, simply call remove with the event-type as the first and the id as the second argument.

Example: Callback Removal

auto id = smartview.on<saucer::window_event::resize>([](int width, int height)
{
   // ...
});

smartview.remove(saucer::window_event::resize, id);

tip

In case you simply want to remove all event callbacks of a specific event-type you can use the clear method.

Example: Clearing all Resize Callbacks

smartview.clear(saucer::window_event::resize);

Available Events

Window

Decorated

Called when the Window decorations change.

Signature

std::function<void(bool)>

Example

smartview.on<saucer::window_event::decorated>([](bool decorated)
{
    std::println("WebView is decorated: {}", decorated);
});

Maximize

Called when the Window is maximized or restored after being maximized.

Signature

std::function<void(bool)>

Example

smartview.on<saucer::window_event::maximize>([](bool state)
{
    std::println("WebView was maximized: {}", state);
});

Minimize

Called when the Window is minimized or restored after being minimized.

Signature

std::function<void(bool)>

Example

smartview.on<saucer::window_event::minimize>([](bool state)
{
    std::println("WebView was minimized: {}", state);
});

Closed

Called when the Window is closed.

Signature

std::function<void()>

Example

smartview.on<saucer::window_event::closed>([]()
{
    std::println("WebView closed");
});

Resize

Called when the Window is resized.

Signature

std::function<void(int width, int height)>

Example

smartview.on<saucer::window_event::resize>([](int width, int height)
{
    std::println("Width: {}, Height: {}", width, height);
});

Focus

Called when the Window gains or loses focus.

Signature

std::function<void(bool)>

Example

smartview.on<saucer::window_event::focus>([](bool focus)
{
    std::println("WebView is focused: {}!", focus);
});

Close

Called when the Window is about to be closed.

info

Returning saucer::policy::block from within the callback prevents the close.

Signature

std::function<saucer::policy()>

Example

smartview.on<saucer::window_event::close>([]()
{
    std::println("Preventing a close!");
    return saucer::policy::block;
});

WebView

DOM Ready

Called when the DOM Content loaded.

Signature

std::function<void()>

Example

smartview.on<saucer::web_event::dom_ready>([]()
{
    std::println("DOM is ready!");
});

Navigated

Called when a new URL was loaded.

Signature

std::function<void(const std::string &)>

Example

smartview.on<saucer::web_event::navigated>([](const std::string& url)
{
    std::println("Navigated: {}", url);
});

Navigate

Called when the URL is about to change.

info

Returning saucer::policy::block from within the callback prevents the navigation.

Signature

std::function<saucer::policy(const saucer::navigation &)>

Example

smartview.on<saucer::web_event::navigate>([](const saucer::navigation& nav)
{
    if (!nav.new_window())
    {
        return saucer::policy::allow;
    }

    auto new_window = /*...*/;
    new_window->set_url(nav.url());

    return saucer::policy::block;
});

Favicon Changed

Called when the favicon changes.

Signature

std::function<void(const saucer::icon &)>

Example

smartview.on<saucer::web_event::favicon>([](const saucer::icon& icon)
{
    std::println("Favicon changed!");
});

Title Changed

Called when the document title changes.

Signature

std::function<void(const std::string &)>

Example

smartview.on<saucer::web_event::title>([](const std::string& title)
{
    std::println("Document Title changed: {}", title);
});

Load

Called when the web-page load progresses.

Signature

std::function<void(const saucer::state &)>

Example

smartview.on<saucer::web_event::load>([](const saucer::state& state)
{
    std::println("Loading progressed");
});