►Racket FFI Interface for rktwebview_  qt
Racket FFI Interface for rktwebview_  qt
1 Overview
2 Requirements
3 Module Initialization
4 Data Model
4.1 The rkt-wv Structure
5 HTTP(S) Contexts
6 Creating Webviews
7 Window Lifecycle
8 Window Configuration
9 Navigation
10 Java  Script Execution
11 Window Geometry
12 Developer Tools
13 Native Dialogs
14 Event Delivery
15 Version Information
16 Example
17 Summary
9.1
Racket
  top  contents  ← prev  up  next → 

Racket FFI Interface for rktwebview_qt🔗ℹ

Hans Dijkema <hans@dijkewijk.nl>

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.

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 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.

4 Data Model🔗ℹ

4.1 The rkt-wv Structure🔗ℹ

Each webview window is represented by a transparent Racket structure.

struct

(struct rkt-wv (win evt-queue callback valid close-callback))

  win : exact-integer?
  evt-queue : any/c
  callback : procedure?
  valid : boolean?
  close-callback : procedure?
Represents a webview instance managed by the Racket wrapper.

Fields:

  • win: the native integer window handle

  • evt-queue: internal queue of pending event strings

  • callback: user event callback

  • valid: mutable flag indicating whether the wrapper considers the window active

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

Although the structure is transparent, user code should normally treat it as an opaque handle.

procedure

(rkt-wv-win wv) → exact-integer?

  wv : rkt-wv?
Returns the native window handle associated with wv.

5 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

procedure

(rkt-webview-new-context boilerplate-js    
  server-cert) → exact-integer?
  boilerplate-js : string?
  server-cert : bytes?
Creates a new HTTP(S) context and returns its native identifier.

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.

6 Creating Webviews🔗ℹ

procedure

(rkt-webview-create context    
  parent    
  evt-callback    
  close-callback) → rkt-wv?
  context : exact-integer?
  parent : (or/c #f rkt-wv?)
  evt-callback : (-> rkt-wv? string? any)
  close-callback : (-> any)
Creates a new webview window in the given HTTP(S) context.

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.

7 Window Lifecycle🔗ℹ

procedure

(rkt-webview-close wv) → boolean?

  wv : rkt-wv?
Requests that the webview window be closed.

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

Returns #t.

procedure

(rkt-webview-valid? wv) → boolean?

  wv : rkt-wv?
Returns whether the webview still exists.

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

procedure

(rkt-webview-exit) → void?

Closes all webviews and stops the background event-processing thread.

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

8 Window Configuration🔗ℹ

procedure

(rkt-webview-set-title! wv title) → symbol?

  wv : rkt-wv?
  title : string?
Sets the native window title.

Returns a result symbol such as:

  • 'oke

  • 'failed

procedure

(rkt-webview-set-ou-token wv token) → boolean?

  wv : rkt-wv?
  token : string?
Associates an Organizational Unit token with the window.

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

9 Navigation🔗ℹ

procedure

(rkt-webview-set-url! wv url) → symbol?

  wv : rkt-wv?
  url : string?
Navigates the webview to the given URL.

Returns a result symbol such as:

  • 'oke

  • 'set_navigate_failed

procedure

(rkt-webview-set-html! wv html) → symbol?

  wv : rkt-wv?
  html : string?
Loads HTML directly into the webview.

Returns a result symbol such as:

  • 'oke

  • 'set_html_failed

10 JavaScript Execution🔗ℹ

procedure

(rkt-webview-run-js wv js) → symbol?

  wv : rkt-wv?
  js : string?
Executes JavaScript without returning a value.

Returns a result symbol such as:

  • 'oke

  • 'eval_js_failed

procedure

(rkt-webview-call-js wv js) → (list/c symbol? string?)

  wv : rkt-wv?
  js : string?
Executes JavaScript and returns:

(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.

11 Window Geometry🔗ℹ

procedure

(rkt-webview-move wv x y) → symbol?

  wv : rkt-wv?
  x : exact-integer?
  y : exact-integer?
Moves the webview window to the given screen coordinates.

procedure

(rkt-webview-resize wv width height) → symbol?

  wv : rkt-wv?
  width : exact-integer?
  height : exact-integer?
Resizes the window.

procedure

(rkt-webview-show wv) → symbol?

  wv : rkt-wv?
Shows the window.

procedure

(rkt-webview-hide wv) → symbol?

  wv : rkt-wv?
Hides the window.

procedure

(rkt-webview-show-normal wv) → symbol?

  wv : rkt-wv?
Restores the window to its normal state.

procedure

(rkt-webview-maximize wv) → symbol?

  wv : rkt-wv?
Maximizes the window.

procedure

(rkt-webview-minimize wv) → symbol?

  wv : rkt-wv?
Minimizes the window.

procedure

(rkt-webview-present wv) → symbol?

  wv : rkt-wv?
Requests that the window be presented to the user.

procedure

(rkt-webview-window-state wv) → symbol?

  wv : rkt-wv?
Returns the current window state.

Possible results include:

  • 'normal

  • 'minimized

  • 'maximized

  • 'hidden

12 Developer Tools🔗ℹ

procedure

(rkt-webview-open-devtools wv) → symbol?

  wv : rkt-wv?
Opens the browser developer tools window.

13 Native Dialogs🔗ℹ

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

procedure

(rkt-webview-choose-dir wv title base-dir) → symbol?

  wv : rkt-wv?
  title : string?
  base-dir : string?
Requests a directory-selection dialog.

procedure

(rkt-webview-file-open wv    
  title    
  base-dir    
  extensions) → symbol?
  wv : rkt-wv?
  title : string?
  base-dir : string?
  extensions : string?
Requests a file-open dialog.

procedure

(rkt-webview-file-save wv    
  title    
  base-dir    
  extensions) → symbol?
  wv : rkt-wv?
  title : string?
  base-dir : string?
  extensions : string?
Requests a file-save dialog.

procedure

(rkt-webview-messagebox wv    
  title    
  message    
  submessage    
  type) → symbol?
  wv : rkt-wv?
  title : string?
  message : string?
  submessage : string?
  type : symbol?
Shows a native message box.

14 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.

15 Version Information🔗ℹ

procedure

(rkt-webview-version) → (list/c list? list?)

Returns version information for the native backend.

Example result:

(list
 (list 'webview-c-api 1 0 0)
 (list 'qt 6 10 2))

16 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")

17 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

  top  contents  ← prev  up  next →