Saucer

https://saucer.app/
Admin
Saucer is a modern C++ webview library that enables cross-platform desktop applications with...
Tokens:10,270
Snippets:152
Trust Score:5.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Saucer Desktop Module with FetchContent

Source: https://saucer.app/misc/modules

Installs the saucer-desktop module using FetchContent. Ensure to link the library after making it available.

```cmake
FetchContent_Declare(
  saucer-desktop
  GIT_REPOSITORY https://github.com/saucer/desktop
  GIT_TAG        <version>
)


FetchContent_MakeAvailable(saucer-desktop)
target_link_libraries(${PROJECT_NAME} [PRIVATE|PUBLIC] saucer::desktop)
```

--------------------------------

### Use Stable Natives (Qt Example)

Source: https://saucer.app/misc/native

Include the stable native header for your platform and use the `native` object to interact with platform features. This example demonstrates setting the zoom factor for a Qt webview.

```cpp
#include <saucer/modules/stable/qt.hpp>


coco::stray start(saucer::application *)
{
    // ...
    auto native = webview->native();
    native.webview->setZoomFactor(5);
    // ...
}
```

--------------------------------

### Use Unstable Natives (Qt Example)

Source: https://saucer.app/misc/native

Include the private header for unstable natives and access the implementation directly using `native<false>()`. This example shows muting audio on a platform web page, but is not recommended for general use.

```cpp
#include <saucer/qt.webview.impl.hpp>


coco::stray start(saucer::application *)
{
    // ...
    auto *const native = webview->native<false>();
    native->platform->web_page->setAudioMuted(true);
    // ...
}
```

--------------------------------

### Install Saucer with FetchContent

Source: https://saucer.app/getting-started

Use FetchContent to declare and make the Saucer dependency available in your CMake project.

```cmake
1
FetchContent_Declare(
2
  saucer
3
  GIT_REPOSITORY https://github.com/saucer/saucer
4
  GIT_TAG        v8.0.5
5
)
6

7
FetchContent_MakeAvailable(saucer)
```

--------------------------------

### Install Saucer with CPM.cmake

Source: https://saucer.app/getting-started

Use CPMAddPackage to include Saucer in your project via CMake.

```cmake
1
CPMAddPackage(
2
  NAME           saucer
3
  VERSION        8.0.5
4
  GIT_REPOSITORY "https://github.com/saucer/saucer"
5
)
```

--------------------------------

### Handle Load State Change Event

Source: https://saucer.app/webview/events

Subscribe to events emitted when the loading state of a web page changes. The state parameter indicates whether loading has started or finished.

```cpp
webview->on<saucer::webview::event::load>([](const saucer::state&) {
    // ...
});
```

--------------------------------

### main.cpp source code

Source: https://saucer.app/getting-started/hello-world

Implements the main application logic, creating a window and webview, exposing functions to the webview, and setting the URL.

```cpp
1
#include <print>
2
#include <saucer/smartview.hpp>
3

4
coco::stray start(saucer::application *app)
5
{
6
    auto window  = saucer::window::create(app).value();
7
    auto webview = saucer::smartview::create({.window = window});
8

9

10
    window->set_title("Hello World!");
11

12

13
    webview->expose("call_me", [&](double a, double b)
14
    {
15
        std::println("Called with: a = {}, b = {}", a, b);
16
        return a + b;
17
    });
18

19

20
    webview->expose("call_me_too", [&]() -> coco::task<double>
21
    {
22

23
        auto random = *co_await webview->evaluate<double>("Math.random()");
24
        std::println("Random: {}", random);
25
        co_return random;
26
    });
27

28
    webview->set_url("https://saucer.app");
29

30
    window->show();
31

32

33
    co_await app->finish();
34
}
35

36
int main()
37
{
38
    return saucer::application::create({.id = "hello-world"})->run(start);
39
}
```

--------------------------------

