webview

README

webview

A tiny cross-platform webview library for C/C++/Golang to build modern cross-platform GUIs. Also, there are Rust bindings, Python bindings, Nim bindings, Haskell, C# bindings and Java bindings available.

The goal of the project is to create a common HTML5 UI abstraction layer for the most widely used platforms.

It supports two-way JavaScript bindings (to call JavaScript from C/C++/Go and to call C/C++/Go from JavaScript).

It uses Cocoa/WebKit on macOS, gtk-webkit2 on Linux and Edge on Windows 10.

Webview for Go developers

If you are interested in writing Webview apps in C/C++, skip to the next section.

Getting started

Install Webview library with go get:

$ go get github.com/zserge/webview

Import the package and start using it:

package main

import "github.com/zserge/webview"

func main() {
	debug := true
	w := webview.New(debug)
	defer w.Destroy()
	w.SetTitle("Minimal webview example")
	w.SetSize(800, 600, webview.HintNone)
	w.Navigate("https://en.m.wikipedia.org/wiki/Main_Page")
	w.Run()
}

To build the app use the following commands:

# Linux
$ go build -o webview-example && ./webview-example

# MacOS uses app bundles for GUI apps
$ mkdir -p example.app/Contents/MacOS
$ go build -o example.app/Contents/MacOS/example
$ open example.app # Or click on the app in Finder

# Windows requires special linker flags for GUI apps.
# It's also recommended to use TDM-GCC-64 compiler for CGo.
# http://tdm-gcc.tdragon.net/download
$ go build -ldflags="-H windowsgui" -o webview-example.exe

For more details see godoc.

Distributing webview apps

On Linux you get a standalone executable. It will depend on GTK3 and GtkWebkit2, so if you distribute your app in DEB or RPM format include those dependencies. An application icon can be specified by providing a .desktop file.

On MacOS you are likely to ship an app bundle. Make the following directory structure and just zip it:

example.app
└── Contents
    ├── Info.plist
    ├── MacOS
    |   └── example
    └── Resources
        └── example.icns

Here, Info.plist is a property list file and *.icns is a special icon format. You may convert PNG to icns online.

On Windows you probably would like to have a custom icon for your executable. It can be done by providing a resource file, compiling it and linking with it. Typically, windres utility is used to compile resources. Also, on Windows, webview.dll and WebView2Loader.dll must be placed into the same directory with your app executable.

Also, if you want to cross-compile your webview app - use xgo.

Migrating from v0.1.1 to v0.10.0

1. webview.Open() has been removed. Use other webview APIs to create a window, open a link and run main UI loop.
2. webview.Debug() and webview.Debugf() have been removed. Use your favorite logging library to debug webview apps.
3. webview.Settings struct has been removed. Title, URL and size are controlled via other API setters and can be updated at any time, not only when webview is created.
4. Webview.Loop() has been removed. Use Run() instead.
5. WebView.Run(), WebView.Terminate(), WebView.SetTitle(), WebView.Dispatch() stayed the same.
6. WebView.Exit() has been renamed to WebView.Destroy()
7. WebView.SetColor() and WebView.SetFullScreen() have been removed. Use Window() to get native window handle and probably write some Cgo code to adjust native window to your taste.
8. webview.Dialog has been removed. But it is likely to be brought back as a standalone module.
9. WebView.Eval() remained the same.
10. WebView.InjectCSS() has been removed. Use eval to inject style tag with CSS inside.
11. WebView.Bind() kept the name, but changed the semantics. Only functions can be bound. Not the structs, like in Lorca.

Webview for C/C++ developers

Download webview.h and include it in your C/C++ code:

C++:

