///|
/// Native handle kind. The actual type depends on the backend.
pub(all) enum NativeHandleKind {
/// Top-level window. `GtkWindow` pointer (GTK), `NSWindow` pointer (Cocoa) or `HWND` (Win32).
Window = 0
/// Browser widget. `GtkWidget` pointer (GTK), `NSView` pointer (Cocoa) or `HWND` (Win32).
Widget = 1
/// Browser controller. Under the CEF backend this is a diagnostic CEF browser
/// host handle.
Browser = 2
} derive(Debug)
///|
/// Window size hints
pub(all) enum SizeHint {
/// Width and height are default size.
None = 0
/// Width and height are minimum bounds.
Min = 1
/// Width and height are maximum bounds.
Max = 2
/// Window size can not be changed by a user.
Fixed = 3
} derive(Debug)
///|
/// Returns the compiled browser backend id.
pub fn backend_id() -> String {
@ffi.from_cstr(webview_backend_id_ffi())
}
///|
/// Returns whether the compiled browser backend can create native windows.
///
/// On Windows, install CEF with `proton cef setup` and build the
/// CEF subprocess helper before creating native windows.
pub fn backend_available() -> Bool {
webview_backend_available_ffi()
}
///|
/// An instance of a webview window.
///
/// Example:
///
/// ```moonbit nocheck
/// let webview = @webview.Webview::new(debug=1)
/// webview.set_title("My Webview")
/// webview.set_size(800, 600, @webview.SizeHint::None)
/// webview.set_html("Hello, World!
")
/// webview.dispatch(fn() { webview.terminate() })
/// webview.run()
/// ```
struct Webview {
handle : Webview_t
bindings : Map[String, BindingHandle]
destroy_hooks : Map[String, () -> Unit]
mut destroyed : Bool
}
///|
/// Creates a new webview instance from a webview handle.
///
/// Parameters:
/// - `debug` - If set to 1, enables debugging mode which provides additional logging.
pub fn Webview::new(debug? : Int = 0) -> Webview {
let window : Int64 = 0
let webview = Webview::{
handle: webview_create(debug, window),
bindings: {},
destroy_hooks: {},
destroyed: false,
}
webview
}
///|
/// Destroys the webview and closes the window. It is safe to call this
/// function from another background thread.
pub fn Webview::destroy(self : Webview) -> Unit {
if self.destroyed {
return
}
self.destroyed = true
let hooks : Array[() -> Unit] = []
for _, hook in self.destroy_hooks {
hooks.push(hook)
}
self.destroy_hooks.clear()
for hook in hooks {
hook()
}
for name, binding in self.bindings {
let _ = webview_unbind(self.handle, @ffi.to_cstr(name), binding)
}
self.bindings.clear()
let _ = webview_destroy(self.handle)
}
///|
/// Schedules a function to be invoked on the thread with the run/event loop.
///
/// Since library functions generally do not have thread safety guarantees,
/// this function can be used to schedule code to execute on the main/GUI
/// thread and thereby make that execution safe in multi-threaded applications.
///
/// Parameters:
/// - `callback` - The function to be invoked.
/// - `arg` - An optional argument passed along to the callback function.
pub fn Webview::dispatch(self : Webview, callback : () -> Unit) -> Unit {
let _ = webview_dispatch(self.handle, fn(w, f) { f(w) }, callback)
}
///|
/// Stops the main event loop. It is safe to call this function from another
/// background thread.
pub fn Webview::terminate(self : Webview) -> Unit {
let _ = webview_terminate(self.handle)
}
///|
/// 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.
///
/// Parameters:
/// - `name` - The name of the JavaScript function to bind.
/// - `callback` - The function to be invoked when the JS function is called.
/// - `arg` - An optional user-provided argument passed to the callback function.
///
/// Returns:
/// - `WEBVIEW_ERROR_DUPLICATE` - A binding already exists with the specified name.
pub fn Webview::bind(
self : Webview,
name : String,
callback : (Bytes, Bytes) -> Unit,
) -> Unit {
let binding = webview_bind(
self.handle,
@ffi.to_cstr(name),
fn(raw_id, raw_req, f) {
let id = webview_copy_cstr(raw_id)
let req = webview_copy_cstr(raw_req)
f(id, req)
},
callback,
)
if !webview_binding_is_null(binding) {
self.bindings.set(name, binding)
}
}
///|
/// Removes a binding created with `webview.bind()`.
///
/// Parameters:
/// - `name` - The name of the JavaScript function to unbind.
///
/// Returns:
/// - `WEBVIEW_ERROR_NOT_FOUND` - No binding exists with the specified name.
pub fn Webview::unbind(self : Webview, name : String) -> Unit {
match self.bindings.get(name) {
Some(binding) => {
self.bindings.remove(name)
let _ = webview_unbind(self.handle, @ffi.to_cstr(name), binding)
}
None => ()
}
}
///|
/// Returns whether a JavaScript binding with this name has been installed.
/// Higher-level runtimes can use this to avoid rebinding helper functions under
/// the same global JavaScript name.
pub fn Webview::has_binding(self : Webview, name : String) -> Bool {
self.bindings.get(name) is Some(_)
}
///|
/// Updates the title of the native window.
///
/// Parameters:
/// - `title` - The new title.
pub fn Webview::set_title(self : Webview, title : String) -> Unit {
let _ = webview_set_title(self.handle, @ffi.to_cstr(title))
}
///|
/// Load HTML content into the webview.
///
/// Parameters:
/// - `html` - The HTML content to load.
///
/// Example:
/// ```moonbit nocheck
/// let webview = @webview.Webview::new()
/// webview.set_html("Hello, World!
")
/// webview.dispatch(fn() { webview.terminate() })
/// webview.run()
/// ```
pub fn Webview::set_html(self : Webview, html : String) -> Unit {
let _ = webview_set_html_script(
self.handle,
@ffi.to_cstr(webview_html_replacement_script(html)),
)
}
///|
/// Navigates webview to the given URL. URL may be a properly encoded data URI.
///
/// Parameters:
/// - `url` - The URL to navigate to.
///
/// Example:
/// ```moonbit nocheck
/// let webview = @webview.Webview::new()
/// webview.navigate("https://www.example.com")
/// webview.navigate("data:text/html,Hello, World!
")
/// webview.navigate("data:text/html;base64,PGgxPkhlbGxvPC9oMT4=")
/// webview.dispatch(fn() { webview.terminate() })
/// webview.run()
/// ```
pub fn Webview::navigate(self : Webview, url : String) -> Unit {
let _ = webview_navigate(self.handle, @ffi.to_cstr(url))
}
///|
/// Returns the native handle of the window associated with the webview instance.
/// The handle can be a `GtkWindow` pointer (GTK), `NSWindow` pointer (Cocoa)
/// or `HWND` (Win32).
pub fn Webview::get_window(self : Webview) -> Int64 {
webview_get_window(self.handle)
}
///|
/// Get a native handle of choice.
///
/// Parameters:
/// - `kind` - The kind of handle to retrieve.
pub fn Webview::get_native_handle(
self : Webview,
kind : NativeHandleKind,
) -> Int64 {
webview_get_native_handle(self.handle, kind)
}
///|
/// Returns a stable integer token for the native webview handle.
///
/// This is primarily intended for native runtime integrations that need to
/// refer back to the owning webview from C stubs.
pub fn Webview::runtime_handle_id(self : Webview) -> Int64 {
self.identity()
}
///|
/// Returns the internal webview handle of the webview instance. This handle is
/// the raw pointer used by the compiled native backend.
pub fn Webview::get_handle(self : Webview) -> Webview_t {
self.handle
}
///|
/// Evaluates arbitrary JavaScript code.
///
/// Use bindings if you need to communicate the result of the evaluation.
///
/// Parameters:
/// - `js` - The JavaScript code to evaluate.
pub fn Webview::eval(self : Webview, js : String) -> Unit {
let _ = webview_eval(self.handle, @ffi.to_cstr(js))
}
///|
/// Injects JavaScript code to be executed immediately upon loading a page.
/// The code will be executed before `window.onload`.
///
/// Parameters:
/// - `js` - The JavaScript code to inject.
pub fn Webview::init(self : Webview, js : String) -> Unit {
let _ = webview_init(self.handle, @ffi.to_cstr(js))
}
///|
/// Responds to a binding call from the JS side.
///
/// This function is safe to call from another thread.
///
/// Parameters:
/// - `id` - The identifier of the binding call. Pass along the value received
/// in the binding handler (see `webview.bind()`).
/// - `status` - A status of zero tells the JS side that the binding call was
/// successful; 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`.
pub fn Webview::response(
self : Webview,
id : String,
status : Int,
result : String,
) -> Unit {
let _ = webview_return(
self.handle,
@ffi.to_cstr(id),
status,
@ffi.to_cstr(result),
)
}
///|
/// Updates the size of the native window.
///
/// Remarks:
/// - Using `WEBVIEW_HINT_MAX` for setting the maximum window size is not
/// supported with GTK 4 because X11-specific functions such as
/// `gtk_window_set_geometry_hints` were removed. This option has no effect
/// when using GTK 4.
/// - GTK 4 can set a default/initial window size if done early enough;
/// otherwise, this function has no effect. GTK 4 (unlike 3) can't resize
/// a window after it has been set up.
///
/// Parameters:
/// - `width` - The new width of the window.
/// - `height` - The new height of the window.
/// - `hints` - Hints for the window size.
pub fn Webview::set_size(
self : Webview,
width : Int,
height : Int,
hints : SizeHint,
) -> Unit {
let _ = webview_set_size(self.handle, width, height, hints)
}
///|
/// Runs the main loop until it's terminated.
/// Once the loop exits, the webview destroys itself and executes registered
/// cleanup hooks.
pub fn Webview::run(self : Webview) -> Unit {
let _ = webview_run(self.handle)
self.destroy()
}
///|
/// Returns the stable identity token used to key runtime caches for this webview.
fn Webview::identity(self : Webview) -> Int64 {
webview_identity(self.handle)
}
///|
/// Registers a named callback that will run before the webview is destroyed.
///
/// Hook names must be unique within the webview so internal runtimes and
/// extensions can safely manage their own cleanup handlers.
pub fn Webview::register_destroy_hook(
self : Webview,
hook_name : String,
hook : () -> Unit,
) -> Unit {
guard self.destroy_hooks.get(hook_name) is None else {
abort(
"Webview::register_destroy_hook: hook already registered: " + hook_name,
)
}
self.destroy_hooks.set(hook_name, hook)
}
///|
/// Removes a previously registered destroy hook by name.
/// Missing hook names are ignored so independent runtimes can unregister
/// defensively during cleanup.
pub fn Webview::unregister_destroy_hook(
self : Webview,
hook_name : String,
) -> Unit {
self.destroy_hooks.remove(hook_name)
}