### CMakeLists.txt configuration

Source: https://saucer.app/getting-started/hello-world

Configures the project using FetchContent to include the saucer library and sets up the executable with C++23 standards.

```cmake
1
cmake_minimum_required(VERSION 3.21)
2
project(hello-world LANGUAGES CXX VERSION 1.0.0)
3

4
# --------------------------------------------------------------------------------------------------------
5
# Create executable
6
# --------------------------------------------------------------------------------------------------------
7

8
add_executable(${PROJECT_NAME})
9
target_sources(${PROJECT_NAME} PRIVATE "src/main.cpp")
10

11
target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_23)
12
set_target_properties(${PROJECT_NAME} PROPERTIES CXX_STANDARD 23 CXX_EXTENSIONS OFF CXX_STANDARD_REQUIRED ON)
13

14
# --------------------------------------------------------------------------------------------------------
15
# Link libraries
16
# --------------------------------------------------------------------------------------------------------
17

18
include(FetchContent)
19

20
FetchContent_Declare(
21
    saucer
22
    GIT_REPOSITORY "https://github.com/saucer/saucer"
23
    GIT_TAG v8.0.5
24
)
25

26
FetchContent_MakeAvailable(saucer)
27

28
target_link_libraries(${PROJECT_NAME} PRIVATE saucer::saucer)
```

--------------------------------

### Registering a custom scheme

Source: https://saucer.app/webview/schemes

Register the scheme before any webview is created.

```cpp
1
int main()
2
{
3
    saucer::webview::register_scheme("name");
4
    return saucer::application::create({.id = "hello-world"})->run(start);
5
}
```

--------------------------------

### Handle Permission Requests

Source: https://saucer.app/webview/events

Subscribe to permission requests from web pages. The callback receives a request object that can be used to accept or deny the permission. If ignored, the request is denied by default.

```cpp
webview->on<saucer::webview::event::permission>([](const std::shared_ptr<saucer::permission::request>&) -> saucer::status {
    // ...
});
```

--------------------------------

### Set Saucer Backend

Source: https://saucer.app/getting-started/cmake

Configures the backend to be used by Saucer. The default is platform-appropriate.

```cmake
set(saucer_backend "Qt")
```

--------------------------------

### Registering a Window Decoration Change Event

Source: https://saucer.app/window/events

Register a listener for changes in window decorations. The callback receives a decoration object.

```cpp
window->on<saucer::window::event::decorated>([](saucer::window::decoration) {
    // ...
});
```

--------------------------------

### Handle Web Resource Request Event

Source: https://saucer.app/webview/events

Subscribe to events emitted when a web resource is requested by the web page.

```cpp
webview->on<saucer::webview::event::request>([](const saucer::uri&) {
    // ...
});
```

--------------------------------

### Registering a Window Maximize Event

Source: https://saucer.app/window/events

Register a listener for window maximize events. The callback receives a boolean indicating whether the window is maximized.

```cpp
window->on<saucer::window::event::maximize>([](bool) {
    // ...
});
```

--------------------------------

### Handle DOM Ready Event

Source: https://saucer.app/webview/events

Subscribe to the event emitted when the Document Object Model (DOM) of a web page is ready.

```cpp
webview->on<saucer::webview::event::dom_ready>([]() {
    // ...
});
```

--------------------------------

### Registering an Event

Source: https://saucer.app/window/events

Register a listener for a specific window event. The `on` function takes an event type and a callback function. It returns an ID that can be used to unregister the event.

```APIDOC
## on<event>(listener)

### Description
Registers a listener function to be called when a specific event occurs.

### Method
`on<event>(listener)`

### Parameters
- **event**: The type of the window event to listen for (e.g., `saucer::window::event::resize`).
- **listener**: A callback function that will be executed when the event is triggered. The parameters of the listener depend on the specific event.

### Returns
- **id**: A unique identifier for the registered event listener, used for unregistering.
```

