Racket

racket-webview🔗ℹ

(require racket-webview/racket-webview)
	package: racket-webview

Higher-level interface built on top of racket-webview/racket-webview-qt.

This module provides a structured programming model around the lower-level webview bindings. It introduces contexts, a local HTTPS server, JSON-based event handling, and DOM and JavaScript utilities.

1 Architecture🔗ℹ

The module builds on the lower-level bindings from racket-webview/racket-webview-qt. It adds:

structured Racket values instead of raw strings
JSON decoding of events and JavaScript results
a local HTTPS server per context
convenience functions for DOM manipulation

A context encapsulates a native webview context together with a local HTTPS server. Windows are created within a context and communicate through events and JavaScript calls. When an HTML file is served, the context’s CSS boilerplate is injected immediately before the closing </head> tag.

2 Contexts🔗ℹ

procedure
(webview-new-context file-getter
[ #:boilerplate-js boilerplate-js
#:boilerplate-css boilerplate-css])
→ wv-context?
  file-getter : procedure?
  boilerplate-js : string? = (webview-default-boilerplate-js)
  boilerplate-css : string? = (webview-default-boilerplate-css)

Creates a new context.

The function:

starts a local HTTPS server on a dynamically chosen port
generates a self-signed certificate
creates a native context
installs the provided JavaScript boilerplate in the native context
stores the provided CSS boilerplate in the context

The file-getter procedure maps request paths to files. The #:boilerplate-js argument provides JavaScript support code passed to the native context constructor. The javascript is injected by the native QtWebEngine software. The #:boilerplate-css argument provides CSS boilerplate that is stored in the context and injected into served HTML documents.

Certificate files are removed automatically when the context is garbage collected.

procedure
(wv-context-base-url ctx) → string?
ctx : wv-context?

Returns the base URL of the context.

This URL can be used to construct URLs from relative path information.

procedure
(wv-context? v) → boolean?
v : any/c

Recognizes context values.

3 Windows🔗ℹ

procedure
(webview-create context
url-path
event-callback
[ #:parent parent]) → wv-win?
  context : wv-context?
  url-path : string?
  event-callback : procedure?
  parent : (or/c wv-win? #f) = #f

Creates a window in context, navigates it to url-path, and returns a window handle.

a native window is created
an event handler is installed
the context security token is applied
navigation is performed via the local server

The callback is invoked as:

(event-callback wv evt)

where evt is a parsed event hash table.

If parent is provided, the new window becomes a child of that window.

procedure
(wv-win-window-nr wv) → exact-integer?
wv : wv-win?

Returns the native window number.

procedure
(webview-close wv) → symbol?
wv : wv-win?

Closes the window. Always returns 'oke.

procedure
(webview-devtools wv) → symbol?
wv : wv-win?

Opens developer tools for the window.

procedure
(webview-move wv x y) → symbol?
  wv : wv-win?
  x : number?
  y : number?

Moves the window.

procedure
(webview-resize wv w h) → symbol?
  wv : wv-win?
  w : number?
  h : number?

Resizes the window.

procedure
(webview-show wv) → symbol?
wv : wv-win?

Shows the window.

procedure
(webview-hide wv) → symbol?
wv : wv-win?

Hides the window.

procedure
(webview-show-normal wv) → symbol?
wv : wv-win?

Shows the window in normal state.

procedure
(webview-maximize wv) → symbol?
wv : wv-win?

Maximizes the window.

procedure
(webview-minimize wv) → symbol?
wv : wv-win?

Minimizes the window.

procedure
(webview-window-state wv) → symbol?
wv : wv-win?

Returns the current window state.

4 Navigation and Content🔗ℹ

procedure
(webview-set-url! wv url) → symbol?
wv : wv-win?
url : (or/c string? url?)

Loads url.

procedure
(webview-navigate! wv place) → symbol?
wv : wv-win?
place : string?

Navigates by assigning window.location via JavaScript.

procedure
(webview-base-url wv) → url?
wv : wv-win?

Returns the context base URL as a URL value.

procedure
(webview-set-html! wv html) → symbol?
wv : wv-win?
html : (or/c string? xexpr?)

Replaces the current document contents.

X-expressions are converted to strings before being passed to JavaScript.

procedure
(webview-set-menu! wv menu) → symbol?
wv : wv-win?
menu : is-wv-menu?

Installs menu in wv.

The menu is converted to JSON using wv-menu->json and then passed to the browser by evaluating JavaScript through webview-run-js.

The result is the symbol returned by webview-run-js.

procedure
(webview-set-title! wv title) → symbol?
wv : wv-win?
title : string?

Sets the window title.

5 JavaScript🔗ℹ

procedure
(webview-run-js wv js) → symbol?
wv : wv-win?
js : string?

Evaluates JavaScript.

procedure
(webview-call-js-result? x) → boolean?
x : any/c

Recognizes lower-level JavaScript call results.

procedure
(webview-call-js wv js) → (or/c string? list? boolean? hash?)
wv : wv-win?
js : string?

Evaluates JavaScript and returns a decoded value.

If the lower-level call fails or the result does not match the expected structure, an exception is raised.

6 Dialogs🔗ℹ

Dialog functions return immediately. Results are delivered asynchronously via events.

procedure
(webview-messagebox wv
type
title
message
[ #:sub submessage]) → symbol?
  wv : wv-win?
  type : symbol?
  title : string?
  message : string?
  submessage : string? = ""

Shows a message box.

The user response is delivered asynchronously via events. If dismissed or canceled, this is indicated through the event.

procedure
(webview-choose-dir wv title base-dir) → symbol?
  wv : wv-win?
  title : string?
  base-dir : (or/c path? string?)

Shows a directory chooser.

The selected directory is delivered asynchronously via events. If canceled, this is indicated through the event.

procedure
(webview-file-open wv
title
base-dir
permitted-exts) → symbol?
  wv : wv-win?
  title : string?
  base-dir : (or/c path? string?)
  permitted-exts : (or/c wv-permitted-exts? wv-list-of-permitted-exts?)

Shows an open-file dialog.

The selected file is delivered asynchronously via events. If canceled, this is indicated through the event.

procedure
(webview-file-save wv
title
base-dir
permitted-exts) → symbol?
  wv : wv-win?
  title : string?
  base-dir : (or/c path? string?)
  permitted-exts : (or/c wv-permitted-exts? wv-list-of-permitted-exts?)

Shows a save-file dialog.

The file to be saved is delivered asynchronously via events. If canceled, this is indicated through the event.

7 DOM Interaction🔗ℹ

7.1 Selectors and Element Identifiers🔗ℹ

Many functions accept either an element identifier or a CSS selector.

If a symbol is provided, it is interpreted as an element id. The symbol is converted to a string and prefixed with "#".

If a string is provided, it is used directly as a CSS selector.

a symbol refers to a single element by id
a string may refer to one or more elements
CSS selector semantics are those of the browser engine

Functions apply their effect to all matched elements.

7.2 Event Binding🔗ℹ

procedure
(webview-bind! wv selector event) → list?
  wv : wv-win?
  selector : (or/c symbol? string?)
  event : (or/c symbol? list-of-symbol?)

Installs one or more DOM event bindings.

If selector is a symbol, it is interpreted as an element id and converted to a CSS selector by prefixing "#".

The result is a list describing the installed bindings.

procedure
(webview-unbind! wv selector event) → list?
  wv : wv-win?
  selector : (or/c symbol? string?)
  event : (or/c symbol? list-of-symbol?)

Removes one or more DOM event bindings.

Selector handling is the same as for webview-bind!. The result is a list describing the removed bindings.

7.3 DOM Values🔗ℹ

procedure
(webview-set-value! wv id val) → symbol?
  wv : wv-win?
  id : symbol?
   val :
(or/c symbol? string? number? boolean?
      g:date? g:time? g:datetime? rgba?)

Sets the value of the element identified by id using JavaScript.

For checkboxes and radio buttons, the checked state is updated. Other elements receive a string value. Dates, times, datetimes, and colors are converted to strings before being passed to JavaScript.

procedure
(webview-value wv id) → (or/c string? boolean?)
wv : wv-win?
id : symbol?

Returns the value of the element identified by id.

For checkboxes and radio buttons, the result reflects the checked state. Other elements return their value property.

procedure
(webview-value/boolean wv id) → (or/c boolean? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a boolean.

procedure
(webview-value/symbol wv id) → (or/c symbol? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a symbol.

procedure
(webview-value/number wv id) → (or/c number? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a number.

procedure
(webview-value/date wv id) → (or/c g:date? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a date.

procedure
(webview-value/time wv id) → (or/c g:time? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a time.

procedure
(webview-value/datetime wv id) → (or/c g:datetime? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a datetime.

procedure
(webview-value/color wv id) → (or/c rgba? #f)
wv : wv-win?
id : symbol?

Returns the value converted to a color.

7.4 Classes, Styles🔗ℹ

procedure
(webview-add-class! wv selector class) → hash?
  wv : wv-win?
  selector : (or/c symbol? string?)
  class : (or/c symbol? string? list?)

Adds one or more CSS classes using JavaScript.

If selector is a symbol, it is treated as an element id. If it is a string, it is used directly as a CSS selector.

The effect is applied to all matched elements.

procedure
(webview-remove-class! wv selector class) → hash?
  wv : wv-win?
  selector : (or/c symbol? string?)
  class : (or/c symbol? string? list?)

Removes one or more CSS classes using JavaScript.

Selector handling is the same as for webview-add-class!.

procedure
(webview-set-style! wv
selector
style-entries) → hash?
  wv : wv-win?
  selector : (or/c symbol? string?)
  style-entries : (or/c kv? list-of-kv?)

Sets inline style properties using JavaScript.

The effect is applied to all elements matched by selector.

procedure
(webview-unset-style! wv
selector
style-entries) → hash?
  wv : wv-win?
  selector : (or/c symbol? string?)
  style-entries : (or/c symbol? list-of-symbol?)

Clears inline style properties using JavaScript.

The effect is applied to all elements matched by selector.

procedure
(webview-get-style wv selector styles) → (or/c list? hash?)
  wv : wv-win?
  selector : (or/c symbol? string?)
  styles : (or/c symbol? list-of-symbol?)

Retrieves computed style values.

If selector is a symbol, the result for that single element is returned directly. Otherwise the result covers all matched elements.

7.5 Attributes🔗ℹ

procedure
(webview-set-attr! wv selector attr-entries) → hash?
  wv : wv-win?
  selector : (or/c symbol? string?)
  attr-entries : (or/c kv? list-of-kv?)

Sets attributes using JavaScript.

Dates, times, datetimes, and colors are converted to strings before being passed to JavaScript. The effect is applied to all elements matched by selector.

procedure
(webview-attr wv id attr) → (or/c string? boolean?)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value of the element identified by id.

If the JavaScript result is null, the function returns #f.

procedure
(webview-attr/boolean wv id attr) → (or/c boolean? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a boolean.

procedure
(webview-attr/symbol wv id attr) → (or/c symbol? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a symbol.

procedure
(webview-attr/number wv id attr) → (or/c number? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a number.

procedure
(webview-attr/date wv id attr) → (or/c g:date? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a date.

procedure
(webview-attr/time wv id attr) → (or/c g:time? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a time.

procedure
(webview-attr/datetime wv id attr) → (or/c g:datetime? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a datetime.

procedure
(webview-attr/color wv id attr) → (or/c rgba? #f)
  wv : wv-win?
  id : symbol?
  attr : (or/c symbol? string?)

Returns the attribute value converted to a color.

7.6 Inner HTML🔗ℹ

procedure
(webview-set-innerHTML! wv id html) → symbol?
  wv : wv-win?
  id : symbol?
  html : (or/c string? xexpr?)

Sets the innerHTML of the element identified by id using JavaScript.

Returns 'oke if the injected JavaScript yields a true value, and 'failed otherwise.

8 File Filters🔗ℹ

struct
(struct wv-permitted-exts (name exts))
name : string?
exts : (listof symbol?)

Represents a file dialog filter entry.

procedure
(make-wv-permitted-exts name exts) → wv-permitted-exts?
name : string?
exts : (listof symbol?)

Creates a filter entry.

procedure
(wv-list-of-permitted-exts? v) → boolean?
v : any/c

Recognizes lists of filter entries.

9 Utilities🔗ℹ

procedure
(webview-default-boilerplate-js custom-js
...) → string?
custom-js : procedure?

Returns the default JavaScript boilerplate.

The result is constructed by concatenating the contents of js/*.js. If an additional procedure is supplied, its returned string is appended to that JavaScript.

procedure
(webview-default-boilerplate-css custom-css
...) → string?
custom-css : procedure?

Returns the default CSS boilerplate.

The result is constructed by concatenating the contents of js/*.css. If an additional procedure is supplied, its returned string is appended to that CSS.

procedure
(webview-standard-file-getter base-path
#:not-exist f) → procedure?
base-path : path-string?
f : procedure?

Creates a standard file getter.

10 Diagnostics🔗ℹ

procedure
(webview-version) → list?

Returns version information.

procedure
(webview-info) → list?

Returns runtime information.

procedure
(webview-set-loglevel l) → void?
l : (or/c 'error 'warning 'info 'debug)

Sets the native log level.

The native log file path can be obtained via webview-info.

1	Architecture
2	Contexts
3	Windows
4	Navigation and Content
5	Java Script
6	Dialogs
7	DOM Interaction
8	File Filters
9	Utilities
10	Diagnostics