// main.c
#include "webview.h"
#ifdef WIN32
int WINAPI WinMain(HINSTANCE hInt, HINSTANCE hPrevInst, LPSTR lpCmdLine,
                   int nCmdShow) {
#else
int main() {
#endif
  webview::webview w(true, nullptr);
  w.set_title("Minimal example");
  w.set_size(480, 320, WEBVIEW_HINT_NONE);
  w.navigate("https://en.m.wikipedia.org/wiki/Main_Page");
  w.run();
  w.destroy();
  return 0;
}

Build it:

# Linux
$ c++ main.cc `pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.0` -o webview-example
# MacOS
$ c++ main.cc -std=c++11 -framework WebKit -o webview-example
# Windows (x64)
$ c++ main.cc -mwindows -L./dll/x64 -lwebview -lWebView2Loader -o webview-example.exe

C:

// webview.c
#include "webview.h"
#ifdef WIN32
int WINAPI WinMain(HINSTANCE hInt, HINSTANCE hPrevInst, LPSTR lpCmdLine,
                   int nCmdShow) {
#else
int main() {
#endif
	webview_t w = webview_create(0, NULL);
	webview_set_title(w, "Webview Example");
	webview_set_size(w, 480, 320, WEBVIEW_HINT_NONE);
	webview_navigate(w, "https://en.m.wikipedia.org/wiki/Main_Page");
	webview_run(w);
	webview_destroy(w);
	return 0;
}

Build it:

# Linux
$ g++ main.c `pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.0` -o webview-example
# MacOS
$ g++ main.c -std=c++11 -framework WebKit -o webview-example
# Windows (x64)
$ g++ main.c -mwindows -L./dll/x64 -lwebview -lWebView2Loader -o webview-example.exe

On Windows it is possible to use webview library directly when compiling with cl.exe, but WebView2Loader.dll is still required. To use MinGW you may dynamically link prebuilt webview.dll (this approach is used in Cgo bindings).

Full C/C++ API is described at the top of the webview.h file.

Migrating from v0.1.1 to v0.10.0

1. Use opaque webview_t type instead of struct webview. Size, title and URL are controlled via API setter functions. Invoke callback has been replaced with webview_bind() and webview_return() to make native function bindings inter-operate with JS.
2. If you have been using simplified webview() API to only open a single URL in a webview window - this function has been removed. You now have to create a new webview instance, configure and run it explicitly.
3. webview_init() is replaced by webview_create() which creates a new webview instance.
4. webview_exit() has been replaced with more meaningful webview_destroy().
5. Main UI loop with webview_loop() inside has been replaced with webview_run() runs infinitely until the webview window is closed.
6. webview_terminate() remains the same.
7. webview_dispatch() remains the same.
8. webview_set_title() remains the same.
9. webview_set_color() has been removed. Use webview_get_window and native window APIs to control colors, trancparency and other native window properties. At some point these APIs might be brought back.
10. webview_set_fullscreen() has been removed, see above.
11. webview_dialog() has been removed. But I'd like to see it added back as a separate independent module or library.
12. webview_eval() remains the same.
13. webview_inject_css() has been removed. Use webview_eval() to create style tag manually.
14. webview_debug() has been removed. Use whatever fits best to your programming language and environment to debug your GUI apps.

Notes

Execution on OpenBSD requires wxallowed mount(8) option. For Ubuntu Users run sudo apt install webkit2gtk-4.0(Try with webkit2gtk-4.0-dev if webkit2gtk-4.0 is not found) to install webkit2gtk-4.0 related items. FreeBSD is also supported, to install webkit2 run pkg install webkit2-gtk3.

License

Code is distributed under MIT license, feel free to use it in your proprietary projects as well.

Documentation

Overview

Example

w := New(true)
defer w.Destroy()
w.SetTitle("Hello")
w.Bind("noop", func() string {
	log.Println("hello")
	return "hello"
})
w.Bind("add", func(a, b int) int {
	return a + b
})
w.Bind("quit", func() {
	w.Terminate()
})
w.Navigate(`data:text/html,
		<!doctype html>
		<html>
			<body>hello</body>
			<script>
				window.onload = function() {
					document.body.innerText = ` + "`hello, ${navigator.userAgent}`" + `;
					noop().then(function(res) {
						console.log('noop res', res);
						add(1, 2).then(function(res) {
							console.log('add res', res);
							quit();
						});
					});
				};
			</script>
		</html>
	)`)
w.Run()

Index

• Constants
• type Hint
• type WebView
  • func New(debug bool) WebView
  • func NewWindow(debug bool, window unsafe.Pointer) WebView

Examples

• Package

Constants

const (
	// Width and height are default size
	HintNone = C.WEBVIEW_HINT_NONE

	// Window size can not be changed by a user
	HintFixed = C.WEBVIEW_HINT_FIXED

	// Width and height are minimum bounds
	HintMin = C.WEBVIEW_HINT_MIN

	// Width and height are maximum bounds
	HintMax = C.WEBVIEW_HINT_MAX
)

Types

type Hint

type Hint int

Hints are used to configure window sizing and resizing

type WebView

type WebView interface {

	// Run runs the main loop until it's terminated. After this function exits -
	// you must destroy the webview.
	Run()

	// Terminate stops the main loop. It is safe to call this function from
	// a background thread.
	Terminate()

	// 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.
	Dispatch(f func())

	// Destroy destroys a webview and closes the native window.
	Destroy()

	// 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.
	Window() unsafe.Pointer

	// SetTitle updates the title of the native window. Must be called from the UI
	// thread.
	SetTitle(title string)

	// SetSize updates native window size. See Hint constants.
	SetSize(w int, h int, hint Hint)

	// Navigate navigates webview to the given URL. URL may be a data URI, i.e.
	// "data:text/text,<html>...</html>". It is often ok not to url-encode it
	// properly, webview will re-encode it for you.
	Navigate(url string)

	// 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.
	Init(js string)

	// 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.
	Eval(js string)

	// 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
}

func New

func New(debug bool) WebView

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 NewWindow

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

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.