--------------------------------

### Set WebView2 Version

Source: https://saucer.app/getting-started/cmake

Specifies the version of the WebView2 NuGet-Package to be used.

```cmake
set(saucer_webview2_version "1.0.2783-prerelease")
```

--------------------------------

### Registering a Window Minimize Event

Source: https://saucer.app/window/events

Register a listener for window minimize events. The callback receives a boolean indicating whether the window is minimized.

```cpp
window->on<saucer::window::event::minimize>([](bool) {
    // ...
});
```

--------------------------------

### Set Window Decorations

Source: https://saucer.app/window/decorations

Use this function to change the window's decoration type. Prefer 'partial' decorations when possible.

```cpp
window->set_decorations(saucer::window::decoration::partial);
```

--------------------------------

### Set Browser Flags for WKWebView

Source: https://saucer.app/misc/portability

Configure WKWebView with browser flags derived from WKWebViewConfiguration properties. Flags are passed as key-value pairs.

```cpp
auto webview = saucer::webview::create({
    .window        = /*...*/,
    .browser_flags = {"upgradeKnownHostsToHTTPS=true", "defaultWebpagePreferences.allowsContentJavaScript=false",
                        "preferences.minimumFontSize=10", "applicationNameForUserAgent=\"Saucer App\""},
});
```

--------------------------------

### Handling a custom scheme request

Source: https://saucer.app/webview/schemes

Register a handler on a webview instance to process requests and return a saucer::scheme::response.

```cpp
1
webview->handle_scheme("name", [](const saucer::scheme::request& req)
2
{
3
    return saucer::scheme::response{
4
        .data   = saucer::stash::from_str(std::format("Hello: {}", req.url().string())),
5
        .mime   = "text/plain",
6
        .status = 200,
7
    };
8
});
```

--------------------------------

### Registering a Window Resize Event

Source: https://saucer.app/window/events

Register a listener for window resize events. The listener receives the new width and height. Returns an ID that can be used to unregister the event.

```cpp
const auto id = window->on<saucer::window::event::resize>([](int width, int height) {
    // ...
});
```

--------------------------------

### Registering a Window Close Policy Event

Source: https://saucer.app/window/events

Register a listener for the window close event, allowing control over the close operation. Subscribers can block or allow the close by returning a policy decision.

```cpp
window->on<saucer::window::event::close>([] -> saucer::policy {
    // ...
});
```

--------------------------------

### Registering a Window Focus Event

Source: https://saucer.app/window/events

Register a listener for window focus events. The callback receives a boolean indicating whether the window gained focus.

```cpp
window->on<saucer::window::event::focus>([](bool) {
    // ...
});
```

--------------------------------

### Handle Favicon Loaded Event

Source: https://saucer.app/webview/events

Subscribe to events emitted when a website's favicon has been loaded. The loaded icon data is passed as a parameter, allowing inspection or saving.

```cpp
webview->on<saucer::webview::event::favicon>([](const saucer::icon&) {
    // ...
});
```

--------------------------------

### Using Embedded Files in Saucer Application

Source: https://saucer.app/webview/embedding

After linking against the `saucer::embedded` target, you can embed all available files into a webview and serve a specific HTML file. Calling `webview->embed` multiple times merges files.

```cpp
#include <saucer/smartview.hpp>
#include <saucer/embedded/all.hpp>


coco::stray start(saucer::application *)
{
    // ...
    webview->set_url("...");
    webview->embed(saucer::embedded::all());
    webview->serve("/index.html");
    // ...
}
```

--------------------------------

### Handle Navigation Finished Event

Source: https://saucer.app/webview/events

Subscribe to the event emitted after a web page navigation has successfully completed.

```cpp
webview->on<saucer::webview::event::navigated>([](const saucer::uri&) {
    // ...
});
```

--------------------------------

### Awaiting an Event

Source: https://saucer.app/window/events

