webview: webview/webview.h File Reference

webview 0.12.0 A tiny cross-platform webview library for C/C++ to build modern cross-platform GUIs.

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
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)
WEBVIEW_STRINGIFY
#define WEBVIEW_STRINGIFY(x)
Utility macro for stringifying a macro argument.
Definition webview.h:98

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)
WEBVIEW_VERSION_MINOR
#define WEBVIEW_VERSION_MINOR
The current library minor version.
Definition webview.h:74
WEBVIEW_VERSION_MAJOR
#define WEBVIEW_VERSION_MAJOR
The current library major version.
Definition webview.h:69
WEBVIEW_EXPAND_AND_STRINGIFY
#define WEBVIEW_EXPAND_AND_STRINGIFY(x)
Utility macro for stringifying the result of a macro argument expansion.
Definition webview.h:101
WEBVIEW_VERSION_PATCH
#define WEBVIEW_VERSION_PATCH
The current library patch version.
Definition webview.h:79

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=");
webview_navigate
WEBVIEW_API webview_error_t webview_navigate(webview_t w, const char *url)

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>");
webview_set_html
WEBVIEW_API webview_error_t webview_set_html(webview_t w, const char *html)

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