Types

Webview = pointer

Pointer to a webview instance. Source Edit

WebviewError = enum
  WebviewErrorMissingDependency = -5, ## Missing dependency.
  WebviewErrorCanceled = -4, ## Operation canceled.
  WebviewErrorInvalidState = -3, ## Invalid state detected.
  WebviewErrorInvalidArgument = -2, ## One or more invalid arguments have been specified e.g. in a function call.
  WebviewErrorUnspecified = -1, ## An unspecified error occurred. A more specific error code may be needed.
  WebviewErrorOk = 0, ## OK/Success. Functions that return error codes will typically return this
                       ## to signify successful operations.
  WebviewErrorDuplicate = 1, ## Signifies that something already exists.
  WebviewErrorNotFound = 2   ## Signifies that something does not exist.

Error codes returned to callers of the API.

The following codes are commonly used in the library:

WebviewErrorOk
WebviewErrorUnspecified
WebviewErrorInvalidArgument
WebviewErrorInvalidState

With the exception of WebviewErrorOk which is normally expected, the other common codes do not normally need to be handled specifically. Refer to specific functions regarding handling of other codes.

Source Edit

WebviewHint = enum
  WebviewHintNone,          ## Width and height are default size.
  WebviewHintMin,           ## Width and height are minimum bounds.
  WebviewHintMax,           ## Width and height are maximum bounds.
  WebviewHintFixed           ## Window size can not be changed by a user.

Window size hints Source Edit

WebviewNativeHandleKind = enum
  WebviewNativeHandleKindUiWindow, ## Top-level window. `GtkWindow` pointer (GTK), `NSWindow` pointer (Cocoa)
                                    ## or `HWND` (Win32).
  WebviewNativeHandleKindUiWidget, ## Browser widget. `GtkWidget` pointer (GTK), `NSView` pointer (Cocoa) or
                                    ## `HWND` (Win32).
  WebviewNativeHandleKindBrowserController ## Browser controller. `WebKitWebView` pointer (WebKitGTK), `WKWebView`
                                           ## pointer (Cocoa/WebKit) or `ICoreWebView2Controller` pointer
                                           ## (Win32/WebView2).

Native handle kind. The actual type depends on the backend. Source Edit

WebviewVersion {.bycopy.} = object
  major*, minor*, patch*: cuint

Holds the elements of a MAJOR.MINOR.PATCH version number. Source Edit

WebviewVersionInfo {.bycopy.} = object
  version*: WebviewVersion   ## The elements of the version number.
  versionNumber*: array[32, char] ## SemVer 2.0.0 version number in `MAJOR.MINOR.PATCH` format.
  preRelease*: array[48, char] ## SemVer 2.0.0 pre-release labels prefixed with "-" if specified, otherwise
                               ## an empty string.
  buildMetadata*: array[48, char] ## SemVer 2.0.0 build metadata prefixed with "+", otherwise an empty string.

Holds the library's version information. Source Edit

Consts

WEBVIEW_VERSION_BUILD_METADATA = "": SemVer 2.0.0 build metadata prefixed with "+". Source Edit
WEBVIEW_VERSION_MAJOR = 0: The current library major version. Source Edit
WEBVIEW_VERSION_MINOR = 11: The current library minor version. Source Edit
WEBVIEW_VERSION_NUMBER = "0.11.0": SemVer 2.0.0 version number in MAJOR.MINOR.PATCH format. Source Edit
WEBVIEW_VERSION_PATCH = 0: The current library patch version. Source Edit
WEBVIEW_VERSION_PRE_RELEASE = "": SemVer 2.0.0 pre-release labels prefixed with "-". Source Edit
weCanceled = WebviewErrorCanceled: Source Edit
weDuplicate = WebviewErrorDuplicate: Source Edit
weInvalidArgument = WebviewErrorInvalidArgument: Source Edit
weInvalidState = WebviewErrorInvalidState: Source Edit
weMissingDependency = WebviewErrorMissingDependency: Source Edit
weNotFound = WebviewErrorNotFound: Source Edit
weOk = WebviewErrorOk: Source Edit
weUnspecified = WebviewErrorUnspecified: Source Edit
whFixed = WebviewHintFixed: Source Edit
whMax = WebviewHintMax: Source Edit
whMin = WebviewHintMin: Source Edit
whNone = WebviewHintNone: Source Edit
wnhkController = WebviewNativeHandleKindBrowserController: Source Edit
wnhkUiWidget = WebviewNativeHandleKindUiWidget: Source Edit
wnhkUiWindow = WebviewNativeHandleKindUiWindow: Source Edit

Procs