Asynchronously wait for a specific window event to occur. This is useful for scenarios like modals where you need to pause execution until an event is triggered with a specific outcome.

```APIDOC
## await<event>(policy_decision)

### Description
Asynchronously waits for a specific window event to occur.

### Method
`co_await window->await<event>(policy_decision)`

### Parameters
- **event**: The type of the window event to await.
- **policy_decision**: The policy decision to be passed to the event (e.g., `saucer::policy::allow`).

### Returns
- **event_result**: The result or parameters typically returned by the event callback, but in this context, they are returned from the awaitable. The parameters usually passed to the event callback are passed as arguments to the await function.
```

--------------------------------

### webview->handle_scheme

Source: https://saucer.app/webview/schemes

Registers a handler for a specific custom scheme on a webview instance to process incoming requests.

```APIDOC
## webview->handle_scheme(name, handler)

### Description
Registers a callback function to handle requests made to a previously registered custom scheme. The handler receives a `saucer::scheme::request` object and must return a `saucer::scheme::response` object.

### Parameters
- **name** (string) - Required - The name of the registered scheme.
- **handler** (function) - Required - A callback function that takes `const saucer::scheme::request&` and returns `saucer::scheme::response`.

### Request Object
The request object provides access to:
- **url** (object) - The requested URL.
- **method** (string) - The HTTP method of the request.
- **content** (any) - The request body content.
- **headers** (map) - The request headers.

### Response Object
The response object must contain:
- **data** (any) - The response body data.
- **mime** (string) - The MIME type of the response.
- **status** (int) - The HTTP status code.
- **headers** (map, optional) - Response headers.
```

--------------------------------

### Handle Fullscreen Changes

Source: https://saucer.app/webview/events

Subscribe to fullscreen requests from web pages. The callback can return saucer::policy::block to prevent fullscreen or saucer::policy::allow to permit it.

```cpp
webview->on<saucer::webview::event::fullscreen>([](bool fullscreened) -> saucer::policy {
    // ...
});
```

--------------------------------

### Handle Division by Zero from JavaScript

Source: https://saucer.app/webview/interop

Demonstrates how a JavaScript call to an exposed C++ function that returns `std::expected` handles an error condition (division by zero).

```javascript
> await saucer.exposed.divide(10, 0)
~~[Error]~~ Divisor must not be zero
```

--------------------------------

### Registering a Window Closed Event

Source: https://saucer.app/window/events

Register a listener for when a window is closed. This event has no parameters.

```cpp
window->on<saucer::window::event::closed>([] {
    // ...
});
```

--------------------------------

### Setting URL with authority

Source: https://saucer.app/webview/schemes

Specify an authority for all scheme URLs to avoid unexpected results due to WebView2 JS-Fetch API issues.

```cpp
1
smartview.set_url("demo://index.html");
2
smartview.set_url("demo://root/index.html"); // "root" could be anything
```

--------------------------------

### Registering an Event Once

Source: https://saucer.app/window/events

Register a listener that will be called only one time for a specific window event. Similar to `on`, but the listener is automatically removed after the first invocation.

```APIDOC
## once<event>(callback)

### Description
Registers a callback function to be executed only once when a specific event occurs.

### Method
`once<event>(callback)`

### Parameters
- **event**: The type of the window event to listen for.
- **callback**: The function to execute once when the event is triggered.

### Returns
- **id**: A unique identifier for the registered event listener.
```

--------------------------------

### saucer::webview::register_scheme

Source: https://saucer.app/webview/schemes

Registers a custom URL scheme. This must be called before any webview instance is created.

```APIDOC
## saucer::webview::register_scheme(name)

### Description
Registers a custom scheme name for use within the application. This function must be invoked prior to the creation of any webview instances.

### Parameters
- **name** (string) - Required - The name of the custom scheme to register.
```

--------------------------------

### Awaiting a Window Close Event

