#lang scribble/manual

@(require scribble/racket
          scribble/example
          scribble/core
          (for-label racket/base
                     racket/class
                     racket/path
                     net/url
                     "../private/wv-context.rkt"
                     "../private/wv-settings.rkt"))

@defmodule[wv-window]

@title{Object-Oriented Interface: @racket[wv-window%]}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defclass[wv-window% object% ()]{

An OO wrapper around a single webview window.
A @racket[wv-window%] object owns one low-level window created with
@racket[webview-create], keeps a per-window settings view, and offers methods for
window management, DOM element access, event binding, file dialogs, and message boxes.

The class is designed so that subclasses can override event methods such as
@racket[moved], @racket[resized], @racket[page-loaded], @racket[js-event],
@racket[navigation-request], @racket[can-close?], and @racket[closed].

@defconstructor[([parent (or/c #f (is-a?/c wv-window%)) #f]
                 [wv-context (is-a?/c wv-context%) (if (eq? parent #f)
                                                      (error "wv context is mandatory")
                                                      (get-field wv-context parent))]
                 [html-path path-string? (error "html path is mandatory")]
                 [settings (is-a?/c wv-settings%)
                           (send wv-context settings
                                 (string->symbol (format "~a" html-path)))]
                 [title string? "Racket Webview Window"]
                 [width (or/c #f exact-integer?) #f]
                 [height (or/c #f exact-integer?) #f]
                 [x (or/c #f exact-integer?) #f]
                 [y (or/c #f exact-integer?) #f]
                 [wv any/c #f])]{
Creates a new window.

The @racket[wv-context] argument supplies the underlying webview context.
If @racket[parent] is given, the default value of @racket[wv-context] is taken from it.
The @racket[html-path] argument identifies the HTML resource to open.
The default @racket[settings] object is derived from @racket[wv-context] using
@racket[html-path] as per-window settings key.

The constructor creates the low-level window using @racket[webview-create] and then
calls @racket[init-size] to restore position and size from settings, falling back to
constructor arguments or internal defaults.
}

@defmethod*[([(context) (is-a?/c wv-context%)])]{
Returns the window context object associated with this window.
}

@defmethod*[([(win-context) symbol?])]{
Returns the symbolic context identifier derived from @racket[html-path].
This value is typically used as the settings section for the window.
}

@defmethod*[([(info) hash?])]{
Returns a hash table with administrative information about the window.
The hash contains entries for at least @racket['wv-context], @racket['wv],
@racket['html-path], and @racket['elements].
}

@defmethod*[([(element [id symbol?]) any/c]
             [(element [id symbol?] [type symbol?]) any/c])]{
Returns the wrapper object for the DOM element with identifier @racket[id].

If the element has not been wrapped before, a new wrapper object is created and cached.
When @racket[type] is omitted, the method attempts to determine the HTML input type via
JavaScript. Depending on the resolved type, it creates an instance of a more specific
wrapper class such as @racket[wv-input/text%], @racket[wv-input/date%],
@racket[wv-input/number%], or falls back to @racket[wv-element%].
}

@defmethod*[([(moved [x exact-integer?] [y exact-integer?]) void?])]{
Event hook called when the window has moved.
The default implementation stores the new position in the settings object.
Subclasses may override this method.
}

@defmethod*[([(resized [width exact-integer?] [height exact-integer?]) void?])]{
Event hook called when the window has been resized.
The default implementation stores the new size in the settings object.
Subclasses may override this method.
}

@defmethod*[([(window-state-changed [state any/c]) any/c])]{
Event hook called when the native window state changes, for example after show,
hide, or maximize notifications. The default implementation returns @racket[#t].
}

@defmethod*[([(page-loaded [ok? any/c]) any/c])]{
Event hook called after the page load completes. The argument indicates whether the
load succeeded. The default implementation returns @racket[#t].
}

@defmethod*[([(can-close?) any/c])]{
Event hook queried before closing the window.
If this method returns a true value, the default event handler closes the window.
The default implementation returns @racket[#t].
}

@defmethod*[([(closed) any/c])]{
Event hook called after the window has been closed.
The default implementation returns @racket[#t].
}

@defmethod*[([(js-event [js-event hash?]) any/c])]{
Handles a JavaScript-originated event.

The default implementation looks up the wrapped element referenced by the event and
forwards the event to that element's dispatcher. If no matching element is known,
it returns @racket['wv-unhandled-js-event]. Subclasses may override this for
application-specific dispatch.
}

@defmethod*[([(navigation-request [type symbol?] [url url?]) (or/c 'internal 'external)])]{
Handles a navigation request.

If the requested URL starts with the context base URL, the window navigates internally
using @racket[webview-set-url!] and returns @racket['internal]. Otherwise the URL is
opened externally using @racket[send-url] and the method returns @racket['external].
}

@defmethod*[([(add-class! [selector-or-id string?] [class string?]) this])]{
Adds the CSS class @racket[class] to the elements selected by @racket[selector-or-id].
Delegates to @racket[webview-add-class!].
}

@defmethod*[([(remove-class! [selector-or-id string?] [class string?]) this])]{
Removes the CSS class @racket[class] from the elements selected by @racket[selector-or-id].
Delegates to @racket[webview-remove-class!].
}

@defmethod*[([(devtools) this])]{
Opens or activates the developer tools for the underlying webview.
}

@defmethod*[([(move [x exact-integer?] [y exact-integer?]) this])]{
Moves the native window to the given screen coordinates.
}

@defmethod*[([(resize [width exact-integer?] [height exact-integer?]) this])]{
Resizes the native window to the given dimensions.
}

@defmethod*[([(close) this])]{
Closes the native window.
}

@defmethod*[([(bind! [selector string?]
                      [events (or/c symbol? (listof symbol?))]
                      [callback procedure?]) (listof any/c)])]{
Binds one or more DOM events to all elements matched by @racket[selector].

This method delegates the JavaScript side of the binding to @racket[webview-bind!],
creates or reuses wrapper objects for the matched elements, and installs
@racket[callback] as event callback on each wrapper. The return value is the list of
matched element wrapper objects.
}

@defmethod*[([(unbind! [selector string?]
                        [events (or/c symbol? (listof symbol?))]) any/c])]{
Removes previously installed bindings for the selected elements and events.
This method delegates to @racket[webview-unbind!] and removes callbacks from the
corresponding cached wrapper objects.
}

@defmethod*[([(file-dialog-done [flag symbol?]
                                 [file any/c]
                                 [dir any/c]
                                 [filter any/c]) void?])]{
Continuation hook used internally to resume a pending file or directory dialog.
Applications normally do not call this method directly.
}

@defmethod*[([(choose-dir [title string?] [base-dir (or/c #f path-string?)])
              (or/c 'showing path-string? #f)])]{
Shows a directory chooser.

If the chooser is successfully shown, the method initially returns @racket['showing]
and later resumes with the selected directory path or @racket[#f] when the dialog is
canceled. If the dialog cannot be shown, it returns @racket[#f].
Only one file or directory dialog can be active at a time.
}

@defmethod*[([(file-open [title string?]
                          [base-dir (or/c #f path-string?)]
                          [filters any/c])
              (or/c 'showing list? #f)])]{
Shows a file-open dialog.

If the dialog is accepted, the resumed result is a list whose contents are derived from
the low-level file dialog result. If the dialog is canceled or cannot be shown, the
result is @racket[#f]. Only one file or directory dialog can be active at a time.
}

@defmethod*[([(file-save [title string?]
                          [base-dir (or/c #f path-string?)]
                          [filters any/c])
              (or/c 'showing list? #f)])]{
Shows a file-save dialog.

If the dialog is accepted, the resumed result is a list whose contents are derived from
the low-level file dialog result. If the dialog is canceled or cannot be shown, the
result is @racket[#f]. Only one file or directory dialog can be active at a time.
}

@defmethod*[([(message-done [event symbol?]) void?])]{
Continuation hook used internally to resume a pending message box.
Applications normally do not call this method directly.
}

@defmethod*[([(message [type symbol?]
                        [title string?]
                        [message string?]
                        [#:sub submessage string? ""])
              (or/c 'showing symbol? #f)])]{
Shows a native message box.

If the message box is shown successfully, the method initially returns @racket['showing]
and later resumes with the button result, such as @racket['msgbox-ok],
@racket['msgbox-cancel], @racket['msgbox-yes], or @racket['msgbox-no].
If the message box cannot be shown, the method returns @racket[#f].
Only one message box can be active at a time.
}

@defmethod*[([(init-size) void?])]{
Initializes the window position and size from the settings object.
If no persisted values are available, constructor arguments or module defaults are used.
}

}

@defproc[(root-file-not-found-handler [standard-file path-string?]
                                      [not-found-handler procedure?])
         procedure?]{
Creates a file-resolution procedure that can be used as a fallback handler for a webview
context.

The returned procedure redirects requests for @tt{"/"} and, when needed,
@tt{"/index.html"} to @racket[standard-file]. For other missing files it either returns
the unresolved path unchanged or delegates to @racket[not-found-handler] when one is
supplied.
}

@defthing[webview-version any/c]{
The version identifier exported by the underlying webview binding.
}