Webview Go

https://github.com/webview/webview_go
Admin
A Go language binding for the webview library, enabling Go applications to create lightweight...
Tokens:21,381
Snippets:166
Trust Score:7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Download example program

Source: https://github.com/webview/webview_go/blob/master/README.md

Fetch the basic example main.go file from the repository.

```sh
curl -sSLo main.go "https://raw.githubusercontent.com/webview/webview_go/master/examples/basic/main.go"
```

--------------------------------

### Install dependencies

Source: https://github.com/webview/webview_go/blob/master/README.md

Install the webview_go package using go get.

```sh
go get github.com/webview/webview_go
```

--------------------------------

### SetTitle() basic example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Sets the window title to "Basic Example".

```go
w.SetTitle("Basic Example")
```

--------------------------------

### Error handling and teardown example with New(true)

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Guards the instance lifetime with defer Destroy. Calling Eval() or Dispatch() before Run() does not work because the instance is only configured and not yet started.

```Go
w := webview.New(true)
defer w.Destroy()
w.Init(`window.alert = (msg) => window.external.invoke('alert:' + msg)`)
w.SetHtml("<h1>Hello</h1>")
// Eval/ Dispatch must be used after Run() has started the main loop.
w.Run()
```

--------------------------------

### Init example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Injects a JavaScript event listener that logs a message on beforeunload.

```go
w.Init(`window.addEventListener('beforeunload', () => console.log('bye'))`)
```

--------------------------------

### Basic webview creation example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Creates a new webview with debug disabled, sets a title, size, and HTML, then runs the main loop. Adapted from examples/basic/main.go.

```Go
package main

import webview "github.com/webview/webview_go"

func main() {
	w := webview.New(false)
	defer w.Destroy()
	w.SetTitle("Basic Example")
	w.SetSize(480, 320, webview.HintNone)
	w.SetHtml("Thanks for using webview!")
	w.Run()
}
```

--------------------------------

### Run() basic example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Creates a webview, sets HTML content, and runs the main loop. The Run() call blocks until Terminate() is called or the window is closed.

```go
w := webview.New(false)
defer w.Destroy()
w.SetHtml("<h1>Hello</h1>")
w.Run() // blocks until Terminate() is called or the window is closed
```

--------------------------------

### NewWindow plain window example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Creates a new window and webview instance with no parent, equivalent to New(false).

```Go
w := webview.NewWindow(false, nil)
defer w.Destroy()
w.SetHtml("<h1>Hello</h1>")
w.Run()
```

--------------------------------

### Bind example: basic binding from examples/bind/main.go

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Example of binding a function that increments a counter and returns an IncrementResult. This is from examples/bind/main.go.

```go
w.Bind("increment", func() IncrementResult {
	count++
	return IncrementResult{Count: count}
})
```

--------------------------------

### SetHtml simple content example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Sets simple HTML content using SetHtml.

```go
w.SetHtml("Thanks for using webview!")
```

--------------------------------

### Import webview package

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/module-webview.md

Import the webview module using the package name. This is the standard import path shown in the basic and bind examples.

```go
import webview "github.com/webview/webview_go"
```

--------------------------------

### Destroy() defer-based teardown example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Idiomatic defer-based teardown used by examples/basic/main.go. Defers Destroy() so it runs when the function exits, sets HTML content, then runs the webview.

```go
w := webview.New(false)
defer w.Destroy()
w.SetHtml("Thanks for using webview!")
w.Run()
```

--------------------------------

### Destroy() deterministic teardown example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Deterministic teardown: creates a webview, runs it, then destroys it explicitly after Run() exits.

```go
w := webview.New(false)
w.Run()
w.Destroy()
```

--------------------------------

### Bind example: validation and error propagation

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Example showing validation failure when binding a non-function, and error propagation when the bound function returns an error. The error is delivered to JavaScript as a rejection.

