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