Racket FFI Interface for rktwebview_qt🔗ℹ

1 Overview🔗ℹ

The module racket-webview-qt.rkt provides a Racket FFI wrapper around the native rktwebview_qt library. It loads the shared library, initializes the native runtime, and exposes Racket functions for creating and controlling webview windows.

If the Qt backend is available locally, it is loaded directly. Otherwise the module attempts to resolve and download the backend. If that is not possible, the module continues in a degraded mode in which a limited subset of the FFI entry points will only display a warning and perform a no-op. All others will fail.

The wrapper translates the low-level C interface into a Racket-oriented API based on structures, callbacks, and ordinary Racket values.

The module provides:

• creation of HTTP(S) contexts

• creation and management of webview windows

• navigation and HTML loading

• JavaScript execution

• window geometry and visibility control

• native dialogs

• asynchronous event delivery

• version and cleanup utilities

2 Requirements🔗ℹ

The native backend requires Qt version 6.10.2 or newer.

The shared library rktwebview_qt must therefore be built against Qt 6.10.2 or a compatible later release.

Earlier Qt versions are not supported.

3 Backend Availability🔗ℹ

The module first checks whether the expected racket-webview-qt backend is already installed.

If it is not installed, the module attempts to resolve the configured download site. If the site can be resolved and the configured archive is downloadable, the backend is downloaded automatically.

If the download site cannot be resolved, if no archive is available for the current operating system and machine architecture, or if the download fails, the module does not immediately abort module loading. Instead it switches to a degraded mode in which native FFI loading is disabled.

In that degraded mode, a textual reason is stored internally and selected FFI entry points are replaced by fallback implementations.

When the backend cannot be loaded, the module defines fallback implementations for missing FFI entry points through define-ffi-definer and #:default-make-fail.

These fallbacks behave in two different ways.

For a small set of initialization and shutdown functions, a non-failing fallback is installed:

• rkt_webview_env returns #t

• rkt_webview_events_waiting returns 0

• rkt_webview_init returns #t

• rkt_webview_cleanup returns #t

All other missing FFI functions raise an exception when called.

Fallback warnings are emitted at most once per function. If native loading was disabled because the backend was unavailable, the warning message includes the recorded reason. If native loading was enabled but a specific symbol could not be loaded from the library, the error names the library file.

4 Module Initialization🔗ℹ

Loading the module performs several initialization steps automatically.

• determines the operating system and architecture

• sets Qt runtime environment variables

• loads the rktwebview_qt shared library

• initializes the native runtime

• starts a background thread that processes native events

Currently the wrapper supports the following platforms:

• ’linux

• ’windows

If the current system is unsupported, loading the module raises an error.

5 Data Model🔗ℹ

6 HTTP(S) Contexts🔗ℹ

A context represents the shared HTTP(S) environment used by webviews.

Contexts correspond to native WebEngine profiles and determine properties such as:

• cookies and cache

• injected JavaScript

• trusted certificates

Arguments:

• boilerplate-js: JavaScript source injected into pages

• server-cert: optional certificate data

The returned context identifier can be passed to rkt-webview-create to create webviews within that context.

7 Creating Webviews🔗ℹ

Arguments:

• context: context identifier returned by rkt-webview-new-context

• parent: optional parent webview

• evt-callback: procedure invoked for each event

• close-callback: procedure invoked when the window is closed

The result is a new rkt-wv structure.

Events generated by the native layer are delivered asynchronously through evt-callback.

8 Window Lifecycle🔗ℹ

The wrapper forwards the request to the native backend and schedules cleanup of the event-processing loop.

Returns #t.

The wrapper first checks its internal validity flag and then queries the native runtime.

This function is also registered with the Racket plumber so that cleanup occurs automatically when the process exits.

9 Window Configuration🔗ℹ

Returns a result symbol such as:

• 'oke

• 'failed

This token may be used by the native layer when accepting certain self-signed certificates.

10 Navigation🔗ℹ

Returns a result symbol such as:

• 'oke

• 'set_navigate_failed

Returns a result symbol such as:

• 'oke

• 'set_html_failed

11 JavaScript Execution🔗ℹ

Returns a result symbol such as:

• 'oke

• 'eval_js_failed

(list result value)

where:

• result is the native result code

• value is a JSON string containing the returned data

The JSON structure is generated by the native backend.

12 Window Geometry🔗ℹ

Possible results:

• 'normal

• 'minimized

• 'maximized

• 'hidden

• 'normal_active

• 'maximized_active

13 Developer Tools🔗ℹ

14 Native Dialogs🔗ℹ

Dialog functions return immediately with a status code. The user’s choice is delivered asynchronously through the event callback.

15 Event Delivery🔗ℹ

Each webview has an associated event callback.

The callback has the form:

(λ (wv event-json) ...)

Arguments:

• wv: the webview handle

• event-json: JSON event string from the native backend

Typical event types include:

• "show"

• "hide"

• "move"

• "resize"

• "closed"

• "page-loaded"

• "navigation-request"

• "js-evt"

The wrapper does not parse the JSON payload.

16 Version Information🔗ℹ

Example result:

(list

(list 'webview-c-api 1 0 0)

(list 'qt 6 10 2))

17 Example🔗ℹ

(define ctx

(rkt-webview-new-context "" #""))

(define wv

(rkt-webview-create

ctx

#f

(λ (wv evt)

(displayln evt))

(λ ()

(displayln "closed"))))

(rkt-webview-set-title! wv "Example")

(rkt-webview-set-url! wv "https://example.org")

18 Summary🔗ℹ

The FFI module provides a thin Racket interface to the native rktwebview_qt backend.

Key characteristics:

• thin wrapper around the native C API

• asynchronous event delivery

• JSON-based event payloads

• simple Racket structures for webviews