Source: https://saucer.app/window/events

Asynchronously await a window close event, allowing the program to pause until the event occurs and a policy is applied. The parameters and return values are inverted compared to standard event callbacks.

```cpp
co_await window->await<saucer::window::event::close>(saucer::policy::allow);
// Window was closed. Do something useful...
```

--------------------------------

### Manual Embedding File Generation via CMake Script

Source: https://saucer.app/webview/embedding

An alternative to `saucer_embed` is to manually invoke the `saucer-embed` CMake script from the command line, specifying the directory containing the web content.

```bash
cmake -P <path-to-saucer-embed>/cmake/embed.cmake <directory>
```

--------------------------------

### Decorated Event

Source: https://saucer.app/window/events

This event is emitted when a window's decorations change.

```APIDOC
## Event: decorated

### Description
Emitted when a window's decorations change.

### Usage
```cpp
window->on<saucer::window::event::decorated>([](saucer::window::decoration) {
    // ...
});
```

### Parameters
- **decoration**: Information about the window's decorations.
```

--------------------------------

### Resize Event

Source: https://saucer.app/window/events

This event is emitted when a window is resized.

```APIDOC
## Event: resize

### Description
Emitted when a window is resized.

### Usage
```cpp
window->on<saucer::window::event::resize>([](int, int) {
    // ...
});
```

### Parameters
- **width**: The new width of the window.
- **height**: The new height of the window.
```

--------------------------------

### Handle Title Change Event

Source: https://saucer.app/webview/events

Subscribe to events emitted when the title of a web page changes. The new title is provided as a string_view.

```cpp
webview->on<saucer::webview::event::title>([](std::string_view) {
    // ...
});
```

--------------------------------

### Handle JavaScript Exceptions in C++

Source: https://saucer.app/webview/interop

Demonstrates how JavaScript exceptions thrown during `evaluate` calls are caught and returned as `std::expected` in C++.

```cpp
> auto res = co_await webview->evaluate<std::vector<int>>("new Array(-1)");
> std::println("Error: {}", res.error());
```

--------------------------------

### Set Browser Flags for WebKitGtk

Source: https://saucer.app/misc/portability

Pass browser flags to WebKitGtk webviews using key-value pairs. Ensure flags are formatted correctly as 'property=value'.

```cpp
auto webview = saucer::webview::create({
    .window        = /*...*/,
    .browser_flags = {"enable-javascript=false"},
});
```

--------------------------------

### Call Exposed C++ Function from JavaScript

Source: https://saucer.app/webview/interop

Demonstrates how to call an exposed C++ function from JavaScript using the `saucer.exposed` object.

```javascript
const result = await saucer.exposed.multiply(5, 10);
```

--------------------------------

### Using saucer::executor with Custom Error Types

Source: https://saucer.app/webview/interop

Shows how to use `saucer::executor` with a specific error type, in this case, `double`, for rejecting Promises. This allows for more structured error handling.

```cpp
webview->expose("error", [](const saucer::executor<void, double>& exec) {
    exec.reject(42);
});
```

--------------------------------

### Access Native Member

Source: https://saucer.app/misc/native

Retrieve the native API object from a webview instance. This is the entry point for interacting with platform-specific features.

```cpp
auto native = webview->native();
```

--------------------------------

### Link Private Target

Source: https://saucer.app/misc/native

Link against the `saucer::private` target to gain access to all required headers and libraries for the Native-API.

```cmake
target_link_libraries(${PROJECT_NAME} [PRIVATE|PUBLIC] saucer::private)
```

--------------------------------

### Handle Navigation Request Event

Source: https://saucer.app/webview/events

Subscribe to events emitted when a navigation is initiated or requested. The callback can return saucer::policy::block to prevent navigation or saucer::policy::allow to permit it.

```cpp
webview->on<saucer::webview::event::navigate>([](const saucer::navigation&) -> saucer::policy {
    // ...
});
```