```go
// f is not a function -> Bind returns an error immediately
if err := w.Bind("broken", 42); err != nil {
	log.Println("bind failed:", err)
}

// f returning (value, error); the error is delivered to JavaScript as a rejection
w.Bind("div", func(a, b int) (int, error) {
	if b == 0 {
		return 0, errors.New("division by zero")
	}
	return a / b, nil
})
```

--------------------------------

### Window() retrieve handle example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Retrieves the native window handle for native tweaks. The pointer can be passed to Cgo glue for native calls not exposed by the binding.

```go
ptr := w.Window()
// ptr can be handed to Cgo glue for native calls that the binding does not expose
```

--------------------------------

### Eval example: change background color

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Example of using Eval to set the document body background color to lightblue.

```go
w.Eval(`document.body.style.background = 'lightblue'`)
```

--------------------------------

### Eval example: fire-and-forget from a binding

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Example of using Eval inside a binding callback to change the document body opacity. The evaluation is fire-and-forget.

```go
w.Bind("flash", func() { w.Eval(`document.body.style.opacity = '0.5'`) })
```

--------------------------------

### Unbind usage example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Shows usage of Unbind to remove a binding. After calling w.Unbind("temp"), the JavaScript global window.temp is removed.

```go
w.Bind("temp", func() string { return "hi" })
// ...
w.Unbind("temp") // window.temp is removed
```

--------------------------------

### JavaScript endpoint invocation for WebView.Bind()

Source: https://github.com/webview/webview_go/blob/master/_autodocs/endpoints.md

Installed by the C glue when a name is bound via WebView.Bind(). Each call increments RPC.nextSeq, stores resolve/reject callbacks, and sends a JSON request with id, method, and params over window.external.invoke. The returned promise resolves or rejects based on the native response.

```javascript
window[name] = function() {
  var seq = RPC.nextSeq++;
  var promise = new Promise(function(resolve, reject) {
    RPC[seq] = { resolve: resolve, reject: reject };
  });
  window.external.invoke(JSON.stringify({
    id: seq,
    method: name,
    params: Array.prototype.slice.call(arguments),
  }));
  return promise;
}
```

--------------------------------

### Create project directory

Source: https://github.com/webview/webview_go/blob/master/README.md

Initialize a new directory for your webview_go project.

```sh
mkdir my-project && cd my-project
```

--------------------------------

### Initialize Go module

Source: https://github.com/webview/webview_go/blob/master/README.md

Create a new Go module for the project.

```sh
go mod init example.com/app
```

--------------------------------

### New

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Creates a new window and webview instance with optional debug mode.

```APIDOC
## New

### Description
Creates a new window and a new webview instance. If debug is non-zero, developer tools will be enabled if the platform supports them.

### Method
Function

### Signature
`func New(debug bool) WebView`

### Parameters
- **debug** (bool) - Required - When `true`, developer tools (e.g. the WebKit/WebView2 inspector) are enabled if the platform backend supports them.

### Return Type
`WebView` - The newly created webview instance, with a fresh native window owned and managed by the webview.

### Behavior
Delegates entirely to `NewWindow(debug, nil)`: a new (non-embedded) window is created and both the window and application lifecycle are managed by the webview instance.

### Source
`webview.go:147` (delegates to `webview.go:155`).

### Example
```go
package main

import webview "github.com/webview/webview_go"

func main() {
	w := webview.New(false)
	defer w.Destroy()
	w.SetTitle("Basic Example")
	w.SetSize(480, 320, webview.HintNone)
	w.SetHtml("Thanks for using webview!")
	w.Run()
}
```

### Notes
- The factory itself does not throw; the only recovery path is to guard the instance lifetime.
- Calling `Eval()` or `Dispatch()` before `Run()` does not work because the instance has only been configured and not yet started.
```

--------------------------------

### Build the application

Source: https://github.com/webview/webview_go/blob/master/README.md

Compile the Go application. On Windows, use -ldflags="-H windowsgui" to prevent a console window from appearing.

```sh
go build
```

--------------------------------

### SetTitle() runtime binding example

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Updates the title at runtime from a binding. Binds the function to the name "setWindowTitle" so it can be called from JavaScript.

```go
w.Bind("setWindowTitle", func(title string) {
	w.SetTitle(title)
})
```

--------------------------------

### SetSize with min, max, and fixed hints

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Sets minimum, maximum, and fixed size constraints for the window. The comments indicate that HintMin prevents shrinking below 400x300, HintMax prevents growing beyond 800x600, and HintFixed disables user resizing.

```go
w.SetSize(400, 300, webview.HintMin) // window cannot shrink below this
w.SetSize(800, 600, webview.HintMax) // window cannot grow beyond this
w.SetSize(480, 320, webview.HintFixed) // user cannot resize
```

--------------------------------

### Init combined with page load

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Injects initialization code and then navigates to a data URL, demonstrating that the init code runs before the page loads.

```go
w.Init(`window.__loaded = true;`)
w.Navigate("data:text/html,<h1>hi</h1>")
```

--------------------------------

### SetSize with HintNone

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Sets the window to a fixed default size of 480x320 pixels with the HintNone hint, which uses the default sizing behavior.

```go
w.SetSize(480, 320, webview.HintNone)
```

--------------------------------

### New function signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Calls NewWindow to create a new window and webview instance. Developer tools are enabled if debug is non-zero and the platform supports them.

```Go
// New calls NewWindow to create a new window and a new webview instance. If debug
// is non-zero - developer tools will be enabled (if the platform supports them).
func New(debug bool) WebView { return NewWindow(debug, nil) }
```

--------------------------------

### SetHtml and Init Methods

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Documentation for the SetHtml and Init methods of the webview interface, which allow setting HTML content and injecting JavaScript initialization code.

```APIDOC
## SetHtml(html string)

### Description
Sets the webview HTML directly. The string is converted with `C.CString(html)` and freed after the call. Implements `C.webview_set_html(w.w, s)` (`webview.h:294`).

### Method
SetHtml

### Endpoint
SetHtml(html string)

### Parameters
#### Path Parameters
- **html** (string) - Required - HTML content to load.

### Request Example
```go
w.SetHtml("Thanks for using webview!")
```

### Response
#### Success Response
- **nothing** - No return value.

#### Response Example
No response body.

---

## Init(js string)

### Description
Injects JavaScript code at the initialization of the new page. Every time the webview opens a new page, this initialization code will be executed; it is guaranteed to execute before `window.onload`. The string is converted with `C.CString(js)` and freed after the call. Implements `C.webview_init(w.w, s)` (`webview.h:303`).

### Method
Init

### Endpoint
Init(js string)

### Parameters
#### Path Parameters
- **js** (string) - Required - JavaScript source to inject.

### Request Example
```go
w.Init(`window.addEventListener('beforeunload', () => console.log('bye'))`)
```

### Response
#### Success Response
- **nothing** - No return value.

#### Response Example
No response body.
```

--------------------------------

### NewWindow

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Creates a new webview instance, optionally embedding into an existing native window.

```APIDOC
## NewWindow

### Description
Creates a new webview instance. If debug is non-zero, developer tools are enabled if the platform supports them. The window parameter can be a pointer to the native window handle. If it's non-null, then a child WebView is embedded into the given parent window. Otherwise a new window is created.

### Method
Function

### Signature
`func NewWindow(debug bool, window unsafe.Pointer) WebView`

### Parameters
- **debug** (bool) - Required - When `true`, developer tools are enabled if the platform backend supports them.
- **window** (unsafe.Pointer) - Required - Native window handle to embed into. Per the C header `webview_create` accepts a `GtkWindow` pointer (GTK), `NSWindow` pointer (Cocoa), or `HWND` (Win32). Pass `nil` to create and own a new window.

### Return Type
`WebView` - A webview configured for the given parent window.

### Behavior
Allocates `&webview{}` and stores the result of `C.webview_create(boolToInt(debug), window)`. Per the vendored C header (`libs/webview/include/webview.h:193`), `webview_create` returns `NULL` on failure (e.g. missing runtime dependencies or window creation failure); the binding stores the value without checking for `NULL`. The C header also notes that on Win32/WebView2, `CoInitializeEx` with `COINIT_APARTMENTTHREADED` should be called before embedding into an existing window.

### Source
`webview.go:155`.

### Example - Embedding into an existing native window
```go
// windowHandle is a GtkWindow / NSWindow / HWND pointer obtained elsewhere
// (e.g. from an existing event loop).
w := webview.NewWindow(false, windowHandle)
defer w.Destroy()
w.Navigate("https://github.com/webview/webview")
w.Run() // the caller is expected to manage the parent window's lifecycle
```

### Example - Plain window (equivalent to `New(false)`)
```go
w := webview.NewWindow(false, nil)
defer w.Destroy()
w.SetHtml("<h1>Hello</h1>")
w.Run()
```
```

--------------------------------

### Module initializer with runtime.LockOSThread

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/module-webview.md

Pins the calling thread to the OS main thread, which is required by the GUI backends. The runtime calls init() automatically.

```go
func init() {
	// Ensure that main.main is called from the main thread
	runtime.LockOSThread()
}
```

--------------------------------

### Run() method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

The method signature for Run(), which runs the main loop until terminated. After it exits, the webview must be destroyed.

```go
Run()
```

--------------------------------

### Init method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

The method signature for Init, which takes a JavaScript string to inject at page initialization.

```go
Init(js string)
```

--------------------------------

### Imports for webview.go

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/module-webview.md

Imports the vendored webview libraries with the underscore qualifier and standard-library packages used by the implementation. The underscore form instructs the package manager to use the locally vendored copies.

```go
import "C"
import (
	_ "github.com/webview/webview_go/libs/mswebview2"
	_ "github.com/webview/webview_go/libs/mswebview2/include"
	_ "github.com/webview/webview_go/libs/webview"
	_ "github.com/webview/webview_go/libs/webview/include"
	"encoding/json"
	"errors"
	"reflect"
	"runtime"
	"sync"
	"unsafe"
)
```

--------------------------------

### SetSize(w int, h int, hint Hint)

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Sets the size of the webview window. The width and height parameters are interpreted according to the provided size hint, which can be none, fixed, minimum, or maximum.

```APIDOC
## SetSize(w int, h int, hint Hint)

### Description
Updates the native window size; the meaning of width and height depends on the provided size hint.

### Method
SetSize

### Signature
SetSize(w int, h int, hint Hint)

### Parameters
- **w** (int) - Required - New width in pixels (interpreted per `hint`).
- **h** (int) - Required - New height in pixels (interpreted per `hint`).
- **hint** (Hint) - Required - Size hint: `HintNone`, `HintFixed`, `HintMin`, or `HintMax`.

### Returns
nothing.

### Example
```go
w.SetSize(480, 320, webview.HintNone)
```

### Example — minimum and maximum bounds
```go
w.SetSize(400, 300, webview.HintMin) // window cannot shrink below this
w.SetSize(800, 600, webview.HintMax) // window cannot grow beyond this
w.SetSize(480, 320, webview.HintFixed) // user cannot resize
```
```

--------------------------------

### NewWindow function signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/functions.md

Creates a new webview instance. If debug is non-zero, developer tools are enabled. Window can be a native handle pointer for embedding or nil for a new window.

```Go
// NewWindow 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.
func NewWindow(debug bool, window unsafe.Pointer) WebView {
	w := &webview{}
	w.w = C.webview_create(boolToInt(debug), window)
	return w
}
```

--------------------------------

### Run() lifecycle with termination

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Binds a 'quit' function to Terminate() and sets HTML with a button that calls it. Run() exits when the button is clicked.

```go
w := webview.New(false)
defer w.Destroy()
w.Bind("quit", func() { w.Terminate() })
w.SetHtml(`<button onclick="quit()">Close</button>`)
w.Run() // exits when the button is clicked
```

--------------------------------

### WebView interface definition

Source: https://github.com/webview/webview_go/blob/master/_autodocs/types.md

Defines the WebView interface with 13 methods. This is the public instance interface returned by New and NewWindow.

```go
type WebView interface {
	Run()
	Terminate()
	Dispatch(f func())
	Destroy()
	Window() unsafe.Pointer
	SetTitle(title string)
	SetSize(w int, h int, hint Hint)
	Navigate(url string)
	SetHtml(html string)
	Init(js string)
	Eval(js string)
	Bind(name string, f interface{}) error
	Unbind(name string) error
}
```

--------------------------------

### Run()

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Runs the main loop until it is terminated. After this function exits, you must destroy the webview.

```APIDOC
## Run()

### Description
Runs the main loop until it is terminated. After this function exits, you must destroy the webview.

### Method
Run

### Parameters
None.

### Returns
Nothing.

### Example
```go
w := webview.New(false)
defer w.Destroy()
w.SetHtml("<h1>Hello</h1>")
w.Run() // blocks until Terminate() is called or the window is closed
```

### Example — lifecycle with termination
```go
w := webview.New(false)
defer w.Destroy()
w.Bind("quit", func() { w.Terminate() })
w.SetHtml(`<button onclick="quit()">Close</button>`)
w.Run() // exits when the button is clicked
```
```

--------------------------------

### CGo preamble for platform-specific build flags

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/module-webview.md

CGo preamble configuring platform-specific compilation flags and linker options for the webview binding. It sets the include paths, defines platform macros (WEBVIEW_GTK, WEBVIEW_COCOA, WEBVIEW_EDGE), and links required libraries (GTK, WebKit, Windows system libs). This is the only configuration the module has.

```c
#cgo CFLAGS: -I${SRCDIR}/libs/webview/include
#cgo CXXFLAGS: -I${SRCDIR}/libs/webview/include -DWEBVIEW_STATIC

#cgo linux openbsd freebsd netbsd CXXFLAGS: -DWEBVIEW_GTK -std=c++11
#cgo linux openbsd freebsd netbsd LDFLAGS: -ldl
#cgo linux openbsd freebsd netbsd pkg-config: gtk+-3.0 webkit2gtk-4.0

#cgo darwin CXXFLAGS: -DWEBVIEW_COCOA -std=c++11
#cgo darwin LDFLAGS: -framework WebKit -ldl

#cgo windows CXXFLAGS: -DWEBVIEW_EDGE -std=c++14 -I${SRCDIR}/libs/mswebview2/include
#cgo windows LDFLAGS: -static -ladvapi32 -lole32 -lshell32 -lshlwapi -luser32 -lversion
```

--------------------------------

### Eval and Bind methods

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Documentation for the Eval and Bind methods of the webview Go interface.

```APIDOC
## `Eval(js string)`

### Description
Evaluates arbitrary JavaScript code in the webview. The evaluation happens asynchronously and the result is ignored.

### Method
N/A (Go method)

### Endpoint
N/A (Go method)

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **js** (string) - Required - JavaScript expression to evaluate.

### Request Example
```go
w.Eval(`document.body.style.background = 'lightblue'`)
```

### Response
#### Success Response (200)
No return value.

#### Response Example
No response body.

### Error Handling
No errors are returned. Evaluation happens asynchronously; use RPC bindings for notifications about results.

---

## `Bind(name string, f interface{}) error`

### Description
Binds a callback function so that it appears under the given name as a global JavaScript function. The callback receives a JSON array of arguments passed to the JavaScript function.

### Method
N/A (Go method)

### Endpoint
N/A (Go method)

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **name** (string) - Required - Name under which the callback appears as a global JavaScript function (`window[name]`).
- **f** (interface{}) - Required - Value that must be a function. It must return either a value, a value plus an error, just an error, or nothing.

### Request Example
```go
w.Bind("increment", func() IncrementResult {
	count++
	return IncrementResult{Count: count}
})
```

### Response
#### Success Response (200)
- **error** (error) - `nil` on success; an `error` value on validation failure.

#### Response Example
```go
if err := w.Bind("broken", 42); err != nil {
	log.Println("bind failed:", err)
}
```

### Error Handling
Returns an error if `f` is not a function or if its signature has more than two out-parameters. Errors are delivered to JavaScript as promise rejections.

---
```