proc `bind`(w: Webview; name: string; fn: proc (id: string; req: JsonNode): string): WebviewError {. inline, discardable, ...raises: [], tags: [], forbids: [].}: Alias of bindCallback() Source Edit
proc bindCallback(w: Webview; name: string; fn: proc (id: string; req: JsonNode): string): WebviewError {. discardable, ...raises: [], tags: [], forbids: [].}: Essentially a high-level version of webviewBind Source Edit
proc create(debug: cint = cint isDebug; window: pointer = nil): Webview {.cdecl, importc: "webview_create", discardable, ...raises: [], tags: [], forbids: [].}: Creates a new webview instance.
debug: Enable developer tools if supported by the backend.

window: Optional native window handle, i.e. GtkWindow pointer NSWindow pointer (Cocoa) or HWND (Win32). If non-nil, the webview widget is embedded into the given window, and the caller is expected to assume responsibility for the window as well as application lifecycle. If the window handle is nil, a new window is created and both the window and application lifecycle are managed by the webview instance.

Note: Win32: The function also accepts a pointer to HWND (Win32) in the window parameter for backward compatibility.

Note: Win32/WebView2: CoInitializeEx should be called with COINIT_APARTMENTTHREADED before attempting to call this function with an existing window. Omitting this step may cause WebView2 initialization to fail.

return: nil on failure. Creation can fail for various reasons such as when required runtime dependencies are missing or when window creation fails.

retval: WEBVIEW_ERROR_MISSING_DEPENDENCY May be returned if WebView2 is unavailable on Windows.

Source Edit
proc destroy(w: Webview): WebviewError {.cdecl, importc: "webview_destroy", discardable, ...raises: [], tags: [], forbids: [].}: Destroys a webview and closes the native window.
w: The webview instance.

Source Edit
proc dispatch(w: Webview; fn: proc (w: Webview; arg: pointer) {.cdecl.}; arg: pointer = nil): WebviewError {.cdecl, importc: "webview_dispatch", discardable, ...raises: [], tags: [], forbids: [].}: Schedules a function to be invoked on the thread with the run/event loop. Use this function e.g. to interact with the library or native handles.
w: The webview instance.

fn: The function to be invoked.

arg: An optional argument passed along to the callback function.

Source Edit
proc eval(w: Webview; js: cstring): WebviewError {.cdecl, importc: "webview_eval", discardable, ...raises: [], tags: [], forbids: [].}: Evaluates arbitrary JavaScript code.

Use bindings if you need to communicate the result of the evaluation.

w: The webview instance.

js: JS content.

Source Edit
proc getNativeHandle(w: Webview; kind: WebviewNativeHandleKind): pointer {. cdecl, importc: "webview_get_native_handle", discardable, ...raises: [], tags: [], forbids: [].}: Get a native handle of choice.
w: The webview instance.

kind: The kind of handle to retrieve.

return: The native handle or @c NULL.

Source Edit
proc getWindow(w: Webview): pointer {.cdecl, importc: "webview_get_window", discardable, ...raises: [], tags: [], forbids: [].}: Returns the native handle of the window associated with the webview instance. The handle can be a GtkWindow pointer (GTK), NSWindow pointer (Cocoa) or @c HWND (Win32).
w: The webview instance.

return: The handle of the native window.

Source Edit
proc html=(w: Webview; html: string): WebviewError {.inline, discardable, ...raises: [], tags: [], forbids: [].}: Setter alias for setHtml.
Example:

let w = newWebview() w.html = "<h1>Hello</h1>"
Source Edit
proc init(w: Webview; js: cstring): WebviewError {.cdecl, importc: "webview_init", discardable, ...raises: [], tags: [], forbids: [].}: Injects JavaScript code to be executed immediately upon loading a page. The code will be executed before window.onload.
w: The webview instance.

js: JS content.

Source Edit
proc navigate(w: Webview; url: cstring): WebviewError {.cdecl, importc: "webview_navigate", discardable, ...raises: [], tags: [], forbids: [].}: Navigates webview to the given URL. URL may be a properly encoded data URI.
w: The webview instance.

url: URL.

Example:

let w = newWebview() w.navigate("https://github.com/webview/webview") w.navigate("data:text/html,%3Ch1%3EHello%3C%2Fh1%3E") w.navigate("data:text/html;base64,PGgxPkhlbGxvPC9oMT4=")
Source Edit
proc newWebview(debug: bool = isDebug; window: pointer = nil): Webview {.inline, ...raises: [], tags: [], forbids: [].}: Alias of create() Source Edit
proc run(w: Webview): WebviewError {.cdecl, importc: "webview_run", discardable, ...raises: [], tags: [], forbids: [].}: Runs the main loop until it's terminated.
w: The webview instance.

Source Edit
proc setHtml(w: Webview; html: cstring): WebviewError {.cdecl, importc: "webview_set_html", discardable, ...raises: [], tags: [], forbids: [].}: Load HTML content into the webview.
w: The webview instance.

html: HTML content.

Example:

let w = newWebview() w.setHtml("<h1>Hello</h1>")
Source Edit
proc setSize(w: Webview; width: cint; height: cint; hints: WebviewHint = WEBVIEW_HINT_NONE): WebviewError {.cdecl, importc: "webview_set_size", discardable, ...raises: [], tags: [], forbids: [].}: Updates the size of the native window.
w: The webview instance.

width: New width.

height: New height.

hints: Size hints.

Source Edit
proc setSize(w: Webview; width: int; height: int; hints: WebviewHint = WebviewHintNone): WebviewError {.inline, discardable, ...raises: [], tags: [], forbids: [].}: Alias of setSize with int instead of cint Source Edit
proc setTitle(w: Webview; title: cstring): WebviewError {.cdecl, importc: "webview_set_title", discardable, ...raises: [], tags: [], forbids: [].}: Updates the title of the native window.
w: The webview instance.

title: The new title.

Source Edit
proc size=(w: Webview; size: tuple[width: int, height: int]): WebviewError {. inline, discardable, ...raises: [], tags: [], forbids: [].}: Setter alias for setSize(). hints default to WEBVIEW_HINT_NONE. Source Edit
proc terminate(w: Webview): WebviewError {.cdecl, importc: "webview_terminate", discardable, ...raises: [], tags: [], forbids: [].}: Stops the main loop. It is safe to call this function from another other background thread.
w: The webview instance.

Source Edit
proc title=(w: Webview; title: string): WebviewError {.inline, discardable, ...raises: [], tags: [], forbids: [].}: Setter alias for setTitle(). Source Edit
proc unbind(w: Webview; name: cstring): WebviewError {.cdecl, importc: "webview_unbind", discardable, ...raises: [], tags: [], forbids: [].}: Removes a binding created with webview_bind().
w: The webview instance.

name: Name of the binding.

retval: WEBVIEW_ERROR_NOT_FOUND No binding exists with the specified name.

Source Edit
proc version(): WebviewVersionInfo {.inline, ...deprecated: "Useless. use `webviewVersion()`_ instead", raises: [], tags: [], forbids: [].}: Deprecated: Useless. use `webviewVersion()`_ instead

Dereferenced version of webviewVersion().

Same as webviewVersion()[].
Source Edit
proc webviewBind(w: Webview; name: cstring; fn: proc (id: cstring; req: cstring; arg: pointer) {.cdecl.}; arg: pointer = nil): WebviewError {.cdecl, importc: "webview_bind", discardable, ...raises: [], tags: [], forbids: [].}: Binds a function pointer to a new global JavaScript function.

Internally, JS glue code is injected to create the JS function by the given name. The callback function is passed a request identifier, a request string and a user-provided argument. The request string is a JSON array of the arguments passed to the JS function.

w: The webview instance.

name: Name of the JS function.

fn: Callback function.

arg: User argument.

retval: WEBVIEW_ERROR_DUPLICATE A binding already exists with the specified name.

Source Edit
proc webviewReturn(w: Webview; seq: cstring; status: cint; result: cstring): WebviewError {. cdecl, importc: "webview_return", discardable, ...raises: [], tags: [], forbids: [].}: Responds to a binding call from the JS side.
w: The webview instance.

id: The identifier of the binding call. Pass along the value received in the binding handler (see webviewBind()).

status: A status of zero tells the JS side that the binding call was succesful; any other value indicates an error.

result: The result of the binding call to be returned to the JS side. This must either be a valid JSON value or an empty string for the primitive JS value undefined.

Source Edit
proc webviewVersion(): ptr WebviewVersionInfo {.cdecl, importc: "webview_version", discardable, ...raises: [], tags: [], forbids: [].}: Get the library's version information. Source Edit

return:	`nil` on failure. Creation can fail for various reasons such as when required runtime dependencies are missing or when window creation fails.
retval:	`WEBVIEW_ERROR_MISSING_DEPENDENCY` May be returned if WebView2 is unavailable on Windows.

w:	The webview instance.
fn:	The function to be invoked.
arg:	An optional argument passed along to the callback function.

w:	The webview instance.
kind:	The kind of handle to retrieve.
return:	The native handle or @c NULL.

w:	The webview instance.
return:	The handle of the native window.

w:	The webview instance.
width:	New width.
height:	New height.
hints:	Size hints.

w:	The webview instance.
name:	Name of the binding.
retval:	`WEBVIEW_ERROR_NOT_FOUND` No binding exists with the specified name.

w:	The webview instance.
name:	Name of the JS function.
fn:	Callback function.
arg:	User argument.
retval:	`WEBVIEW_ERROR_DUPLICATE` A binding already exists with the specified name.

w:	The webview instance.
id:	The identifier of the binding call. Pass along the value received in the binding handler (see webviewBind()).
status:	A status of zero tells the JS side that the binding call was succesful; any other value indicates an error.
result:	The result of the binding call to be returned to the JS side. This must either be a valid JSON value or an empty string for the primitive JS value `undefined`.

w:	The webview instance.
html:	HTML content.