--------------------------------

### Import Saucer TypeScript functions

Source: https://saucer.app/getting-started

Import functions from the @saucer-dev/types package instead of accessing them via the global saucer object.

```typescript
import { call } from "@saucer-dev/types";
```

--------------------------------

### Execute JavaScript and Capture Result

Source: https://saucer.app/webview/interop

Execute JavaScript code from C++ and capture the returned value. Supports basic expressions and function calls.

```cpp
auto random = *co_await webview->evaluate<double>("Math.random()");
auto pow = *co_await webview->evaluate<double>("Math.pow({}, {})", 2, 5);
```

--------------------------------

### Set Saucer Serializer

Source: https://saucer.app/getting-started/cmake

Defines the serializer for Saucer. Defaults to a glaze-based serializer.

```cmake
set(saucer_serializer "Rflpp")
```

--------------------------------

### Maximize Event

Source: https://saucer.app/window/events

This event is emitted when a window is maximized or unmaximized.

```APIDOC
## Event: maximize

### Description
Emitted when a window is (un-)maximized.

### Usage
```cpp
window->on<saucer::window::event::maximize>([](bool) {
    // ...
});
```

### Parameters
- **is_maximized**: A boolean value, `true` if the window was maximized, `false` otherwise.
```

--------------------------------

### Expose C++ Function to JavaScript

Source: https://saucer.app/webview/interop

Expose a C++ function to be callable from JavaScript. The function is registered with a given name and parameters.

```cpp
webview->expose("multiply", [](double a, double b) {
    return a * b;
});
```

--------------------------------

### Automated Web Content Embedding with CMake

Source: https://saucer.app/webview/embedding

Use the `saucer_embed` CMake function to automatically embed web content from a specified directory into your project. This function adds a pre-build hook to refresh embedded files.

```cmake
include(FetchContent)

FetchContent_Declare(
    saucer
    GIT_REPOSITORY "https://github.com/saucer/saucer"
    GIT_TAG $VERSION$
)

FetchContent_MakeAvailable(saucer)

saucer_embed("out" TARGET ${PROJECT_NAME})
target_link_libraries(${PROJECT_NAME} PRIVATE saucer::saucer saucer::embedded)
```

--------------------------------

### Minimize Event

Source: https://saucer.app/window/events

This event is emitted when a window is minimized or unminimized.

```APIDOC
## Event: minimize

### Description
Emitted when a window is (un-)minimized.

### Usage
```cpp
window->on<saucer::window::event::minimize>([](bool) {
    // ...
});
```

### Parameters
- **is_minimized**: A boolean value, `true` if the window was minimized, `false` otherwise.
```

--------------------------------

### Focus Event

Source: https://saucer.app/window/events

This event is emitted when a window gains or loses focus.

```APIDOC
## Event: focus

### Description
Emitted when a window is (un-)focused.

### Usage
```cpp
window->on<saucer::window::event::focus>([](bool) {
    // ...
});
```

### Parameters
- **is_focused**: A boolean value, `true` if the window gained focus, `false` otherwise.
```

--------------------------------

### Registering a Non-Clearable Window Resize Event

Source: https://saucer.app/window/events

Register a window resize event listener that is marked as non-clearable. These events can only be unregistered by their specific ID.

```cpp
window->on<saucer::window::event::resize>({{.func = [](int width, int height) { /*...*/ }, .clearable = false}});
```

--------------------------------

### Inject JavaScript Code

Source: https://saucer.app/webview/scripts

Injects a JavaScript code snippet into a web page. The script runs at creation time. A unique ID is returned for later management.

```cpp
const auto id = webview->inject({
    .code   = "console.log('Hello from script!')",
    .run_at = saucer::script::time::creation,
});
```

--------------------------------

### Link Saucer library in CMake

Source: https://saucer.app/getting-started

Link the Saucer library to your project target using target_link_libraries.

