Web Wire: Low-Level WebUI Command Layer🔗ℹ

1 Startup and shutdown🔗ℹ

Internally this:

• creates queues and semaphores for events and logs;

• starts an IPC connection via webui-ipc;

• spawns a background thread that handles incoming events and log lines;

• stores the handle in an internal variable.

If log-level is supplied, it is passed to ww-log-level to configure the remote log level.

Calling ww-start when the backend is already running is a no-op: the existing handle is returned.

The backend type is currently always 'ipc; FFI integration is not implemented yet.

This function:

• notifies registered window event handlers that windows are being destroyed;

• sends an "exit"-style command to webui-wire;

• stops the event-handling thread;

• clears the current backend handle.

After ww-stop, calling window/DOM functions will fail until ww-start is used again.

2 Debugging and log inspection🔗ℹ

These functions control and inspect the logging used by this module and its event thread.

When ww-set-debug has been enabled, these macros:

• format msg-expr (and optionally id-expr);

• enqueue a debug log line in the in-memory log buffer.

They are primarily intended for development and diagnostics.

These always log, regardless of the debug flag, and are used for internal error conditions. Log lines are stored in the same log buffer used by ww-display-log and ww-tail-log.

The value is clamped between 10 and 10,000. When the buffer exceeds this limit, the oldest entries are dropped.

The optional filter controls which lines are shown:

• #f — show all entries;

• string? — case-insensitive substring match;

• regexp? — regular expression match;

• (listof string?) — OR-combination of substring filters.

The optional args are interpreted as:

• a number: how many last lines to show initially;

• a filter (string, regexp, or list of strings) as in ww-display-log;

• a boolean #f to stop an existing tail session.

This is mainly intended for interactive debugging.

3 Backend settings and protocol info🔗ℹ

This function is defined via:

(def-cmd ww-log-level

loglevel () ((level symbol?)) -> symbol)

so level is optional:

• with an argument, the remote log level is set to level and the effective level is returned;

• without arguments, the current remote log level is queried and returned.

Definition (simplified):

(def-cmd ww-protocol

protocol () () -> int)

The result is an integer that should match the protocol version that the Racket side expects.

This function is defined as:

(def-cmd ww-cwd

cwd () [(path path-or-string?)] -> path)

Semantics:

• With a path, the helper’s working directory is set and the new directory (as a path) is returned.

• Without arguments, the current directory (as seen by the helper) is returned.

This directory is used to resolve relative file names (HTML files, icons, etc.).

4 Global stylesheet🔗ℹ

(def-cmd ww-set-stylesheet

set-stylesheet ((st stylesheet-or-string?)) () -> void)

The argument st may be either:

• a stylesheet value understood by the WebUI side;

• a raw CSS string.

(def-cmd ww-get-stylesheet

get-stylesheet () () -> stylesheet)

5 Window handles and window management🔗ℹ

The internal id field corresponds to the numeric window id used by the webui-wire backend.

(def-cmd ww-new

new ((profile symbol?)) [(use-browser boolean?) (parent ww-win?)]

-> ww-win)

Arguments:

• profile symbolic profile name used by the helper to select configuration (e.g. 'default).

• use-browser when true, prefers an external browser instead of an embedded webview where supported.

• parent optional parent window (for dialog-like windows).

Returns a ww-win handle.

(def-cmd ww-close

close ((win-id ww-win?)) [] -> void)

(def-cmd ww-move

move ((win-id ww-win?) (x number?) (y number?)) [] -> void)

(def-cmd ww-resize

resize ((win-id ww-win?) (width? number?) (height number?)) [] -> void)

(def-cmd ww-set-title

set-title ((win-id ww-win?) (title string?)) [] -> void)

(def-cmd ww-set-icon

set-icon ((win-id ww-win?)

(svg-file (is-icon-file? 'svg))

(png-file (is-icon-file? 'png))) [] -> void)

The predicates (is-icon-file? 'svg) and (is-icon-file? 'png) ensure that the paths refer to existing files with the correct file extension.

(def-cmd ww-set-menu

set-menu ((win-id ww-win?)

(menu is-menu?)) [] -> void)

The menu value is a menu structure as defined in "menu.rkt".

(def-cmd ww-set-show-state

set-show-state ((win-id ww-win?)

(state symbol?)) () -> void)

Typical states are things like 'normal, 'maximized, etc., depending on what the backend supports.

(def-cmd ww-get-show-state

show-state ((win-id ww-win?)) () -> symbol)

6 HTML / URL content🔗ℹ

(def-cmd ww-set-html-file

set-html ((win-id ww-win?)

(html-file html-file-exists?)) ()

-> number)

The html-file argument must exist (resolved against ww-cwd); otherwise an error is raised. The return value is a numeric status code from the helper.

(def-cmd ww-set-url

set-url ((win-id ww-win?)

(url string?)) () -> void)

(def-cmd ww-set-inner-html

set-inner-html ((win-id ww-win?)

(element-id symbol-or-string?)

(html-of-file html-or-file?)) () -> void)

The html-of-file value is either a string containing HTML or a path to a file whose contents are used as HTML.

(def-cmd ww-get-inner-html

get-inner-html ((win-id ww-win?)

(element-id symbol-or-string?)) () -> json)

7 Attributes, CSS, classes🔗ℹ

(def-cmd ww-set-attr

set-attr ((win-id ww-win?)

(element-id symbol-or-string?)

(attr symbol-or-string?)

(val any?)) () -> void)

(def-cmd ww-get-attr

get-attr ((win-id ww-win?)

(element-id symbol-or-string?)

(attr symbol-or-string?)) () -> json)

(def-cmd ww-get-attrs

get-attrs ((win-id ww-win?)

(element-id symbol-or-string?)) () -> json

-> mk-attrs)

(def-cmd ww-del-attr

del-attr ((win-id ww-win?)

(element-id symbol-or-string?)

(attr symbol-or-string?)) () -> void)

(def-cmd ww-add-style

add-style ((win-id ww-win?)

(element-id symbol-or-string?)

(css-style css-style?)) () -> void)

(def-cmd ww-set-style

set-style ((win-id ww-win?)

(element-id symbol-or-string?)

(css-style css-style?)) () -> void)

(def-cmd ww-get-style

get-style ((win-id ww-win?)

(element-id symbol-or-string?)) ()

-> css-style)

(def-cmd ww-add-class

add-class ((win-id ww-win?)

(element-id symbol-or-string?)

(class symbol-or-string?))

() -> void)

(def-cmd ww-remove-class

remove-class ((win-id ww-win?)

(element-id symbol-or-string?)

(class symbol-or-string?))

() -> void)

(def-cmd ww-has-class?

has-class ((win-id ww-win?)

(element-id symbol-or-string?)

(class symbol-or-string?)) ()

-> bool)

8 Values and element queries🔗ℹ

(def-cmd ww-get-value

value ((win-id ww-win?)

(element-id symbol-or-string?)) () -> string)

(def-cmd ww-set-value

value ((win-id ww-win?)

(element-id symbol-or-string?)

(value any?)) () -> void)

(def-cmd ww-get-elements

get-elements ((win-id ww-win?)

(selector selector?)) () -> json

-> (λ (r) ...))

The raw JSON result is converted by a small helper into a more usable Racket structure (see the implementation).

(def-cmd ww-element-info

element-info ((win-id ww-win?)

(element-id symbol-or-string?)) ()

-> json

-> (λ (r) ...))

9 Events🔗ℹ

(def-cmd ww-bind

bind ((win-id ww-win?)

(event symbol-or-string?)

(selector selector?)) () -> json

-> (λ (r) ...))

The JSON result includes information about the bound elements.

(def-cmd ww-on

on ((win-id ww-win?)

(event symbol-or-string?)

(id symbol-or-string?)) () -> void)

10 File and directory dialogs🔗ℹ

(def-cmd ww-file-open

file-open ((win-id ww-win?)

(caption string?)

(dir string?)

(file-filters string?)) ()

-> string)

Returns the selected path as a string, or an empty string on cancel.

(def-cmd ww-file-save

file-save ((win-id ww-win?)

(caption string?)

(dir string?)

(file-filters string?)

(overwrite boolean?)) ()

-> string)

Returns the chosen file path as a string, or an empty string if the user cancels.

(def-cmd ww-choose-dir

choose-dir ((win-id ww-win?)

(caption string?)

(dir string?)) ()

-> string)

Returns the selected directory path as a string, or an empty string on cancel.

11 Low-level command access🔗ℹ

This is the lowest-level escape hatch; all def-cmd-generated functions use this under the hood.

• returns #t if r is a cmdr with a false ok field, or the symbol 'cmd-nok;

• returns #f otherwise.

• removes surrounding quotes;

• replaces escaped quotes (\"\\\"\") by plain quotes.

12 Window tables🔗ℹ

This is mainly useful for diagnostics and advanced introspection; most application code keeps explicit ww-win handles instead.

13 Helper predicates used in contracts🔗ℹ

The following predicates are used as argument checkers in the def-cmd-generated functions above.

(define (stylesheet-or-string? st)

(or (stylesheet? st) (string? st)))

(define (is-icon-file? ext)

(lambda (v)

(and (string? v)

(string-suffix? v (string-append "." (symbol->string ext)))

(file-exists? v))))

Used in ww-set-icon with 'svg and 'png.

(define (html-file-exists? f)

(if (file-exists? f)

#t

(let* ((cwd (ww-cwd))

(full-file (build-path cwd f)))

(ww-debug (format "file-exists? '~a'" full-file))

(file-exists? full-file))))

(define (html-or-file? v)

(if (file-exists? v)

#t

(string? v)))

(define (symbol-or-string? s)

(or (symbol? s) (string? s)))

(define (path-or-string? s)

(or (path? s) (string? s)))

• symbol? — a single symbolic selector;

• string? — a string selector;

• a non-empty list of symbols/strings.

Implementation sketch:

(define (selector? s)

(or (symbol? s) (string? s)

(and (list? s)

(not (null? s))

(letrec ([f (λ (l)

(if (null? l)

#t

(and (or (symbol? (car l))

(string? (car l)))

(f (cdr l)))))]

(f s))))))