Documentation and some other stuff.

scrbl/wv-input.scrbl

@@ -0,0 +1,386 @@
+#lang scribble/manual
+
+@(require racket/base
+          racket/class
+          scribble/core
+          (for-label racket/base
+                     racket/class
+                     "../private/racket-webview.rkt"
+                     "../private/wv-element.rkt"
+                     "../private/wv-window.rkt"
+                     "../private/rgba.rkt"))
+
+@title{wv-input}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defmodule[wv-input]
+
+Typed input-element wrappers used by the window layer.
+
+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}
+
+All classes in this module inherit from @racket[wv-element%].
+
+Each input wrapper:
+
+@itemlist[#:style 'compact
+ @item{is associated with one @racket[wv-window%]}
+ @item{is associated with one DOM element id}
+ @item{uses @racket[webview-set-value!] to write values}
+ @item{uses a type-specific @racket[webview-value*] function to read values}]
+
+The classes do not add their own storage. They delegate directly to the
+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}
+
+All input wrapper classes have the same constructor shape:
+
+@racketblock[
+(new some-input% [window some-window] [element-id 'some-id])
+]
+
+where @racket[window] is the owning @racket[wv-window%] and
+@racket[element-id] is the DOM id of the corresponding element.
+
+Each class provides two public methods:
+
+@itemlist[#:style 'compact
+ @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%}
+
+@defclass[wv-input/text% wv-element% ()]{
+
+Wrapper for a text input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a text-input wrapper.
+}
+
+@defmethod[(get) (or/c string? boolean?)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/number%}
+
+@defclass[wv-input/number% wv-element% ()]{
+
+Wrapper for a numeric input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a numeric-input wrapper.
+}
+
+@defmethod[(get) (or/c number? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/number wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/boolean%}
+
+@defclass[wv-input/boolean% wv-element% ()]{
+
+Wrapper for an input whose value is interpreted as a boolean.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a boolean-input wrapper.
+}
+
+@defmethod[(get) (or/c boolean? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/boolean wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/date%}
+
+@defclass[wv-input/date% wv-element% ()]{
+
+Wrapper for a date input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a date-input wrapper.
+}
+
+@defmethod[(get) (or/c g:date? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/date wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/time%}
+
+@defclass[wv-input/time% wv-element% ()]{
+
+Wrapper for a time input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a time-input wrapper.
+}
+
+@defmethod[(get) (or/c g:time? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/time wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/datetime%}
+
+@defclass[wv-input/datetime% wv-element% ()]{
+
+Wrapper for a datetime input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a datetime-input wrapper.
+}
+
+@defmethod[(get) (or/c g:datetime? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/datetime wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/range%}
+
+@defclass[wv-input/range% wv-element% ()]{
+
+Wrapper for a range input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a range-input wrapper.
+}
+
+@defmethod[(get) (or/c number? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/number wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/check%}
+
+@defclass[wv-input/check% wv-element% ()]{
+
+Wrapper for a checkbox input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a checkbox wrapper.
+}
+
+@defmethod[(get) (or/c boolean? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/boolean wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/radio%}
+
+@defclass[wv-input/radio% wv-element% ()]{
+
+Wrapper for a radio input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a radio-input wrapper.
+}
+
+@defmethod[(get) (or/c boolean? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/boolean wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}
+
+@section{Class: wv-input/color%}
+
+@defclass[wv-input/color% wv-element% ()]{
+
+Wrapper for a color input element.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates a color-input wrapper.
+}
+
+@defmethod[(get) (or/c rgba? #f)]{
+
+Returns the current value by delegating to:
+
+@racketblock[
+(webview-value/color wv element-id)
+]
+}
+
+@defmethod[(set! [v (or/c symbol? string? number? boolean?
+                          g:date? g:time? g:datetime? rgba?)])
+            any/c]{
+
+Writes @racket[v] by delegating to:
+
+@racketblock[
+(webview-set-value! wv element-id v)
+]
+}
+}