```cmake
1
target_link_libraries(${PROJECT_NAME} [PRIVATE|PUBLIC] saucer::saucer)
```

--------------------------------

### Manual Promise Resolution with saucer::executor

Source: https://saucer.app/webview/interop

Expose a function that manually handles a JavaScript Promise using `saucer::executor`. This is useful for performing operations and then resolving or rejecting the Promise based on conditions.

```cpp
webview->expose("divide", [](double a, double b, const saucer::executor<double>& exec) {
    const auto& [resolve, reject] = exec;

    if (b == 0) {
        return reject("Divisor must not be zero");
    }

    return resolve(a / b);
});
```

--------------------------------

### Expose C++ Function Returning std::expected

Source: https://saucer.app/webview/interop

Expose a C++ function that returns `std::expected<double, std::string>` to signal success or failure with an error message to JavaScript.

```cpp
webview->expose("divide", [](double a, double b) -> std::expected<double, std::string> {
    if (b == 0) {
        return std::unexpected{"Divisor must not be zero"};
    }
    return a / b;
});
```

--------------------------------

### Controlling Promise Lifetime with saucer::executor

Source: https://saucer.app/webview/interop

Demonstrates how to control the lifetime of a JavaScript Promise by resolving it asynchronously on a separate thread. This allows for operations that take time to complete before the Promise is settled.

```cpp
webview->expose("wait", [](saucer::executor<double> exec) {
    std::thread t{[exec = std::move(exec)] {
        std::this_thread::sleep_for(std::chrono::seconds(5));
        exec.resolve(42);
    }};
    t.detach();
});
```

--------------------------------

### Close Event

Source: https://saucer.app/window/events

This event is emitted just before a window is closed, allowing subscribers to block or allow the close operation.

```APIDOC
## Event: close

### Description
Emitted when a window is about to be closed. Subscribers can influence the close operation.

### Usage
```cpp
window->on<saucer::window::event::close>([] -> saucer::policy {
    // ...
    return saucer::policy::allow; // or saucer::policy::block
});
```

### Returns
- **policy**: A `saucer::policy` value, either `saucer::policy::block` to prevent closing or `saucer::policy::allow` to permit closing.
```

--------------------------------

### Handle RPC Message Event

Source: https://saucer.app/webview/events

Subscribe to events emitted when an RPC message is sent. Return saucer::status::handled if the message was processed, or saucer::status::unhandled to allow other subscribers to process it.

```cpp
webview->on<saucer::webview::event::message>([](std::string_view) -> saucer::status {
    // ...
});
```

--------------------------------

### Expose C++ Function Throwing Exception

Source: https://saucer.app/webview/interop

Expose a C++ function that throws a `std::runtime_error` when a specific condition is met, allowing JavaScript to handle the error.

```cpp
webview->expose("divide", [](double a, double b) {
    if (b == 0) {
        throw std::runtime_error{"Divisor must not be zero"};
    }
    return a / b;
});
```

--------------------------------

### Registering a Non-Clearable Event

Source: https://saucer.app/window/events

Register an event listener that will not be automatically cleared by wildcard disconnects. These events must be explicitly disconnected using their ID.

```APIDOC
## on<event>({{.func = listener, .clearable = false}})

### Description
Registers a listener for a specific event that is marked as not clearable by wildcard operations.

### Method
`on<event>({{.func = listener, .clearable = false}})`

### Parameters
- **event**: The type of the window event.
- **listener**: The callback function to execute.
- **clearable**: A boolean flag, set to `false`, indicating this event should not be cleared by `off(event)`.

### Returns
- **id**: A unique identifier for the registered event listener.
```

--------------------------------

### Enable MSVC Mutex Hack

Source: https://saucer.app/getting-started/cmake

Enables a workaround for issues caused by constexpr mutex constructors in MSVC version 17.10, particularly affecting Java Bindings.

