diff --git a/README.md b/README.md index 68f47b5..b119644 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,13 @@ Webview integration for Racket. -## Release v0.1.10 +## Release v0.1.11 + +This release assigns explicit, file-prefixed Scribble tags to manual parts and sections. This prevents duplicate collected-information warnings for headings such as `Overview`, `Example`, `Conversion`, `Events`, and `racket-webview` during `raco setup`. + +The process-interface changes from v0.1.10 remain unchanged. + +### Process interface (introduced in v0.1.10) This version replaces the FFI/shared-memory transport with a child-process interface to racket-webview-qt v0.2.3: diff --git a/info.rkt b/info.rkt index 220233e..6ef645d 100644 --- a/info.rkt +++ b/info.rkt @@ -1,7 +1,7 @@ #lang info (define pkg-authors '(hnmdijkema)) -(define version "0.1.10") +(define version "0.1.11") (define license 'MIT) (define collection "racket-webview") (define pkg-desc "racket-webview - A Web Based GUI library, based on a Qt WebEngine backend") diff --git a/scrbl/js-transform.scrbl b/scrbl/js-transform.scrbl index 9478c13..42a064d 100644 --- a/scrbl/js-transform.scrbl +++ b/scrbl/js-transform.scrbl @@ -3,7 +3,7 @@ @(require (for-label racket/base "../private/js-transform.rkt")) -@title{JavaScript Transformation} +@title[#:tag "js-transform"]{JavaScript Transformation} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/private/js-transform] @@ -47,7 +47,7 @@ This generates JavaScript source that assigns a function to sets an attribute, and writes a message to the JavaScript console. } -@section{Primitive values} +@section[#:tag "js-transform-primitive-values"]{Primitive values} Numbers are emitted as JavaScript numeric literals. Strings are emitted as double-quoted JavaScript strings, with embedded double quotes escaped. @@ -68,7 +68,7 @@ Symbols can be quoted to produce JavaScript string values: (send console log 'hello)) ] -@section{Function calls and method calls} +@section[#:tag "js-transform-function-calls-and-method-calls"]{Function calls and method calls} A form that is not recognized as a special DSL form is treated as a JavaScript function call: @@ -109,7 +109,7 @@ document.getElementById("hi") Using @racket[send] keeps the method-call structure explicit in the DSL. It is usually clearer than writing dotted JavaScript names directly as function names. -@section{Operators} +@section[#:tag "js-transform-operators"]{Operators} The DSL supports a small set of JavaScript infix operators. @@ -138,7 +138,7 @@ For example: (return (* x x))))) ] -@section{Definitions and assignments} +@section[#:tag "js-transform-definitions-and-assignments"]{Definitions and assignments} @defform[(define (name arg ...) body ...)]{ @@ -165,7 +165,7 @@ Generates a JavaScript assignment. This produces an assignment to @tt{window.answer}. } -@section{Functions} +@section[#:tag "js-transform-functions"]{Functions} @defform[(lambda (arg ...) body ...)]{ Generates a JavaScript function expression. @@ -194,7 +194,7 @@ A function body may contain more than one DSL statement: (return (* x x))))) ] -@section{Control flow and statement blocks} +@section[#:tag "js-transform-control-flow-and-statement-blocks"]{Control flow and statement blocks} @defform[(if condition then-expr else-expr)]{ @@ -236,7 +236,7 @@ Generates a JavaScript @tt{return} statement. ] } -@section{Sequential bindings} +@section[#:tag "js-transform-sequential-bindings"]{Sequential bindings} @defform[(let* ((id expr) ...) body ...)]{ @@ -256,7 +256,7 @@ context. Use @racket[let*] instead, so that the generated JavaScript bindings remain explicitly sequential. } -@section{Lists} +@section[#:tag "js-transform-lists"]{Lists} @defform[(list expr ...)]{ @@ -287,7 +287,7 @@ console.log([ x].concat([ y].concat([ z]))); }| } -@section{Embedding Racket values} +@section[#:tag "js-transform-embedding-racket-values"]{Embedding Racket values} @defform[(eval value)]{ @@ -306,7 +306,7 @@ The value is converted to JavaScript source text before the generated JavaScript is returned. } -@section{Example} +@section[#:tag "js-transform-example"]{Example} The following example combines function definition, method calls, list construction, sequential bindings and a lambda expression passed to a JavaScript @@ -327,7 +327,7 @@ method: This generates a JavaScript function that logs an array, constructs the same array in a local binding, maps over it, and returns the mapped result. -@section{Limitations} +@section[#:tag "js-transform-limitations"]{Limitations} This transformer is intentionally small. It is not a complete JavaScript parser, not a JavaScript evaluator and not a general Racket-to-JavaScript diff --git a/scrbl/menu.scrbl b/scrbl/menu.scrbl index 1b2bfe9..b855467 100644 --- a/scrbl/menu.scrbl +++ b/scrbl/menu.scrbl @@ -8,7 +8,7 @@ json "../menu.rkt")) -@title{menu} +@title[#:tag "menu"]{menu} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/menu] @@ -18,7 +18,7 @@ Menu data structures used by the webview library. This module provides constructors, predicates, traversal helpers, mutation operations, and JSON conversion for menu trees. -@section{Overview} +@section[#:tag "menu-overview"]{Overview} A menu is represented as a tree. A menu consists of menu items, and a menu item may optionally contain a submenu. @@ -29,14 +29,14 @@ strings and may be supplied either as @racket[#f], strings, or URL values. The module does not display menus itself. It provides the menu data structure used by higher layers. -@section{Internal Representation} +@section[#:tag "menu-internal-representation"]{Internal Representation} Internally, menus are represented by transparent structure values. These structure constructors and predicates are not exported directly. The public API uses constructor procedures and helper functions operating on those internal values. -@section{Predicates} +@section[#:tag "menu-predicates"]{Predicates} @defproc[(is-wv-menu? [mnu any/c]) boolean?]{ @@ -48,7 +48,7 @@ list is a list of internal menu items, and every submenu recursively also satisfies @racket[is-wv-menu?]. } -@section{Constructors} +@section[#:tag "menu-constructors"]{Constructors} @defproc[(wv-menu [item-or-id any/c] ...) any/c]{ @@ -97,7 +97,7 @@ stored. If any argument does not satisfy these conditions, an exception is raised. } -@section{Traversal and Lookup} +@section[#:tag "menu-traversal-and-lookup"]{Traversal and Lookup} @defproc[(wv-menu-for-each [menu any/c] [cb procedure?]) boolean?]{ @@ -121,7 +121,7 @@ After the callback has been applied, the original @racket[menu] value is returned. } -@section{Mutation} +@section[#:tag "menu-mutation"]{Mutation} @defproc[(wv-menu-set-title! [menu any/c] [id symbol?] [title string?]) any/c]{ @@ -154,7 +154,7 @@ Sets the callback of the menu item identified by @racket[id]. @racket[menu] value. } -@section{Conversion} +@section[#:tag "menu-conversion"]{Conversion} @defproc[(wv-menu->json [menu any/c]) string?]{ @@ -177,7 +177,7 @@ The @racket['id] field of the top-level menu is also converted to a string in the JSON output. } -@section{Accessors} +@section[#:tag "menu-accessors"]{Accessors} @defproc[(wv-menu-id [m any/c]) any/c]{ diff --git a/scrbl/racket-webview-collection.scrbl b/scrbl/racket-webview-collection.scrbl index 7046bea..d01c3a4 100644 --- a/scrbl/racket-webview-collection.scrbl +++ b/scrbl/racket-webview-collection.scrbl @@ -5,7 +5,7 @@ scribble/core ) -@title{@elem{racket-webview}} +@title[#:tag "racket-webview-collection"]{@elem{racket-webview}} @table-of-contents[] diff --git a/scrbl/racket-webview-downloader.scrbl b/scrbl/racket-webview-downloader.scrbl index a750d50..2468f48 100644 --- a/scrbl/racket-webview-downloader.scrbl +++ b/scrbl/racket-webview-downloader.scrbl @@ -7,7 +7,7 @@ setup/dirs "../racket-webview-downloader.rkt")) -@title{racket-webview-downloader} +@title[#:tag "racket-webview-downloader"]{racket-webview-downloader} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/racket-webview-downloader] @@ -18,7 +18,7 @@ This module provides functions for checking whether the native runtime is already installed, whether it can be resolved and downloaded, and for downloading and unpacking it into the user's addon directory. -@section{Overview} +@section[#:tag "racket-webview-downloader-overview"]{Overview} The module manages one specific downloadable version of the native @tt{racket-webview-qt} package. The version is fixed in the source code through @@ -36,7 +36,7 @@ The download URL is derived from: The downloaded archive is installed below the user's addon directory in a subdirectory named @tt{racket-webview-qt}. -@section{Installation Layout} +@section[#:tag "racket-webview-downloader-installation-layout"]{Installation Layout} The installation directory is: @@ -57,7 +57,7 @@ The OS and architecture components are derived from: (system-type 'arch) ] -@section{Availability and Version Checks} +@section[#:tag "racket-webview-downloader-availability-and-version-checks"]{Availability and Version Checks} @defproc[(racket-webview-qt-is-available?) boolean?]{ @@ -93,7 +93,7 @@ The returned path has the form: ] } -@section{Downloadability Checks} +@section[#:tag "racket-webview-downloader-downloadability-checks"]{Downloadability Checks} @defproc[(racket-webview-qt-resolves?) boolean?]{ @@ -114,7 +114,7 @@ succeeds, the port is closed immediately and the function returns @racket[#t]. Any failure is caught and results in @racket[#f]. } -@section{Downloading} +@section[#:tag "racket-webview-downloader-downloading"]{Downloading} @defproc[(download-racket-webview-qt) boolean?]{ @@ -138,7 +138,7 @@ If no download port can be obtained, the function raises an exception. Otherwise on successful completion, it returns @racket[#t]. } -@section{Notes} +@section[#:tag "racket-webview-downloader-notes"]{Notes} The module forces HTTPS downloads by temporarily setting the current HTTPS protocol to @racket['secure] while opening the download port. diff --git a/scrbl/racket-webview-intro.scrbl b/scrbl/racket-webview-intro.scrbl index 732730d..f276b62 100644 --- a/scrbl/racket-webview-intro.scrbl +++ b/scrbl/racket-webview-intro.scrbl @@ -23,12 +23,12 @@ @(define version (webview-version-string)) -@title{Racket Webview - v@version - Introduction} +@title[#:tag "racket-webview-intro"]{Racket Webview - v@version - Introduction} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule{racket-webview} -@section{Overview} +@section[#:tag "racket-webview-intro-overview"]{Overview} This documentation is provided for version @bold{@version} of racket webview. @@ -41,7 +41,7 @@ On top of that, @racketmodname[racket-webview/racket-webview] provides a functional API. The class-oriented API described in this manual is built from smaller modules on top of that layer. -@section{Core Concepts} +@section[#:tag "racket-webview-intro-core-concepts"]{Core Concepts} The library is structured around two main concepts: @@ -52,7 +52,7 @@ The library is structured around two main concepts: A context manages local file serving, certificates, and settings. A window loads content, handles events, and provides access to DOM elements. -@section{Modules} +@section[#:tag "racket-webview-intro-modules"]{Modules} The public API is divided into the following modules: @@ -66,7 +66,7 @@ The public API is divided into the following modules: @item{@racketmodname[racket-webview/rgba] — RGBA color values} @item{@racketmodname[racket-mimetypes] — MIME type lookup}] -@section{Typical Usage} +@section[#:tag "racket-webview-intro-typical-usage"]{Typical Usage} A typical application creates a @racket[wv-context%] object and then creates one or more @racket[wv-window%] objects within that context. DOM elements are diff --git a/scrbl/racket-webview-qt.scrbl b/scrbl/racket-webview-qt.scrbl index ab23024..d75ceca 100644 --- a/scrbl/racket-webview-qt.scrbl +++ b/scrbl/racket-webview-qt.scrbl @@ -5,7 +5,7 @@ @title[#:tag "rktwebview-process"]{Racket Process Interface for @tt{rktwebview_prg}} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] -@section{Overview} +@section[#:tag "racket-webview-qt-overview"]{Overview} The module @tt{racket-webview-qt.rkt} provides the low-level Racket interface to the Qt helper process @tt{rktwebview_prg}. It keeps the existing command numbers, @@ -33,7 +33,7 @@ The module provides: @item{asynchronous event delivery} @item{version and cleanup utilities}] -@section{Backend Availability} +@section[#:tag "racket-webview-qt-backend-availability"]{Backend Availability} The environment variable @tt{RKT_WEBVIEW_PRG} may name an explicit backend executable. This is useful during development and testing. @@ -43,7 +43,7 @@ directory. Availability is checked when the first backend operation is made, not while the module is loaded. If the configured backend cannot be found or downloaded, that operation raises an exception with the reason. -@section{Module Initialization} +@section[#:tag "racket-webview-qt-module-initialization"]{Module Initialization} Starting the backend performs the following steps: @@ -61,9 +61,9 @@ written only to stderr. Currently the wrapper supports @tt{'linux} and @tt{'windows} release layouts. -@section{Data Model} +@section[#:tag "racket-webview-qt-data-model"]{Data Model} -@subsection{The @tt{rkt-wv} Structure} +@subsection[#:tag "racket-webview-qt-rkt-wv-structure"]{The @tt{rkt-wv} Structure} Each webview window is represented by a transparent Racket structure. @@ -95,7 +95,7 @@ an opaque handle. @;Returns the native window handle associated with @racket[wv]. @;} -@section{HTTP(S) Contexts} +@section[#:tag "racket-webview-qt-http-s-contexts"]{HTTP(S) Contexts} A context represents the shared HTTP(S) environment used by webviews. @@ -126,7 +126,7 @@ The returned context identifier can be passed to @racket[rkt-webview-create] to create webviews within that context. } -@section{Creating Webviews} +@section[#:tag "racket-webview-qt-creating-webviews"]{Creating Webviews} @defproc[(rkt-webview-create [context exact-integer?] @@ -153,7 +153,7 @@ Events generated by the native layer are delivered asynchronously through @racket[evt-callback]. } -@section{Window Lifecycle} +@section[#:tag "racket-webview-qt-window-lifecycle"]{Window Lifecycle} @defproc[(rkt-webview-close [wv rkt-wv?]) boolean?]{ @@ -182,7 +182,7 @@ This function is also registered with the Racket plumber so that cleanup occurs automatically when the process exits. } -@section{Window Configuration} +@section[#:tag "racket-webview-qt-window-configuration"]{Window Configuration} @defproc[(rkt-webview-set-title! [wv rkt-wv?] [title string?]) symbol?]{ @@ -206,7 +206,7 @@ This token may be used by the native layer when accepting certain self-signed certificates. } -@section{Navigation} +@section[#:tag "racket-webview-qt-navigation"]{Navigation} @defproc[(rkt-webview-set-url! [wv rkt-wv?] [url string?]) symbol?]{ @@ -232,7 +232,7 @@ Returns a result symbol such as: ] } -@section{JavaScript Execution} +@section[#:tag "racket-webview-qt-javascript-execution"]{JavaScript Execution} @defproc[(rkt-webview-run-js [wv rkt-wv?] [js string?]) symbol?]{ @@ -265,7 +265,7 @@ where: The JSON structure is generated by the native backend. } -@section{Window Geometry} +@section[#:tag "racket-webview-qt-window-geometry"]{Window Geometry} @defproc[(rkt-webview-move [wv rkt-wv?] [x exact-integer?] [y exact-integer?]) symbol?]{ @@ -322,13 +322,13 @@ Possible results: ] } -@section{Developer Tools} +@section[#:tag "racket-webview-qt-developer-tools"]{Developer Tools} @defproc[(rkt-webview-open-devtools [wv rkt-wv?]) symbol?]{ Opens the browser developer tools window. } -@section{Native Dialogs} +@section[#:tag "racket-webview-qt-native-dialogs"]{Native Dialogs} Dialog functions return immediately with a status code. The user’s choice is delivered asynchronously through the event callback. @@ -373,7 +373,7 @@ Requests a file-save dialog. Shows a native message box. } -@section{Event Delivery} +@section[#:tag "racket-webview-qt-event-delivery"]{Event Delivery} Each webview has an associated event callback. @@ -405,7 +405,7 @@ Typical event types include: The wrapper does not parse the JSON payload. -@section{Version Information} +@section[#:tag "racket-webview-qt-version-information"]{Version Information} @defproc[(rkt-webview-version) (list/c list? list?)]{ @@ -421,7 +421,7 @@ Example result: ] } -@section{Example} +@section[#:tag "racket-webview-qt-example"]{Example} @racketblock[ (define ctx @@ -440,7 +440,7 @@ Example result: (rkt-webview-set-url! wv "https://example.org") ] -@section{Summary} +@section[#:tag "racket-webview-qt-summary"]{Summary} The module provides a thin Racket interface to the separate @tt{rktwebview_prg} process. diff --git a/scrbl/racket-webview.scrbl b/scrbl/racket-webview.scrbl index b6e8b0d..093748c 100644 --- a/scrbl/racket-webview.scrbl +++ b/scrbl/racket-webview.scrbl @@ -3,7 +3,7 @@ @(require racket/base scribble/core) -@title{racket-webview} +@title[#:tag "racket-webview"]{racket-webview} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/racket-webview] @@ -14,7 +14,7 @@ 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. -@section{Architecture} +@section[#:tag "racket-webview-architecture"]{Architecture} The module builds on the lower-level bindings from @racketmodname[racket-webview/racket-webview-qt]. It adds: @@ -31,7 +31,7 @@ JavaScript calls. When an HTML file is served, the context's CSS boilerplate is injected immediately before the closing @tt{} tag. -@section{Contexts} +@section[#:tag "racket-webview-contexts"]{Contexts} @defproc[(webview-new-context @@ -76,7 +76,7 @@ This URL can be used to construct URLs from relative path information. Recognizes context values. } -@section{Windows} +@section[#:tag "racket-webview-windows"]{Windows} @defproc[(webview-create [context wv-context?] @@ -136,7 +136,7 @@ Resizes the window. Returns the current window state. } -@section{Navigation and Content} +@section[#:tag "racket-webview-navigation-and-content"]{Navigation and Content} @defproc[(webview-set-url! [wv wv-win?] [url (or/c string? url?)]) symbol?]{ @@ -176,7 +176,7 @@ The result is the symbol returned by @racket[webview-run-js]. Sets the window title. } -@section{JavaScript} +@section[#:tag "racket-webview-javascript"]{JavaScript} @defproc[(webview-run-js [wv wv-win?] [js string?]) symbol?]{ Evaluates JavaScript. @@ -196,7 +196,7 @@ structure, an exception is raised. } -@section{Dialogs} +@section[#:tag "racket-webview-dialogs"]{Dialogs} Dialog functions return immediately. Results are delivered asynchronously via events. @@ -254,9 +254,9 @@ is indicated through the event. } -@section{DOM Interaction} +@section[#:tag "racket-webview-dom-interaction"]{DOM Interaction} -@subsection{Selectors and Element Identifiers} +@subsection[#:tag "racket-webview-selectors-and-element-identifiers"]{Selectors and Element Identifiers} Many functions accept either an element identifier or a CSS selector. @@ -272,7 +272,7 @@ If a string is provided, it is used directly as a CSS selector. Functions apply their effect to all matched elements. -@subsection{Event Binding} +@subsection[#:tag "racket-webview-event-binding"]{Event Binding} @defproc[(webview-bind! [wv wv-win?] @@ -300,7 +300,7 @@ Selector handling is the same as for @racket[webview-bind!]. The result is a list describing the removed bindings. } -@subsection{DOM Values} +@subsection[#:tag "racket-webview-dom-values"]{DOM Values} @defproc[(webview-set-value! [wv wv-win?] @@ -367,7 +367,7 @@ Returns the value converted to a datetime. Returns the value converted to a color. } -@subsection{Classes, Styles} +@subsection[#:tag "racket-webview-classes-styles"]{Classes, Styles} @defproc[(webview-add-class! [wv wv-win?] @@ -428,7 +428,7 @@ If @racket[selector] is a symbol, the result for that single element is returned directly. Otherwise the result covers all matched elements. } -@subsection{Attributes} +@subsection[#:tag "racket-webview-attributes"]{Attributes} @defproc[(webview-set-attr! [wv wv-win?] @@ -517,7 +517,7 @@ Returns the attribute value converted to a datetime. Returns the attribute value converted to a color. } -@subsection{Inner HTML} +@subsection[#:tag "racket-webview-inner-html"]{Inner HTML} @defproc[(webview-set-innerHTML! [wv wv-win?] @@ -531,7 +531,7 @@ Returns @racket['oke] if the injected JavaScript yields a true value, and @racket['failed] otherwise. } -@section{File Filters} +@section[#:tag "racket-webview-file-filters"]{File Filters} @defstruct*[wv-permitted-exts ([name string?] [exts (listof symbol?)])]{ @@ -548,7 +548,7 @@ Represents a file dialog filter entry. Recognizes lists of filter entries. } -@section{Utilities} +@section[#:tag "racket-webview-utilities"]{Utilities} @defproc[(webview-default-boilerplate-js [custom-js procedure?] ...) string?]{ @@ -576,7 +576,7 @@ If an additional procedure is supplied, its returned string is appended to that Creates a standard file getter. } -@section{Diagnostics} +@section[#:tag "racket-webview-diagnostics"]{Diagnostics} @defproc[(webview-version) list?]{ Returns version information. diff --git a/scrbl/rgba.scrbl b/scrbl/rgba.scrbl index f84ef25..bba942e 100644 --- a/scrbl/rgba.scrbl +++ b/scrbl/rgba.scrbl @@ -6,7 +6,7 @@ racket/string racket/contract)) -@title{rgba} +@title[#:tag "rgba"]{rgba} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/rgba] @@ -16,7 +16,7 @@ RGBA color support used by the webview library. This module exports a transparent @racket[rgba] structure together with predicates and conversion procedures for working with CSS-style color values. -@section{Overview} +@section[#:tag "rgba-overview"]{Overview} An @racket[rgba] value represents a color using red, green, blue, and alpha components. @@ -35,7 +35,7 @@ The intended external representation is the CSS form: "rgba(r,g,b,a)" ] -@section{Predicates} +@section[#:tag "rgba-predicates"]{Predicates} @defproc[(rgba/color? [v any/c]) boolean?]{ @@ -53,7 +53,7 @@ A valid alpha component is a real number in the range from @racket[0] to @racket[1], inclusive. } -@section{Structure Type} +@section[#:tag "rgba-structure-type"]{Structure Type} @defstruct*[rgba ([r rgba/color?] [g rgba/color?] @@ -68,7 +68,7 @@ components. The field @racket[a] is the alpha component. The structure is transparent. } -@section{Conversion} +@section[#:tag "rgba-conversion"]{Conversion} @defproc[(rgba->string [c rgba?]) string?]{ diff --git a/scrbl/rktwebview-api.scrbl b/scrbl/rktwebview-api.scrbl index e44b57b..b655ecc 100644 --- a/scrbl/rktwebview-api.scrbl +++ b/scrbl/rktwebview-api.scrbl @@ -4,7 +4,7 @@ @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] -@title{C API for Racket Integration} +@title[#:tag "rktwebview-api"]{C API for Racket Integration} This section documents the legacy C API defined in @tt{rktwebview.h} and @tt{rktwebview_types.h}. The source remains in the backend repository for @@ -16,7 +16,7 @@ return a @tt{result_t}, and structured values are returned as @tt{rkt_data_t *}. The latter are caller-owned and must be released with @tt{rkt_webview_free_data()}. -@section{Version, Export, and Basic Types} +@section[#:tag "rktwebview-api-version-export-and-basic-types"]{Version, Export, and Basic Types} The public API version is: @@ -40,7 +40,7 @@ typedef int rkt_wv_context_t; @tt{rktwebview_t} identifies a webview. @tt{rkt_wv_context_t} identifies a context. -@section{Enums and Structured Data} +@section[#:tag "rktwebview-api-enums-and-structured-data"]{Enums and Structured Data} The API defines the following enums: @tt{rkt_webview_loglevel_t}, @tt{result_t}, @tt{window_state_t}, @tt{rkt_messagetype_t}, and @@ -92,7 +92,7 @@ typedef struct { The @tt{kind} field determines which member of @tt{data} is valid. -@section{Ownership} +@section[#:tag "rktwebview-api-ownership"]{Ownership} Any function returning @tt{rkt_data_t *} returns allocated memory. The caller must release it using: @@ -105,7 +105,7 @@ This applies to values returned by @tt{rkt_webview_info()}, @tt{rkt_webview_version()}, @tt{rkt_webview_get_event()}, and @tt{rkt_webview_call_js()}. -@section{Environment and Runtime Control} +@section[#:tag "rktwebview-api-environment-and-runtime-control"]{Environment and Runtime Control} @defproc[(rkt_webview_env [env_cmds any/c]) void?]{ C signature: @@ -185,7 +185,7 @@ Returns a pointer to @tt{rkt_data_t}. The returned object has Return value: @tt{rkt_data_t *}, caller-owned. } -@subsection{Events} +@subsection[#:tag "rktwebview-api-events"]{Events} @defproc[(rkt_webview_events_waiting) exact-integer?]{ C signature: @@ -213,7 +213,7 @@ returned pointer may be null. Return value: @tt{rkt_data_t *}, caller-owned, or null. } -@subsubsection{Event Polling} +@subsubsection[#:tag "rktwebview-api-event-polling"]{Event Polling} Events are retrieved explicitly by polling. In normal use, polling should be performed regularly; a polling interval of about 10 ms is appropriate. @@ -222,7 +222,7 @@ This keeps the event queue flowing, allows asynchronous operations such as dialogs to complete in a timely manner, and avoids the impression that the system has stalled while the Racket side is simply not looking. -@section{Contexts} +@section[#:tag "rktwebview-api-contexts"]{Contexts} @defproc[(rkt_webview_new_context [boilerplate_js string?] [optional_server_cert_pem string?]) @@ -240,7 +240,7 @@ self-signed certificate. Return value: @tt{rkt_wv_context_t}. } -@section{Webviews} +@section[#:tag "rktwebview-api-webviews"]{Webviews} @defproc[(rkt_webview_create [context exact-integer?] [parent exact-integer?]) @@ -308,7 +308,7 @@ specified webview. Return value: none. } -@section{Navigation and JavaScript} +@section[#:tag "rktwebview-api-navigation-and-javascript"]{Navigation and JavaScript} @defproc[(rkt_webview_set_url [wv exact-integer?] [url string?]) exact-integer?]{ C signature: @@ -378,7 +378,7 @@ Opens developer tools for the specified webview. Return value: @tt{result_t}. } -@section{Window Management} +@section[#:tag "rktwebview-api-window-management"]{Window Management} @defproc[(rkt_webview_move [w exact-integer?] [x exact-integer?] [y exact-integer?]) exact-integer?]{ @@ -492,7 +492,7 @@ Returns the current state of the specified window. Return value: @tt{window_state_t}. } -@section{Dialogs} +@section[#:tag "rktwebview-api-dialogs"]{Dialogs} The dialog functions are asynchronous. They request that the dialog be opened on the Qt side, but do not block the Racket side while the dialog is shown. This is @@ -575,7 +575,7 @@ reported through events. Return value: @tt{result_t}. } -@section{Remarks} +@section[#:tag "rktwebview-api-remarks"]{Remarks} The API is queue-based. Commands are issued through function calls; events are retrieved explicitly using @tt{rkt_webview_events_waiting()} and diff --git a/scrbl/rktwebviewqt-internals.scrbl b/scrbl/rktwebviewqt-internals.scrbl index 258273b..e5bc82b 100644 --- a/scrbl/rktwebviewqt-internals.scrbl +++ b/scrbl/rktwebviewqt-internals.scrbl @@ -2,10 +2,10 @@ @defmodule{racket-webview/internals} -@title{Qt WebView Backend Architecture} +@title[#:tag "rktwebviewqt-internals"]{Qt WebView Backend Architecture} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] -@section{Overview} +@section[#:tag "rktwebviewqt-internals-overview"]{Overview} The runtime consists of two processes. The Racket process owns the public API, contexts used by the local HTTPS server, handle wrappers, and user callbacks. @@ -15,7 +15,7 @@ The helper process @tt{rktwebview_prg} owns @tt{QApplication}, Qt widgets, The processes communicate through standard pipes. There is no shared library, shared-memory queue, or callback from native code into the Racket runtime. -@section{Standard Streams} +@section[#:tag "rktwebviewqt-internals-standard-streams"]{Standard Streams} The streams have fixed roles: @@ -28,7 +28,7 @@ Messages on stdin and stdout are compact UTF-8 JSON objects, one object per line. Stdout must not contain ordinary logging because the Racket protocol reader treats every value there as a protocol record. -@section{Protocol Compatibility} +@section[#:tag "rktwebviewqt-internals-protocol-compatibility"]{Protocol Compatibility} The command identifiers in @tt{rkt_protocol.h} and the JSON objects used as command payloads are unchanged. The process transport adds an outer message @@ -45,7 +45,7 @@ A corresponding result has this form: The request identifier prevents concurrent calls from consuming each other's results. It is not visible in the public API. -@section{Command Execution} +@section[#:tag "rktwebviewqt-internals-command-execution"]{Command Execution} A Racket caller registers a private response channel, writes a command while holding the transport write lock, and waits on that channel. @@ -58,7 +58,7 @@ result record to stdout. The Racket stdout reader is the only thread that reads protocol output. It uses the request identifier to forward each result to the correct waiting caller. -@section{Event Delivery} +@section[#:tag "rktwebviewqt-internals-event-delivery"]{Event Delivery} Qt events remain the original JSON strings. The Qt callback converts them only into this transport record: @@ -75,7 +75,7 @@ closure. Qt writes the @tt{"closed"} event before the result of the close comman The handle can be removed immediately after the result reaches its caller, but the already captured callback still receives the event. -@section{Contexts and Handles} +@section[#:tag "rktwebviewqt-internals-contexts-and-handles"]{Contexts and Handles} A context corresponds to a @tt{QWebEngineProfile} and is identified by an integer. A webview or tray icon is also identified by an integer handle. Only @@ -84,7 +84,7 @@ these numbers cross the process boundary; Qt object pointers never do. The existing Racket @tt{rkt-wv} structure is retained so the higher layers do not need to change. -@section{Lifecycle and Failure Handling} +@section[#:tag "rktwebviewqt-internals-lifecycle-and-failure-handling"]{Lifecycle and Failure Handling} The backend writes a protocol-version handshake after initialization. Racket waits for this handshake before sending application commands. @@ -100,14 +100,14 @@ loop. This replaces the former shared-memory alive and alive-ack queues. If stdout closes unexpectedly, Racket marks all handles invalid and delivers an exception to every command still waiting for a result. -@section{Logging} +@section[#:tag "rktwebviewqt-internals-logging"]{Logging} The Qt backend writes its existing log messages to stderr. Racket forwards that stream to its current error port. The @racket[rkt-webview-info] result reports @tt{"stderr"} as the backend log destination and retains zero-valued shared-memory metrics for compatibility with callers that display those fields. -@section{Development Override} +@section[#:tag "rktwebviewqt-internals-development-override"]{Development Override} Setting @tt{RKT_WEBVIEW_PRG} to a backend executable bypasses the installed release directory. This makes it possible to test a newly compiled backend diff --git a/scrbl/wv-context.scrbl b/scrbl/wv-context.scrbl index ba9194b..409f64f 100644 --- a/scrbl/wv-context.scrbl +++ b/scrbl/wv-context.scrbl @@ -10,12 +10,12 @@ "../wv-context.rkt" )) -@title{wv-context} +@title[#:tag "wv-context"]{wv-context} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/wv-context] -@section{Overview} +@section[#:tag "wv-context-overview"]{Overview} The library is organized around two main concepts: contexts and windows. diff --git a/scrbl/wv-dialog.scrbl b/scrbl/wv-dialog.scrbl index 61cb549..12f59eb 100644 --- a/scrbl/wv-dialog.scrbl +++ b/scrbl/wv-dialog.scrbl @@ -8,7 +8,7 @@ "../wv-dialog.rkt" "../wv-window.rkt")) -@title{wv-dialog} +@title[#:tag "wv-dialog"]{wv-dialog} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/wv-dialog] @@ -18,7 +18,7 @@ Dialog-window wrapper built on top of @racket[wv-window%]. This module exports the @racket[wv-dialog%] class. It is a specialized window class whose initial size and position are derived from its parent window. Closing a dialog does not quit the application by default. -@section{Overview} +@section[#:tag "wv-dialog-overview"]{Overview} A @racket[wv-dialog%] object is a @racket[wv-window%] that initializes itself as a dialog relative to its parent window. @@ -27,7 +27,7 @@ The class inherits the window lifecycle, event handling, navigation, and dialog support from @racket[wv-window%]. Its only specialization in the current source is the implementation of @racket[init-size]. A dialog also changes the inherited @racket[quit-on-close] default to @racket[#f]. -@section{Class: wv-dialog%} +@section[#:tag "wv-dialog-class-wv-dialog"]{Class: wv-dialog%} @defclass[wv-dialog% wv-window% ()]{ diff --git a/scrbl/wv-element.scrbl b/scrbl/wv-element.scrbl index 4e0c65c..0af629c 100644 --- a/scrbl/wv-element.scrbl +++ b/scrbl/wv-element.scrbl @@ -10,7 +10,7 @@ "../racket-webview.rkt" "../wv-element.rkt")) -@title{wv-element} +@title[#:tag "wv-element"]{wv-element} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/wv-element] @@ -22,7 +22,7 @@ represent one DOM element within a @racket[wv-window%] and provide a small object-oriented interface for event dispatch, content replacement, CSS class manipulation, style access, and attribute access. -@section{Overview} +@section[#:tag "wv-element-overview"]{Overview} A @racket[wv-element%] object is associated with: @@ -37,7 +37,7 @@ of its methods therefore follow the contracts of those lower-level functions. The class also stores per-element event callbacks used by @racket[wv-window%] when dispatching JavaScript events received from the browser. -@section{Class: wv-element%} +@section[#:tag "wv-element-class-wv-element"]{Class: wv-element%} @defclass[wv-element% object% ()]{ diff --git a/scrbl/wv-input.scrbl b/scrbl/wv-input.scrbl index 4ea0581..f0f3312 100644 --- a/scrbl/wv-input.scrbl +++ b/scrbl/wv-input.scrbl @@ -11,7 +11,7 @@ "../wv-input.rkt" "../rgba.rkt")) -@title{wv-input} +@title[#:tag "wv-input"]{wv-input} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/wv-input] @@ -22,7 +22,7 @@ This module exports a family of classes derived from @racket[wv-element%]. Each class represents one DOM input element and provides a typed @racket[get] method together with a @racket[set!] method. -@section{Overview} +@section[#:tag "wv-input-overview"]{Overview} All classes in this module inherit from @racket[wv-element%]. @@ -39,7 +39,7 @@ lower-level DOM/value API from @racketmodname[racket-webview]. Their accepted argument shapes and result values therefore follow the contracts of those lower-level functions. -@section{Common Structure} +@section[#:tag "wv-input-common-structure"]{Common Structure} All input wrapper classes have the same constructor shape: @@ -56,7 +56,7 @@ Each class provides two public methods: @item{@racket[get], returning the current typed value} @item{@racket[set!], writing a new value through @racket[webview-set-value!]}] -@section{Class: wv-input/text%} +@section[#:tag "wv-input-class-wv-input-text"]{Class: wv-input/text%} @defclass[wv-input/text% wv-element% ()]{ @@ -89,7 +89,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/number%} +@section[#:tag "wv-input-class-wv-input-number"]{Class: wv-input/number%} @defclass[wv-input/number% wv-element% ()]{ @@ -122,7 +122,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/boolean%} +@section[#:tag "wv-input-class-wv-input-boolean"]{Class: wv-input/boolean%} @defclass[wv-input/boolean% wv-element% ()]{ @@ -155,7 +155,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/date%} +@section[#:tag "wv-input-class-wv-input-date"]{Class: wv-input/date%} @defclass[wv-input/date% wv-element% ()]{ @@ -188,7 +188,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/time%} +@section[#:tag "wv-input-class-wv-input-time"]{Class: wv-input/time%} @defclass[wv-input/time% wv-element% ()]{ @@ -221,7 +221,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/datetime%} +@section[#:tag "wv-input-class-wv-input-datetime"]{Class: wv-input/datetime%} @defclass[wv-input/datetime% wv-element% ()]{ @@ -254,7 +254,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/range%} +@section[#:tag "wv-input-class-wv-input-range"]{Class: wv-input/range%} @defclass[wv-input/range% wv-element% ()]{ @@ -287,7 +287,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/check%} +@section[#:tag "wv-input-class-wv-input-check"]{Class: wv-input/check%} @defclass[wv-input/check% wv-element% ()]{ @@ -320,7 +320,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/radio%} +@section[#:tag "wv-input-class-wv-input-radio"]{Class: wv-input/radio%} @defclass[wv-input/radio% wv-element% ()]{ @@ -353,7 +353,7 @@ Writes @racket[v] by delegating to: } } -@section{Class: wv-input/color%} +@section[#:tag "wv-input-class-wv-input-color"]{Class: wv-input/color%} @defclass[wv-input/color% wv-element% ()]{ diff --git a/scrbl/wv-settings.scrbl b/scrbl/wv-settings.scrbl index e6cd81b..128af50 100644 --- a/scrbl/wv-settings.scrbl +++ b/scrbl/wv-settings.scrbl @@ -9,7 +9,7 @@ racket/file "../wv-settings.rkt")) -@title{wv-settings} +@title[#:tag "wv-settings"]{wv-settings} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/wv-settings] @@ -20,7 +20,7 @@ This module exports the @racket[wv-settings%] class, which provides a small object-oriented interface over an @racket[ini] settings backend. Settings are accessed relative to a context. -@section{Overview} +@section[#:tag "wv-settings-overview"]{Overview} A @racket[wv-settings%] object combines: @@ -30,7 +30,7 @@ A @racket[wv-settings%] object combines: Keys used in this class are symbols. -@section{Class: wv-settings%} +@section[#:tag "wv-settings-class-wv-settings"]{Class: wv-settings%} @defclass[wv-settings% object% ()]{ diff --git a/scrbl/wv-tray.scrbl b/scrbl/wv-tray.scrbl index aed28aa..38cc285 100644 --- a/scrbl/wv-tray.scrbl +++ b/scrbl/wv-tray.scrbl @@ -6,7 +6,7 @@ "../wv-tray.rkt" "../menu.rkt")) -@title{Tray Icons} +@title[#:tag "wv-tray"]{Tray Icons} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] diff --git a/scrbl/wv-window.scrbl b/scrbl/wv-window.scrbl index 46b1afd..aae1fed 100644 --- a/scrbl/wv-window.scrbl +++ b/scrbl/wv-window.scrbl @@ -15,7 +15,7 @@ "../rgba.rkt" "../wv-window.rkt")) -@title{wv-window} +@title[#:tag "wv-window"]{wv-window} @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]] @defmodule[racket-webview/wv-window] @@ -26,7 +26,7 @@ This module exports the @racket[wv-window%] class and re-exports the APIs from @racketmodname[wv-element], @racketmodname[wv-input], @racketmodname[rgba], and @racketmodname[wv-settings]. -@section{Overview} +@section[#:tag "wv-window-overview"]{Overview} A @racket[wv-window%] object represents one webview window. @@ -37,7 +37,7 @@ element wrappers through @racket[element]. The class also provides synchronous wrappers around the asynchronous dialog interface by using continuations internally. -@section{Class: wv-window%} +@section[#:tag "wv-window-class-wv-window"]{Class: wv-window%} @defclass[wv-window% object% ()]{ @@ -478,7 +478,7 @@ The resulting geometry is then applied through @racket[move] and @racket[resize] } } -@section{Events} +@section[#:tag "wv-window-events"]{Events} The window installs an internal event handler when it is created. @@ -499,7 +499,7 @@ This handler reacts to the following event kinds produced by the lower layer: Unhandled events are printed to the console by the current implementation. -@section{Function: root-file-not-found-handler} +@section[#:tag "wv-window-function-root-file-not-found-handler"]{Function: root-file-not-found-handler} @defproc[(root-file-not-found-handler [standard-file string?] [not-found-handler procedure?] ...) @@ -527,7 +527,7 @@ Its behavior is as follows: Only the first optional @racket[not-found-handler] is used. } -@section{Re-exports} +@section[#:tag "wv-window-re-exports"]{Re-exports} This module also re-exports the public APIs from: