257 lines
10 KiB
Racket
257 lines
10 KiB
Racket
#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.
|
|
}
|