#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)
]
}
}