Home Original page

webview

Source   Edit

Wrapper for Webview.

Types

WebviewError = enum
  WebviewErrorMissingDependency = -5, 
  WebviewErrorCanceled = -4, 
  WebviewErrorInvalidState = -3, 
  WebviewErrorInvalidArgument = -2, 
  WebviewErrorUnspecified = -1, 
  WebviewErrorOk = 0, 
                       
  WebviewErrorDuplicate = 1, 
  WebviewErrorNotFound = 2

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,          
  WebviewHintMin,           
  WebviewHintMax,           
  WebviewHintFixed
Window size hints Source   Edit   
WebviewNativeHandleKind = enum
  WebviewNativeHandleKindUiWindow, 
                                    
  WebviewNativeHandleKindUiWidget, 
                                    
  WebviewNativeHandleKindBrowserController
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  

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 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 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