High-Level Web Racket GUI API
| (require web-racket) | package: web-racket |
The web-racket module provides a higher-level GUI layer on top of the low-level web-wire backend. It is intended as the main entry point for desktop applications that embed a WebUI.
The module exports:
OO wrappers for DOM elements and form inputs (ww-element%, ww-input%);
classes for main windows and dialogs (ww-webview%, ww-webview-dialog%, ww-webview-message%);
an abstract settings interface (ww-settings%);
backend control and logging helpers re-exported from web-wire;
backend installation/override helpers re-exported from webui-wire-download;
CSS and menu construction helpers re-exported from "css.rkt" and "menu.rkt".
The goal of this layer is:
You rarely call web-wire directly;
you work with windows, elements, and inputs as Racket objects;
only when you need fine-grained control do you drop to the underlying wire API.
1 Re-exported backend control and logging
The following bindings are re-exported directly from web-wire. See that module’s documentation for full details; here is a short summary for convenience.
procedure
log-level : symbol?
Most applications do not call this directly: ww-webview% constructors will automatically call ww-start when the first window is created.
procedure
(ww-stop) → void?
This is called automatically when the last window created via ww-webview% is closed; you normally do not need to call it directly, but you can use it for explicit shutdown.
syntax
#:contracts ([msg-expr any/c]) (ww-debug id-expr msg-expr) #:contracts ([id-expr any/c] [msg-expr any/c])
syntax
#:contracts ([msg-expr any/c]) (ww-error id-expr msg-expr) #:contracts ([id-expr any/c] [msg-expr any/c])
procedure
(ww-tail-log args ...) → void?
args : any/c
2 Re-exported WebUI helper command control
The following bindings are re-exported from webui-wire-download; they are documented in more detail in that module. Briefly:
procedure
(ww-get-webui-wire-version) → string?
3 Re-exported CSS and menu helpers
The module also re-exports:
(all-from-out "css.rkt") — CSS helper functions and css-style values;
(all-from-out "menu.rkt") — menu construction helpers for building menu structures passed to ww-webview%.
See the documentation of those modules for the exact API.
4 Element wrapper classes
These classes provide OO wrappers around DOM elements managed by webui-wire. They work on top of the lower-level web-wire functions that address elements by id.
4.1 Generic element
constructor
(new ww-element% [win-id win-id] [id id] ...superclass-args...) → (is-a?/c ww-element%) win-id : ww-win? id : (or/c symbol? string?) The constructor normally isn’t called directly by user code. Objects are created automatically by ww-webview% when you bind inputs and buttons or when you explicitly request an element.
Fields:
win-id — a ww-win handle identifying the WebUI window that owns this element
id — the element id (symbol or string), as used in the DOM.
Public methods:
method
(send a-ww-element get-win-id) → ww-win?
Return the window handle used for this element.Return the element id.
method
(send a-ww-element win) → (or/c ww-webview% #f)
Look up the ww-webview% instance for win-id in the global window table. Returns #f if the window no longer exists.Call a previously registered callback for evt with the given args. This is used internally when DOM events arrive from webui-wire.Register func as the handler for event kind evt on this element.Remove any callback registered for evt.Merge the given style into the element’s existing style.Replace the element’s style with st.
method
(send a-ww-element style) → css-style?
Return the current style as a css-style value.Get a single attribute value as JSON.Set an attribute value.Remove an attribute.Return all attributes as a hash table (symbol → value).Add a CSS class to the element.Remove a CSS class.Test whether the element has a given CSS class.Remove the disabled state from the element (by manipulating its CSS/attributes).Return #t when the element is not disabled.Mark the element as disabled (e.g. by adding a disabled attribute and/or class).Return #t when the element is disabled.Set the CSS display style; default is "block".Show the element again (typically restoring display to a non-"none" value).
4.2 Form input element
|
superclass: ww-element% |
the current value (mirrored from the DOM);
an optional change callback.
method
(send a-ww-input get) → any/c
Return the last known value of the input.Register a change callback:
The callback is stored;
It is immediately called once with the current value;
Later, when an input event with a value field arrives from the browser, the stored callback is called with the new value.
Set the input’s value both locally and in the DOM. This will normally update the form control on screen and may also trigger change/input events in the browser.Disable the input (overrides base behaviour).Enable the input again (overrides base behaviour).
5 Webview windows
5.1 Main windows
constructor
(new ww-webview% [ [profile profile] [settings settings] [use-browser use-browser] [parent-id parent-id] [parent parent] [title title]] [x x] [y y] [width width] [height height] [ [icon icon] [menu menu] [html-file html-file]] ...superclass-args...) → (is-a?/c ww-webview%) profile : symbol? = 'default-profile settings : (or/c #f ww-settings%) = #f use-browser : boolean? = #f parent-id : (or/c #f ww-win?) = #f parent : (or/c #f ww-webview%) = #f title : string? = "Racket HTML Window" x : number? y : number? width : number? height : number? icon : (or/c #f path? string?) = #f menu : any/c = #f html-file : (or/c #f path? string?) = #f The numeric geometry defaults (x, y, width, height) are taken either from settings or from builtin defaults.If parent or parent-id is provided, a child window is created and positioned relative to the parent; otherwise a normal top-level window is created.
If menu, icon, or html-file are provided, they are applied after window creation.
Important behaviour during construction:
when the first window is created, ww-start is called;
the new window is registered in the global windows table;
an event handler is installed so that incoming events from webui-wire are dispatched to methods like handle-click and handle-change;
when the last window is destroyed, ww-stop is called.
Key public methods (grouped by responsibility):
Settings and cloning
If settings is non-#f, call clone on it to obtain a section-specific settings object, otherwise return #f.Event handling hooks
These are normally invoked internally when events arrive from webui-wire, but can be overridden in subclasses.
Find the element object for element-id (if present) and call its callback method with the 'click event.Find the element object and delegate a 'change event.Find the element object and delegate an input event.
method
(send a-ww-webview handle-navigate url type kind) → void? url : string? type : symbol? kind : symbol? Handle navigation events (for example link clicks) as reported by webui-wire. The default implementation may call send-url depending on type and kind.Element management
method
(send a-ww-webview get-win-id) → ww-win?
Return the underlying ww-win handle.Return (and lazily create) an element wrapper for a given DOM id. The concrete class is chosen based on the element’s tag and type (ww-input% for input fields, or ww-element% otherwise).
method
(send a-ww-webview get-elements selector)
→ (listof ww-element%) selector : selector? Query elements matching selector via ww-get-elements and return a list of element wrapper objects.
method
(send a-ww-webview bind event selector [ forced-cl]) → void? event : symbol? selector : selector? forced-cl : (or/c #f (is-a?/c ww-element%)) = #f Bind event to all elements matching selector.A suitable element class is chosen automatically based on tag/type, unless forced-cl is provided; in that case the given class is used for all matched elements.
Convenience: bind 'change events for input and textarea elements and create ww-input% wrappers.Convenience: bind 'click events for button elements.Window geometry and title
Move the window to (x, y).Resize the window to width x, height y.Current x position (cached).Current y position (cached).Current width (cached).Current height (cached).Set the window title (cached locally and sent to the backend).Return the last title set.Show/hide and lifetime
Show the window (set show state to 'show).Hide the window.Maximise the window.Restore the window to its normal state.Minimise the window.Request a fullscreen display (if supported).Return the current show state as reported by the backend.Return #t if the window may be closed; subclasses can override this to veto close requests.Close the window, unregister it from the global tables, and if this is the last window, stop the backend by calling ww-stop.Menus
Set the window menu using a structure created with the helpers from "menu.rkt".Associate a callback cb with a menu item id. When the menu item is activated, the callback is called.HTML and navigation
Set the window icon; the file is validated by ww-set-icon.Load the given HTML file. The directory part is used to adjust ww-cwd, and the file name is passed to ww-set-html-file.Write html to a temporary file and call set-html-file! with it. Intended for simple dynamic content.Open the given URL using send-url.Hook that is called when a page is fully loaded and matches the current HTML handle. The default implementation binds buttons and inputs by calling bind-buttons and bind-inputs.File and directory dialogs
method
(send a-ww-webview file-open caption base-dir filters) → (or/c #f path?) caption : string? base-dir : string? filters : string? Show a file-open dialog and return the selected path as a path, or #f if the operation failed or was cancelled.
method
(send a-ww-webview file-save caption base-dir filters [ overwrite]) → (or/c #f path?) caption : string? base-dir : string? filters : string? overwrite : boolean? = #f Show a file-save dialog. The overwrite flag controls whether overwriting existing files is allowed. Returns the chosen path, or #f if cancelled or if the command failed.
method
(send a-ww-webview choose-dir caption base-dir) → (or/c #f path?) caption : string? base-dir : string? Show a directory chooser dialog; return the chosen directory, or #f on cancel/failure.Hook for subclasses
Called early during construction to allow subclasses to enforce preconditions (for example: “dialog windows must have a parent”). The default implementation simply returns #t.
5.2 Dialog windows
|
superclass: ww-webview% |
(define/override (inherit-checks) (when (eq? parent #f) (error "A parent must be given")))
5.3 Message dialogs
|
superclass: ww-webview-dialog% |
calls the ww-webview-dialog% constructor;
sets a minimal HTML page containing a message header and a submessage, with known element ids (e.g. "msg" and "submsg").
6 Settings abstraction
Set a configuration value for key. Default implementation raises an error.Look up a configuration value for key. If the key is not present, return default (if provided) or raise an error. The default implementation always raises an error.Return a “cloned” settings object for a given section or profile. Used by ww-webview% to derive per-window settings from a shared base. Default implementation raises an error.Convenience that forwards to set. Provided for symmetry with Racket’s set! naming style.