Documentation and some other stuff.

scrbl/wv-element.scrbl

@@ -0,0 +1,283 @@
+#lang scribble/manual
+
+@(require racket/base
+          racket/class
+          scribble/core
+          (for-label racket/base
+                     racket/string
+                     racket/class
+                     "../private/wv-window.rkt"
+                     "../private/racket-webview.rkt"))
+
+@title{wv-element}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defmodule[wv-element]
+
+DOM element wrapper used by the window layer.
+
+This module exports the @racket[wv-element%] class. Instances of this class
+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}
+
+A @racket[wv-element%] object is associated with:
+
+@itemlist[#:style 'compact
+ @item{one window}
+ @item{one DOM element identifier}]
+
+The class delegates DOM operations to the JavaScript-based API from
+@racketmodname[racket-webview]. The accepted argument shapes and result values
+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%}
+
+@defclass[wv-element% object% ()]{
+
+Represents one DOM element identified by its id.
+
+The class stores the owning window and the element id supplied at construction
+time. It also maintains an internal hash table mapping event symbols to
+callbacks.
+
+@defconstructor[([window (is-a?/c wv-window%)]
+                 [element-id symbol?])]{
+
+Creates an element wrapper.
+
+@racket[window] is the owning window object. @racket[element-id] is the DOM
+element identifier used in calls to the lower-level DOM manipulation functions.
+}
+
+@defmethod[(id) symbol?]{
+
+Returns the element id.
+}
+
+@defmethod[(add-event-callback! [evt symbol?] [cb procedure?]) void?]{
+
+Associates @racket[cb] with @racket[evt].
+
+If a callback was already stored for @racket[evt], it is replaced.
+}
+
+@defmethod[(remove-event-callback! [evt symbol?]) void?]{
+
+Removes the callback associated with @racket[evt], if any.
+}
+
+@defmethod[(event-callback-count) exact-integer?]{
+
+Returns the number of registered event callbacks.
+}
+
+@defmethod[(dispatch-event [evt symbol?] [data any/c])
+            (or/c 'wv-unhandled-js-event 'wv-handled-js-event)]{
+
+Dispatches an event to the callback registered for @racket[evt].
+
+If no callback is registered, the method returns
+@racket['wv-unhandled-js-event].
+
+If a callback is found, it is invoked as:
+
+@racketblock[
+(cb this evt data)
+]
+
+and the method returns @racket['wv-handled-js-event].
+}
+
+@defmethod[(set-innerHTML! [html (or/c string? xexpr?)])
+            (is-a?/c wv-element%)]{
+
+Sets the @tt{innerHTML} of this element using JavaScript and returns this
+element.
+
+The operation delegates to:
+
+@racketblock[
+(webview-set-innerHTML! wv element-id html)
+]
+}
+
+@defmethod[(add-class! [cl (or/c symbol? string? list?)]) any/c]{
+
+Adds one or more CSS classes to this element.
+
+The accepted values follow the contract of @racket[webview-add-class!]. The
+operation delegates to:
+
+@racketblock[
+(webview-add-class! wv element-id cl)
+]
+}
+
+@defmethod[(remove-class! [cl (or/c symbol? string? list?)]) any/c]{
+
+Removes one or more CSS classes from this element.
+
+The accepted values follow the contract of @racket[webview-remove-class!]. The
+operation delegates to:
+
+@racketblock[
+(webview-remove-class! wv element-id cl)
+]
+}
+
+@defmethod[(display [d (or/c symbol? string?)] ...) any/c]{
+
+Gets or sets the CSS @tt{display} property of this element.
+
+If no argument is supplied, the current value is returned by delegating to:
+
+@racketblock[
+(webview-get-style wv element-id 'display)
+]
+
+If an argument is supplied, only the first argument is used. The value may be a
+symbol or string and is converted internally before being passed to
+@racket[webview-set-style!].
+
+The resulting style value is then read back and returned.
+}
+
+@defmethod[(visibility [v (or/c symbol? string?)] ...) any/c]{
+
+Gets or sets the CSS @tt{visibility} property of this element.
+
+If no argument is supplied, the current value is returned by delegating to:
+
+@racketblock[
+(webview-get-style wv element-id 'visibility)
+]
+
+If an argument is supplied, only the first argument is used. The value may be a
+symbol or string and is converted internally before being passed to
+@racket[webview-set-style!].
+
+The resulting style value is then read back and returned.
+}
+
+@defmethod[(set-style! [styles (or/c kv? list-of-kv?)]) any/c]{
+
+Sets one or more inline style properties on this element.
+
+The accepted values follow the contract of @racket[webview-set-style!]. The
+method delegates to:
+
+@racketblock[
+(webview-set-style! wv element-id styles)
+]
+}
+
+@defmethod[(unset-style! [styles (or/c symbol? list-of-symbol?)]) any/c]{
+
+Clears one or more inline style properties on this element.
+
+The accepted values follow the contract of @racket[webview-unset-style!]. The
+method delegates to:
+
+@racketblock[
+(webview-unset-style! wv element-id styles)
+]
+}
+
+@defmethod[(set-attr! [attr-entries (or/c kv? list-of-kv?)]) any/c]{
+
+Sets one or more attributes on this element.
+
+The accepted values follow the contract of @racket[webview-set-attr!]. The
+method delegates to:
+
+@racketblock[
+(webview-set-attr! wv element-id attr-entries)
+]
+}
+
+@defmethod[(attr [attr (or/c symbol? string?)]) (or/c string? boolean?)]{
+
+Returns the value of the attribute identified by @racket[attr].
+
+The result follows the contract of @racket[webview-attr]. If the underlying
+JavaScript result is @tt{null}, the lower layer returns @racket[#f].
+
+The method delegates to:
+
+@racketblock[
+(webview-attr wv element-id attr)
+]
+}
+
+@defmethod[(attr/number [attr (or/c symbol? string?)]) (or/c number? #f)]{
+
+Returns the attribute value converted to a number.
+
+The method delegates to:
+
+@racketblock[
+(webview-attr/number wv element-id attr)
+]
+}
+
+@defmethod[(attr/symbol [attr (or/c symbol? string?)]) (or/c symbol? #f)]{
+
+Returns the attribute value converted to a symbol.
+
+The method delegates to:
+
+@racketblock[
+(webview-attr/symbol wv element-id attr)
+]
+}
+
+@defmethod[(attr/boolean [attr (or/c symbol? string?)]) (or/c boolean? #f)]{
+
+Returns the attribute value converted to a boolean.
+
+The method delegates to:
+
+@racketblock[
+(webview-attr/boolean wv element-id attr)
+]
+}
+
+@defmethod[(attr/date [attr (or/c symbol? string?)]) any/c]{
+
+Returns the attribute value converted to a date.
+
+The method delegates to:
+
+@racketblock[
+(webview-attr/date wv element-id attr)
+]
+}
+
+@defmethod[(attr/time [attr (or/c symbol? string?)]) any/c]{
+
+Returns the attribute value converted to a time.
+
+The method delegates to:
+
+@racketblock[
+(webview-attr/time wv element-id attr)
+]
+}
+
+@defmethod[(attr/datetime [attr (or/c symbol? string?)]) any/c]{
+
+Returns the attribute value converted to a datetime.
+
+The method delegates to:
+
+@racketblock[
+(webview-attr/datetime wv element-id attr)
+]
+}
+}