```cmake
set(saucer_msvc_hack ON)
```

--------------------------------

### Execute JavaScript Without Capturing Result

Source: https://saucer.app/webview/interop

Use `execute` to run JavaScript code when the return value is not needed. This is more efficient than `evaluate` in such cases.

```cpp
webview->execute("console.log({})", saucer::make_args(1, "Test", std::vector<int>{4, 2}));
```

--------------------------------

### Clear All Clearable Injected Scripts

Source: https://saucer.app/webview/scripts

Removes all injected scripts that are marked as 'clearable'. This is a convenient way to reset all user-injectable scripts.

```cpp
webview->uninject();
```

--------------------------------

### Closed Event

Source: https://saucer.app/window/events

This event is emitted when a window is closed.

```APIDOC
## Event: closed

### Description
Emitted when a window is closed.

### Usage
```cpp
window->on<saucer::window::event::closed>([] {
    // ...
});
```
```

--------------------------------

### Expose C++ Coroutine Returning std::expected

Source: https://saucer.app/webview/interop

Expose a C++ coroutine function that returns `std::expected` to handle asynchronous operations and potential errors gracefully.

```cpp
webview->expose("divide", [](double a, double b) -> coco::task<std::expected<double, std::string>> {
    if (b == 0) {
        co_return std::unexpected{"Divisor must not be zero"};
    }
    co_return a / b;
});
```

--------------------------------

### Disable MacOS Private API

Source: https://saucer.app/getting-started/cmake

Controls the usage of private MacOS APIs. Disabled by default, disabling has several consequences for security and API availability.

```cmake
set(saucer_private_webkit OFF)
```

--------------------------------

### Define Exposed Function with TypeScript

Source: https://saucer.app/webview/interop

Define the signature of an exposed C++ function when using the TypeScript package for type safety.

```typescript
import { exposed } from "@saucer-dev/types";
const multiply = exposed<number, [number, number]>("multiply");
```

--------------------------------

### Pass Unquoted String to JavaScript Execute

Source: https://saucer.app/webview/interop

Use `saucer::unquoted` to pass strings to JavaScript execution without them being automatically quoted, useful for passing code snippets or identifiers.

```cpp
webview->execute("{}({})", saucer::unquoted{"console.log"}, "42");
```

--------------------------------

### Unregistering a Specific Window Event

Source: https://saucer.app/window/events

Unregister a specific event listener using its ID. This is used to stop listening to a particular event.

```cpp
window->off(saucer::window::event::resize, id);
```

--------------------------------

### Remove Injected Script

Source: https://saucer.app/webview/scripts

Removes a previously injected script using its unique ID. This allows for targeted removal of scripts.

```cpp
webview->uninject(id);
```

--------------------------------

### Unregistering All Events of a Specific Type

Source: https://saucer.app/window/events

Unregister all event listeners of a specific event type by omitting the event ID. This is useful for cleaning up all listeners for a particular event.

```cpp
window->off(saucer::window::event::resize);
```

--------------------------------

### Disable Saucer Exceptions

Source: https://saucer.app/getting-started/cmake

Explicitly disables Saucer's exception catching mechanism for exposed functions. This is relevant when compiled without `-fno-exceptions`.

```cmake
set(saucer_exceptions OFF)
```

--------------------------------

### Unregistering an Event

Source: https://saucer.app/window/events

Remove an event listener using its unique ID or by event type. You can remove a specific listener by providing both the event type and its ID, or remove all listeners for a given event type.

```APIDOC
## off(event, id)

### Description
Removes a specific event listener.

### Method
`off(event, id)`

### Parameters
- **event**: The type of the window event.
- **id**: The unique identifier of the listener to remove.

## off(event)

### Description
Removes all event listeners for a specific event type.

### Method
`off(event)`

### Parameters
- **event**: The type of the window event for which to remove all listeners.
```
Tokens:
Raw