webview.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	webview_version_t
	Holds the elements of a MAJOR.MINOR.PATCH version number. More...
struct	webview_version_info_t
	Holds the library's version information. More...

Macros
#define	WEBVIEW_API   extern
Version
#define	WEBVIEW_VERSION_MAJOR   0
	The current library major version.
#define	WEBVIEW_VERSION_MINOR   12
	The current library minor version.
#define	WEBVIEW_VERSION_PATCH   0
	The current library patch version.
#define	WEBVIEW_VERSION_PRE_RELEASE   ""
	SemVer 2.0.0 pre-release labels prefixed with "-".
#define	WEBVIEW_VERSION_BUILD_METADATA   ""
	SemVer 2.0.0 build metadata prefixed with "+".
#define	WEBVIEW_VERSION_NUMBER
	SemVer 2.0.0 version number in MAJOR.MINOR.PATCH format.
Used internally
#define	WEBVIEW_STRINGIFY(x)
	Utility macro for stringifying a macro argument.
#define	WEBVIEW_EXPAND_AND_STRINGIFY(x)
	Utility macro for stringifying the result of a macro argument expansion.

Typedefs
typedef void *	webview_t
	Pointer to a webview instance.

Enumerations
enum	webview_native_handle_kind_t { WEBVIEW_NATIVE_HANDLE_KIND_UI_WINDOW , WEBVIEW_NATIVE_HANDLE_KIND_UI_WIDGET , WEBVIEW_NATIVE_HANDLE_KIND_BROWSER_CONTROLLER }
	Native handle kind. The actual type depends on the backend. More...
enum	webview_hint_t { WEBVIEW_HINT_NONE , WEBVIEW_HINT_MIN , WEBVIEW_HINT_MAX , WEBVIEW_HINT_FIXED }
	Window size hints. More...

Functions
WEBVIEW_API webview_t	webview_create (int debug, void *window)
WEBVIEW_API webview_error_t	webview_destroy (webview_t w)
WEBVIEW_API webview_error_t	webview_run (webview_t w)
WEBVIEW_API webview_error_t	webview_terminate (webview_t w)
WEBVIEW_API webview_error_t	webview_dispatch (webview_t w, void(*fn)(webview_t w, void *arg), void *arg)
WEBVIEW_API void *	webview_get_window (webview_t w)
WEBVIEW_API void *	webview_get_native_handle (webview_t w, webview_native_handle_kind_t kind)
WEBVIEW_API webview_error_t	webview_set_title (webview_t w, const char *title)
WEBVIEW_API webview_error_t	webview_set_size (webview_t w, int width, int height, webview_hint_t hints)
WEBVIEW_API webview_error_t	webview_navigate (webview_t w, const char *url)
WEBVIEW_API webview_error_t	webview_set_html (webview_t w, const char *html)
WEBVIEW_API webview_error_t	webview_init (webview_t w, const char *js)
WEBVIEW_API webview_error_t	webview_eval (webview_t w, const char *js)
WEBVIEW_API webview_error_t	webview_bind (webview_t w, const char *name, void(*fn)(const char *id, const char *req, void *arg), void *arg)
WEBVIEW_API webview_error_t	webview_unbind (webview_t w, const char *name)
WEBVIEW_API webview_error_t	webview_return (webview_t w, const char *id, int status, const char *result)
WEBVIEW_API const webview_version_info_t *	webview_version (void)

Errors
#define	WEBVIEW_SUCCEEDED(error)
	Evaluates to TRUE for error codes indicating success or additional information.
#define	WEBVIEW_FAILED(error)
	Evaluates to TRUE if the given error code indicates failure.
enum	webview_error_t {   WEBVIEW_ERROR_MISSING_DEPENDENCY = -5 , WEBVIEW_ERROR_CANCELED = -4 , WEBVIEW_ERROR_INVALID_STATE = -3 , WEBVIEW_ERROR_INVALID_ARGUMENT = -2 ,   WEBVIEW_ERROR_UNSPECIFIED = -1 , WEBVIEW_ERROR_OK = 0 , WEBVIEW_ERROR_DUPLICATE = 1 , WEBVIEW_ERROR_NOT_FOUND = 2 }
	Error codes returned to callers of the API. More...

Macro Definition Documentation

WEBVIEW_API

#define WEBVIEW_API   extern

Used to specify function linkage such as extern, inline, etc.

When WEBVIEW_API is not already defined, the defaults are as follows:

• inline when compiling C++ code.
• extern when compiling C code.

The following macros can be used to automatically set an appropriate value for WEBVIEW_API:

• Define WEBVIEW_BUILD_SHARED when building a shared library.
• Define WEBVIEW_SHARED when using a shared library.
• Define WEBVIEW_STATIC when building or using a static library.

WEBVIEW_EXPAND_AND_STRINGIFY

#define WEBVIEW_EXPAND_AND_STRINGIFY

(

x

)

Value:

WEBVIEW_STRINGIFY(x)

Utility macro for stringifying the result of a macro argument expansion.

WEBVIEW_FAILED

#define WEBVIEW_FAILED

(

error

)

Value:

((int)(error) < 0)

Evaluates to TRUE if the given error code indicates failure.

WEBVIEW_STRINGIFY

#define WEBVIEW_STRINGIFY

(

x

)

Value:

#x

Utility macro for stringifying a macro argument.

WEBVIEW_SUCCEEDED

#define WEBVIEW_SUCCEEDED

(

error

)

Value:

((int)(error) >= 0)

Evaluates to TRUE for error codes indicating success or additional information.

WEBVIEW_VERSION_BUILD_METADATA

#define WEBVIEW_VERSION_BUILD_METADATA   ""

SemVer 2.0.0 build metadata prefixed with "+".

WEBVIEW_VERSION_MAJOR

#define WEBVIEW_VERSION_MAJOR   0

The current library major version.

WEBVIEW_VERSION_MINOR

#define WEBVIEW_VERSION_MINOR   12

The current library minor version.

WEBVIEW_VERSION_NUMBER

#define WEBVIEW_VERSION_NUMBER

Value:

WEBVIEW_EXPAND_AND_STRINGIFY(WEBVIEW_VERSION_MAJOR)                          \
"." WEBVIEW_EXPAND_AND_STRINGIFY(                                            \
    WEBVIEW_VERSION_MINOR) "." WEBVIEW_EXPAND_AND_STRINGIFY(WEBVIEW_VERSION_PATCH)

SemVer 2.0.0 version number in MAJOR.MINOR.PATCH format.

WEBVIEW_VERSION_PATCH

#define WEBVIEW_VERSION_PATCH   0

The current library patch version.

WEBVIEW_VERSION_PRE_RELEASE

#define WEBVIEW_VERSION_PRE_RELEASE   ""

SemVer 2.0.0 pre-release labels prefixed with "-".

Typedef Documentation

webview_t

typedef void* webview_t

Pointer to a webview instance.

Enumeration Type Documentation

webview_error_t

enum webview_error_t

Error codes returned to callers of the API.

The following codes are commonly used in the library:

• WEBVIEW_ERROR_OK
• WEBVIEW_ERROR_UNSPECIFIED
• WEBVIEW_ERROR_INVALID_ARGUMENT
• WEBVIEW_ERROR_INVALID_STATE

With the exception of WEBVIEW_ERROR_OK 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.

Enumerator
WEBVIEW_ERROR_MISSING_DEPENDENCY	Missing dependency.
WEBVIEW_ERROR_CANCELED	Operation canceled.
WEBVIEW_ERROR_INVALID_STATE	Invalid state detected.
WEBVIEW_ERROR_INVALID_ARGUMENT	One or more invalid arguments have been specified e.g. in a function call.
WEBVIEW_ERROR_UNSPECIFIED	An unspecified error occurred. A more specific error code may be needed.
WEBVIEW_ERROR_OK	OK/Success. Functions that return error codes will typically return this to signify successful operations.
WEBVIEW_ERROR_DUPLICATE	Signifies that something already exists.
WEBVIEW_ERROR_NOT_FOUND	Signifies that something does not exist.

webview_hint_t

enum webview_hint_t

Window size hints.

Enumerator
WEBVIEW_HINT_NONE	Width and height are default size.
WEBVIEW_HINT_MIN	Width and height are minimum bounds.
WEBVIEW_HINT_MAX	Width and height are maximum bounds.
WEBVIEW_HINT_FIXED	Window size can not be changed by a user.

webview_native_handle_kind_t

enum webview_native_handle_kind_t

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

