Skip to main content

webview

LuaJIT bindings for the embedded webview library

Foreign Function Interface
This is a low-level module; misuse can easily crash the runtime!

Status​

External: Functionality is provided by a third-party library, which may or may not give semantic versioning guarantees

Availability​

This module is preloaded. You can simply require it:

local webview = require("webview")

Fields​

cdefs​

A string representing the C type definitions that were used to load the FFI bindings. Do not attempt to ffi.load them manually.

bindings​

A pointer to the statically-loaded exports table that exposes the bound functions to Lua. For more details, see this note.

Functions​

initialize​

Initializes the bindings by loading the C type definitions. Automatically called by the runtime when it sets up the Lua environment.

version​

Returns the embedded webview library version as a Lua string.

Mostly equivalent to bindings.version(), but the latter returns a cdata object that may include additional versioning information.

Native Bindings​

All C functions listed here can be accessed via webview.bindings and must be called with the appropriate cdata values.

bind​

// Binds a native C callback so that it will appear under the given name as a
// global JavaScript function. Internally it uses webview_init(). Callback
// receives a request string and a user-provided argument pointer. Request
// string is a JSON array of all the arguments passed to the JavaScript
// function.
WEBVIEW_API void webview_bind(webview_t w, const char *name,
                              void (*fn)(const char *seq, const char *req,
                                         void *arg),
                              void *arg);

create​

// Creates a new webview instance. If debug is non-zero - developer tools will
// be enabled (if the platform supports them). Window parameter can be a
// pointer to the native window handle. If it's non-null - then child WebView
// is embedded into the given parent window. Otherwise a new window is created.
// Depending on the platform, a GtkWindow, NSWindow or HWND pointer can be
// passed here. Returns null on failure. Creation can fail for various reasons
// such as when required runtime dependencies are missing or when window creation
// fails.

WEBVIEW_API webview_t webview_create(int debug, void *window);

destroy​

// Destroys a webview and closes the native window.
WEBVIEW_API void webview_destroy(webview_t w);

dispatch​

// Posts a function to be executed on the main thread. You normally do not need
// to call this function, unless you want to tweak the native window.
WEBVIEW_API void
webview_dispatch(webview_t w, void (*fn)(webview_t w, void *arg), void *arg);

eval​

// Evaluates arbitrary JavaScript code. Evaluation happens asynchronously, also
// the result of the expression is ignored. Use RPC bindings if you want to
// receive notifications about the results of the evaluation.
WEBVIEW_API void webview_eval(webview_t w, const char *js);

get_window​

// Returns a native window handle pointer. When using GTK backend the pointer
// is GtkWindow pointer, when using Cocoa backend the pointer is NSWindow
// pointer, when using Win32 backend the pointer is HWND pointer.
WEBVIEW_API void *webview_get_window(webview_t w);

init​

// Injects JavaScript code at the initialization of the new page. Every time
// the webview will open a the new page - this initialization code will be
// executed. It is guaranteed that code is executed before window.onload.
WEBVIEW_API void webview_init(webview_t w, const char *js);
// Navigates webview to the given URL. URL may be a properly encoded data URI.
// Examples:
// webview_navigate(w, "https://github.com/webview/webview");
// webview_navigate(w, "data:text/html,%3Ch1%3EHello%3C%2Fh1%3E");
// webview_navigate(w, "data:text/html;base64,PGgxPkhlbGxvPC9oMT4=");
WEBVIEW_API void webview_navigate(webview_t w, const char *url);

return​

// Allows to return a value from the native binding. Original request pointer
// must be provided to help internal RPC engine match requests with responses.
// If status is zero - result is expected to be a valid JSON result value.
// If status is not zero - result is an error JSON object.
WEBVIEW_API void webview_return(webview_t w, const char *seq, int status,
                                const char *result);

run​

This function completely blocks the event loop and should not be used if you need to perform other asynchronous tasks.

// Runs the main loop until it's terminated. After this function exits - you
// must destroy the webview.
WEBVIEW_API void webview_run(webview_t w);

run_once​

Runs a single iteration of the WebView's update loop. Used to integrate with the event loop, i.e., by polling for updates.

You can turn it into a blocking call with the second argument, but it's better to just use run instead if you need that.

int webview_run_once(webview_t w, int blocking);

set_html​

// Set webview HTML directly.
// Example: webview_set_html(w, "<h1>Hello</h1>");
WEBVIEW_API void webview_set_html(webview_t w, const char *html);

set_icon​

Sets the WebView window's application icon, which is displayed in the title bar (or in the dock/Finder on Mac OS).

The icon is loaded using platform-specific APIs. This will briefly block the event loop. In case of success the call returns true.

Importantly, you must respect the OS-specific icon format for each platform or loading will certainly fail:

  • On Windows, icons are expected to be in ico format
  • On Mac OS, you should create an icns catalog/file using Apple's tools
  • On Linux, GTK APIs are used - they luckily support several common image formats (such as PNG or JPEG)

Needless to say, the image file you submit has to actually exist on disk. Failure to load (or set) the icon results in a false return value.

bool webview_set_icon(webview_t w, const char* file_path);

set_size​

// Window size hints
#define WEBVIEW_HINT_NONE 0  // Width and height are default size
#define WEBVIEW_HINT_MIN 1   // Width and height are minimum bounds
#define WEBVIEW_HINT_MAX 2   // Width and height are maximum bounds
#define WEBVIEW_HINT_FIXED 3 // Window size can not be changed by a user
// Updates native window size. See WEBVIEW_HINT constants.
WEBVIEW_API void webview_set_size(webview_t w, int width, int height,
                                  int hints);

set_title​

// Updates the title of the native window. Must be called from the UI thread.
WEBVIEW_API void webview_set_title(webview_t w, const char *title);

terminate​

// Stops the main loop. It is safe to call this function from another other
// background thread.
WEBVIEW_API void webview_terminate(webview_t w);

toggle_fullscreen​

Toggles fullscreen mode for the native browser window, switching between windowed and fullscreen mode whenever called.

The monitor to be used depends on the platform: It should default to the one that holds the window, but this may not work in WSL.

void webview_toggle_fullscreen(webview_t w);

unbind​

// Removes a native C callback that was previously set by webview_bind.
WEBVIEW_API void webview_unbind(webview_t w, const char *name);

version​

// Get the library's version information.
WEBVIEW_API const webview_version_info_t *webview_version();

Changelog​

VersionWhat happened?
v0.0.1Initial release