--------------------------------

### Window() method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Returns the native window handle as an unsafe.Pointer: a GtkWindow pointer with the GTK backend, an NSWindow pointer with the Cocoa backend, or an HWND with the Win32 backend. Implements C.webview_get_window(w.w) (webview.h:236).

```go
Window() unsafe.Pointer
```

--------------------------------

### SetSize method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Declares the SetSize method on the webview interface. Use it to update the native window size, where the meaning of width and height depends on the provided hint.

```go
SetSize(w int, h int, hint Hint)
```

--------------------------------

### Navigate from a binding

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Binds a Go function named "openPage" that takes a URL string and calls Navigate on it, enabling navigation from JavaScript.

```go
w.Bind("openPage", func(url string) { w.Navigate(url) })
```

--------------------------------

### SetHtml multi-line document with bound functions

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Binds a function and sets a multi-line HTML document with a button that calls the bound function.

```go
w.Bind("increment", func() uint { return count })
w.SetHtml(`<!doctype html>
<html>
	<body><button id="b" onclick="increment().then(r => { ... })">+1</button></body>
</html>`)
w.Run()
```

--------------------------------

### Dispatch(f func())

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Posts a function to be executed on the main thread. You normally do not need to call this, unless you want to tweak the native window (which requires the UI thread).

```APIDOC
## Dispatch(f func())

### Description
Posts a function to be executed on the main thread. You normally do not need to call this, unless you want to tweak the native window (which requires the UI thread). The closure is stored in the module-level `dispatch` map under the next free integer `index` and the index is handed to the C glue (`CgoWebViewDispatch`, `glue.c:23` → `webview_dispatch`, `webview.h:226`). When the UI thread runs it, `_webviewDispatchGoCallback` (`webview.go:221`) removes the closure from the map and calls it. Like `Eval()`, this does not work before `Run()`.

### Method
Dispatch

### Signature
```go
Dispatch(f func())
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| f | func() | required | — | Zero-argument, no-return closure to post for execution on the main thread. |

### Returns
Nothing.

### Example — safely touching the native window from another thread:
```go
w.Dispatch(func() {
	ptr := w.Window() // must run on the UI thread
	// pass ptr to native Cgo code that adjusts the native window
})
```

### Example — ordering multiple dispatches:
```go
w.Dispatch(func() { w.SetTitle("first") })
w.Dispatch(func() { w.SetTitle("second") })
```

```

--------------------------------

### Bind Go functions and observe RPC results in JavaScript

Source: https://github.com/webview/webview_go/blob/master/_autodocs/endpoints.md

Binds two Go functions to JavaScript and sets HTML that calls them. The 'sum' function returns a value, while 'fail' returns an error, demonstrating how errors are delivered as rejected promises. The JavaScript comments show expected outputs: 'sum' logs 3 and 'fail' logs 'boom'.

```go
w.Bind("sum", func(a, b int) int {
	return a + b
})
w.Bind("fail", func() (string, error) {
	return "", errors.New("boom")
})
w.SetHtml(`
<script>
  sum(1, 2).then(r => console.log('sum', r));      // -> 3
  fail().catch(e => console.log('rejected', e));    // -> "boom"
</script>
`)