Enumerator
WEBVIEW_NATIVE_HANDLE_KIND_UI_WINDOW	Top-level window. GtkWindow pointer (GTK), NSWindow pointer (Cocoa) or HWND (Win32).
WEBVIEW_NATIVE_HANDLE_KIND_UI_WIDGET	Browser widget. GtkWidget pointer (GTK), NSView pointer (Cocoa) or HWND (Win32).
WEBVIEW_NATIVE_HANDLE_KIND_BROWSER_CONTROLLER	Browser controller. WebKitWebView pointer (WebKitGTK), WKWebView pointer (Cocoa/WebKit) or ICoreWebView2Controller pointer (Win32/WebView2).

Function Documentation

webview_bind()

WEBVIEW_API webview_error_t webview_bind	(	webview_t	w,
		const char *	name,
		void(*	fn )(const char *id, const char *req, void *arg),
		void *	arg )

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

w	The webview instance.
name	Name of the JS function.
fn	Callback function.
arg	User argument.

Return values

WEBVIEW_ERROR_DUPLICATE

A binding already exists with the specified name.

webview_create()

WEBVIEW_API webview_t webview_create	(	int	debug,
		void *	window )

Creates a new webview instance.

Parameters

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-null, 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 null, a new window is created and both the window and application lifecycle are managed by the webview instance.

Remarks

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

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.

Returns

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

Return values

WEBVIEW_ERROR_MISSING_DEPENDENCY

May be returned if WebView2 is unavailable on Windows.

webview_destroy()

WEBVIEW_API webview_error_t webview_destroy

(

webview_t

w

)

Destroys a webview instance and closes the native window.

Parameters

w	The webview instance.

webview_dispatch()

WEBVIEW_API webview_error_t webview_dispatch	(	webview_t	w,
		void(*	fn )(webview_t w, void *arg),
		void *	arg )

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.

Parameters

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

webview_eval()

WEBVIEW_API webview_error_t webview_eval	(	webview_t	w,
		const char *	js )

Evaluates arbitrary JavaScript code.

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

Parameters

w	The webview instance.
js	JS content.

webview_get_native_handle()

WEBVIEW_API void * webview_get_native_handle	(	webview_t	w,
		webview_native_handle_kind_t	kind )

Get a native handle of choice.

Parameters

w	The webview instance.
kind	The kind of handle to retrieve.

Returns

The native handle or NULL.

Since

0.11

webview_get_window()

WEBVIEW_API void * webview_get_window

(

webview_t

w

)

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

Parameters

w	The webview instance.

Returns

The handle of the native window.

webview_init()

WEBVIEW_API webview_error_t webview_init	(	webview_t	w,
		const char *	js )

Injects JavaScript code to be executed immediately upon loading a page. The code will be executed before window.onload.

Parameters

w	The webview instance.
js	JS content.

webview_navigate()

WEBVIEW_API webview_error_t webview_navigate	(	webview_t	w,
		const char *	url )

Navigates webview to the given URL. URL may be a properly encoded data URI.

Example:

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=");

Parameters

w	The webview instance.
url	URL.

webview_return()

WEBVIEW_API webview_error_t webview_return	(	webview_t	w,
		const char *	id,
		int	status,
		const char *	result )

Responds to a binding call from the JS side.

Parameters

w	The webview instance.
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 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.

webview_run()

WEBVIEW_API webview_error_t webview_run

(

webview_t

w

)

Runs the main loop until it's terminated.

Parameters

w	The webview instance.

webview_set_html()

WEBVIEW_API webview_error_t webview_set_html	(	webview_t	w,
		const char *	html )

Load HTML content into the webview.

Example:

webview_set_html(w, "<h1>Hello</h1>");

Parameters

w	The webview instance.
html	HTML content.

webview_set_size()

WEBVIEW_API webview_error_t webview_set_size	(	webview_t	w,
		int	width,
		int	height,
		webview_hint_t	hints )

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.

Parameters

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

webview_set_title()

WEBVIEW_API webview_error_t webview_set_title	(	webview_t	w,
		const char *	title )

Updates the title of the native window.

Parameters

w	The webview instance.
title	The new title.

webview_terminate()

WEBVIEW_API webview_error_t webview_terminate

(

webview_t

w

)

Stops the main loop. It is safe to call this function from another other background thread.

Parameters

w	The webview instance.

webview_unbind()

WEBVIEW_API webview_error_t webview_unbind	(	webview_t	w,
		const char *	name )

Removes a binding created with webview_bind().

Parameters

w	The webview instance.
name	Name of the binding.

Return values

WEBVIEW_ERROR_NOT_FOUND

No binding exists with the specified name.

webview_version()

WEBVIEW_API const webview_version_info_t * webview_version

(

void

)

Get the library's version information.

Since

0.10