```

--------------------------------

### Bind internals (webview.go:251-324) and binding callback

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/struct-webview.md

Bind validates the callable via reflection, builds a wrapper closure that unmarshals JSON arguments and calls the function, and registers it in the bindings map. The callback _webviewBindingGoCallback runs the wrapper and answers with C.webview_return; status 0 resolves the promise, status -1 rejects it.

```go
func (w *webview) Bind(name string, f interface{}) error {
	v := reflect.ValueOf(f)
	// f must be a function
	if v.Kind() != reflect.Func {
		return errors.New("only functions can be bound")
	}
	// f must return either value and error or just error
	if n := v.Type().NumOut(); n > 2 {
		return errors.New("function may only return a value or a value+error")
	}
	...
```

```go
	binding := func(id, req string) (interface{}, error) {
		raw := []json.RawMessage{}
		if err := json.Unmarshal([]byte(req), &raw); err != nil {
			return nil, err
		}
		isVariadic := v.Type().IsVariadic()
		numIn := v.Type().NumIn()
		if (isVariadic && len(raw) < numIn-1) || (!isVariadic && len(raw) != numIn) {
			return nil, errors.New("function arguments mismatch")
		}
		args := []reflect.Value{}
		for i := range raw {
			var arg reflect.Value
			if isVariadic && i >= numIn-1 {
				arg = reflect.New(v.Type().In(numIn - 1).Elem())
			} else {
				arg = reflect.New(v.Type().In(i))
			}
			if err := json.Unmarshal(raw[i], arg.Interface()); err != nil {
				return nil, err
			}
			args = append(args, arg.Elem())
		}
		errorType := reflect.TypeOf((*error)(nil)).Elem()
		res := v.Call(args)
		switch len(res) {
		case 0:
			return nil, nil
		case 1:
			if res[0].Type().Implements(errorType) {
				if res[0].Interface() != nil {
					return nil, res[0].Interface().(error)
				}
				return nil, nil
			}
			return res[0].Interface(), nil
		case 2:
			if !res[1].Type().Implements(errorType) {
				return nil, errors.New("second return value must be an error")
			}
			if res[1].Interface() == nil {
				return res[0].Interface(), nil
			}
			return res[0].Interface(), res[1].Interface().(error)
		default:
			return nil, errors.New("unexpected number of return values")
		}
	}

	m.Lock()
	for ; bindings[index] != nil; index++ {
	}
	bindings[index] = binding
	m.Unlock()
	cname := C.CString(name)
	defer C.free(unsafe.Pointer(cname))
	C.CgoWebViewBind(w.w, cname, C.uintptr_t(index))
	return nil
```

```go
func _webviewBindingGoCallback(w C.webview_t, id *C.char, req *C.char, index uintptr) {
	m.Lock()
	f := bindings[uintptr(index)]
	m.Unlock()
	jsString := func(v interface{}) string { b, _ := json.Marshal(v); return string(b) }
	status, result := 0, ""
	if res, err := f(C.GoString(id), C.GoString(req)); err != nil {
		status = -1
		result = jsString(err.Error())
	} else if b, err := json.Marshal(res); err != nil {
		status = -1
		result = jsString(err.Error())
	} else {
		status = 0
		result = string(b)
	}
	s := C.CString(result)
	defer C.free(unsafe.Pointer(s))
	C.webview_return(w, id, C.int(status), s)
}
```

--------------------------------

### Ordering multiple Dispatch() calls

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Dispatch two closures in sequence, setting the window title to 'first' then 'second'.

```go
w.Dispatch(func() { w.SetTitle("first") })
w.Dispatch(func() { w.SetTitle("second") })
```

--------------------------------

### Navigate method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Declares the Navigate method on the webview interface. Use it to navigate the webview to a given URL, which may be a properly encoded data: URI.

```go
Navigate(url string)
```

--------------------------------

### Navigate to remote and data URIs

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Navigates to a remote URL and to data URIs, both percent-encoded and base64-encoded, as documented in the source comment.

```go
w.Navigate("https://github.com/webview/webview")
w.Navigate("data:text/html,%3Ch1%3EHello%3C%2Fh1%3E")
w.Navigate("data:text/html;base64,PGgxPkhlbGxvPC9oMT4=")
```

--------------------------------

### Using Dispatch() to touch the native window from another thread

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Dispatch a closure that retrieves the window pointer on the UI thread, for passing to native Cgo code that adjusts the window.

```go
w.Dispatch(func() {
	ptr := w.Window() // must run on the UI thread
	// pass ptr to native Cgo code that adjusts the native window
})
```

--------------------------------

### Bind method signature with documentation comment

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Signature of the Bind method with its documentation comment. It binds a callback function to a global JavaScript function. The callback receives a JSON array of arguments. f must be a function and can return value and error or just error.

```go
// Bind binds a callback function 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.
//
// f must be a function
// f must return either value and error or just error
Bind(name string, f interface{}) error
```

--------------------------------

### Window()

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Returns the native window handle as an unsafe.Pointer, allowing access to the underlying platform-specific window object.

```APIDOC
## Window()

### Description
Returns the native window handle: a `GtkWindow` pointer with the GTK backend, an `NSWindow` pointer with the Cocoa backend, or an `HWND` with the Win32 backend. Implements `C.webview_get_window(w.w)` (`webview.h:236`).

### Method
Window

### Signature
`Window() unsafe.Pointer`

### Parameters
None.

### Returns
- `unsafe.Pointer` — the native window handle.

### Source
Interface `webview.go:62-125`; implementation `webview.go:173`.

### Example — retrieve handle for native tweaks:
```go
ptr := w.Window()
// ptr can be handed to Cgo glue for native calls that the binding does not expose
```
```

--------------------------------

### Binding quit to Terminate()

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Binds a 'quit' callback that calls w.Terminate(), using the w.Bind method.

```go
w.Bind("quit", func() { w.Terminate() })
```

--------------------------------

### Dispatch() method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Declares the Dispatch method that accepts a zero-argument function for execution on the main thread.

```go
Dispatch(f func())
```

--------------------------------

### C callback forwarding binding invocation to Go

Source: https://github.com/webview/webview_go/blob/master/_autodocs/endpoints.md

C glue callback that forwards the binding invocation to Go. It extracts the binding context from the argument and calls the Go callback with the sequence id, raw request string, and context index.

```c
static void _webview_binding_cb(const char *id, const char *req, void *arg) {
    struct binding_context *ctx = (struct binding_context *) arg;
    _webviewBindingGoCallback(ctx->w, (char *)id, (char *)req, ctx->index);
}
```

--------------------------------

### Destroy() method signature

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Destroys a webview and closes the native window. Implements C.webview_destroy(w.w) (webview.h:200). Per the factory documentation, the instance must be destroyed after Run() exits.

```go
Destroy()
```

--------------------------------

### Dispatch internals (webview.go:211-219) and callback

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/struct-webview.md

Dispatch stores a closure in the dispatch map under the next free index and passes only the integer index to C. The C glue registers _webview_dispatch_cb; when it fires on the main thread, _webviewDispatchGoCallback retrieves and runs the closure.

```go
func (w *webview) Dispatch(f func()) {
	m.Lock()
	for ; dispatch[index] != nil; index++ {
	}
	dispatch[index] = f
	m.Unlock()
	C.CgoWebViewDispatch(w.w, C.uintptr_t(index))
}
```

```go
func _webviewDispatchGoCallback(index unsafe.Pointer) {
	m.Lock()
	f := dispatch[uintptr(index)]
	delete(dispatch, uintptr(index))
	m.Unlock()
	f()
}
```

--------------------------------

### Navigate(url string)

Source: https://github.com/webview/webview_go/blob/master/_autodocs/api-reference/interface-webview.md

Navigates the webview to the specified URL. The URL can be a remote address or a data URI, and the method can be called from a binding.

```APIDOC
## Navigate(url string)

### Description
Navigates the webview to the given URL. The URL may be a remote URL or a properly encoded data URI.

### Method
Navigate

### Signature
Navigate(url string)

### Parameters
- **url** (string) - Required - URL to navigate to; may be a properly encoded `data:` URI.

### Returns
nothing.

### Example — remote and data URIs
```go
w.Navigate("https://github.com/webview/webview")
w.Navigate("data:text/html,%3Ch1%3EHello%3C%2Fh1%3E")
w.Navigate("data:text/html;base64,PGgxPkhlbGxvPC9oMT4=")
```

### Example — navigation from a binding
```go
w.Bind("openPage", func(url string) { w.Navigate(url) })
```
```
Tokens:
Raw