webviewer

package
v0.0.0-...-3331d8c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 23, 2024 License: BSD-3-Clause, MIT Imports: 14 Imported by: 1

README

webviewer

Go Reference

Give some Webview to your Gio and Golang application. 😎

Currently, GioWebview doesn't work with Gio out-of-box and requires some patches to work.

Usage

Example
// Define what WebView is been used (the Tag specify the tag).
wv := webviewer.WebViewOp{Tag: &something}.Push(gtx.Ops)

// Show the WebView with the given size.
webviewer.RectOp{Size: f32.Point{X: 100, Y: 100}}.Add(gtx.Ops)

// Stop using this webview in the current frame.
wv.Pop(gtx.Ops)
Operations:

Operations must be added with .Add(gtx.Ops) method, except webviewer.WebViewOp which must be added with .Push(gtx.Ops) and .Pop(gtx.Ops). All operations (except webviewer.WebViewOp) should be added inside the stack of webviewer.WebViewOp.

The operation will be executed at the end of the frame.

WebView:

  • webviewer.WebViewOp{Tag: &something}:
    • Limits operations to the WebView. You must re-use the same Tag to use the same WebView. Also, some events (like NavigationEvent, ErrorEvent...) are sent using the Tag.
  • webviewer.NavigateOp{URL: "https://example.com"}:
    • Load the given URL.
  • webviewer.RectOp{Size: f32.Point{X: 100, Y: 100}}:
    • Display the WebView in the current frame, with the specified size in pixels.
  • webviewer.OffsetOp{Offset: f32.Point{X: 10, Y: 10}}:
    • Set the position of the WebView in the current frame, with the specified offset in pixels.

Storage:

  • webviewer.SetStorageOp{Local: webviewer.StorageTypeLocal, Storage: webviewer.Storage{Key: "key", Value: "value"}}:
    • Set storage data for the WebView.
  • webviewer.ListStorageOp{Tag: &something, Local: webviewer.StorageTypeLocal}:
    • List the storage for the WebView. The response will be sent using the Tag as StorageEvent.
  • webviewer.RemoveStorageOp{Tag: &something, Local: webviewer.StorageTypeLocal, Content: webviewer.Storage{Key: "key"}}:
    • Remove the storage for the WebView.

Cookies:

  • webviewer.SetCookieOp{Cookie: webviewer.Cookie{Name: "name", Value: "value"}}:
    • Set the cookie data for the WebView.
  • webviewer.ListCookieOp{Tag: &something}:
    • List the cookie for the WebView. The response will be sent using the Tag as CookiesEvent.
  • webviewer.RemoveCookieOp{Tag: &something, Cookie: webviewer.Cookie{Name: "name"}}:
    • Remove the cookie for the WebView.

Cache:

  • webviewer.ClearCacheOp{}:
    • Clear Cache, Cookies, LocalStorage, SessionStorage, WebSQL, IndexedDB of the current WebView.

Javascript:

  • webviewer.JavascriptOp{Javascript: "console.log(\"Hello World\")"}:
    • Execute the given Javascript code in the WebView.
  • webviewer.InstallJavascriptOp{Javascript: "console.log(\"Hello World\")"}:
    • Persistently define the given Javascript code in the WebView. This code will be executed in every page load.
  • webviewer.MessageReceiverOp{Tag: &something, Name: "your_function_name"}:
    • Defines an function which can be called from the WebView, the function can be called as window.callback.your_function_name("some text") on the WebView side. The response will be sent using the Tag as MessageEvent.
Options:

Some settings can be used to customize the WebView implementation, they must be set before the first webviewer.WebViewOp, it will affect all WebViews. It's recommended to set them in the init.

  • webviewer.SetProxy():
    • [Android/Windows] Set the proxy to use for the WebView.
  • webviewer.SetCustomCertificates():
    • [Android/Windows] Set the custom certificates to use for the WebView, which will be used to validate the SSL connections, additionally to the system CA certificates.

Events

Events are response sent using the Tag and should be handled with gtx.Events().

  • webviewer.NavigationEvent:

    • Sent to WebViewOp.Tag when the WebView navigates to a new page.

  • webviewer.TittleEvent:

    • Sent to WebViewOp.Tag when the WebView changes the page title.

  • webviewer.ErrorEvent:

    • Sent to WebViewOp.Tag when the WebView encounters an error.

  • webviewer.StorageEvent:

    • Sent to ListStorageOp.Tag when the WebView returns the storage list.

  • webiver.CookiesEvent:

    • Sent to ListCookieOp.Tag when the WebView returns the cookie list.

  • webiver.MessageEvent:

    • Sent to MessageReceiverOp.Tag when the WebView calls a function defined with MessageReceiverOp.

Features

We are capable of more than just displaying one webpage.

Features Windows Android MacOS iOS WebAssembly
Basic Support ✔ ✔ ✔ ✔ ✔****
Setup: Custom Proxy ✔*** ✔*** ❌ ❌ ❌
Setup: Custom Certificate ✔*** ✔*** ❌ ❌ ❌
Cookies: Read ✔ ✔ ✔* ✔ ❌
Cookies: Write ✔ ✔ ✔* ✔ ❌
Cookies: Delete ✔ ✔ ❌* ✔ ❌
LocalStorage: Read ✔ ✔ ✔ ✔ ❌
LocalStorage: Write ✔ ✔ ✔ ✔ ❌
LocalStorage: Delete ✔ ✔ ✔ ✔ ❌
SessionStorage: Write ✔ ✔ ✔ ✔ ❌
SessionStorage: Read ✔ ✔ ✔ ✔ ❌
SessionStorage: Delete ✔ ✔ ✔ ✔ ❌
Cache: Delete ✔ ✔ ✔ ✔ ❌
Javascript: Execute ✔ ✔ ✔ ✔ ❌
Javascript: Install ✔ ✔ ✔ ✔ ❌
Javascript: Callback ✔** ✔** ✔** ✔** ❌
Events: NavigationChange ✔ ✔ ✔ ✔ ❌
Events: TitleChange ✔ ✔ ✔ ✔ ❌

  • ❌ = Not supported.

  • ✔ = Supported.

  • * = Cookies can be shared across multiple instances of the WebView. Information from the cookie can be incomplete and lack metadata.

  • ** = Only accepts a string as argument (other types are not supported and might be encoded as text).

  • *** = Must be defined before the WebView is created and is shared with all instances.

  • **** = Only websites that accepts iframe is supported.

APIs

Each operating system has uniqueAPI. For Windows 10+, we use WebView2. For Android 6+, we use WebView. For MacOS and iOS, we use WKWebView. For WebAssembly, the HTMLIFrameElement is used.

Requirements

  • Windows:
    • End-Users: must have Windows 7+ and WebView2 installed (you can install it on the user's machine using the installview package).
    • Developers: must have Golang 1.18+ installed (no CGO required).
  • WebAssembly:
    • End-Users: must have WebAssembly enabled browser (usually Safari 13+, Chrome 70+).
    • Developers: must have Golang 1.18+ installed (no CGO required).
    • Contributors: must have InkWasm installed.
  • macOS:
    • End-Users: must have macOS 11+.
    • Developers: must have macOS device with Golang, Xcode, and CLang installed.
  • iOS:
    • End-Users: must have macOS 11+.
    • Developers: must have macOS device with Golang, Xcode, and CLang installed.
  • Android:
    • End-Users: must have Android 6 or later.
    • Developers: must have Golang 1.18+, OpenJDK 1.8, Android NDK, Android SDK 31+ installed (here for more information).
    • Hacking: must have Android SDK 30 installed.

Limitations

  1. Currently, GioWebview is always the top-most view/window and can't be overlapped by any other draw operation in Gio.
  2. Render multiple webviews at the same time might cause unexpected behaviour, related to z-indexes.
  3. On Javascript/WebAssembly, it needs to be allowed to iframe the content, which most websites blocks such operation.
  4. It's not possible to use WebView using custom shapes (e.g. rounded corners) or apply transformations (e.g. rotating).
  5. Some dialogs (such as alerts, file-picker, etc.) may not be displayed correctly, or not displayed at all.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewConfigFromViewEvent 

func NewConfigFromViewEvent(w *app.Window, evt app.ViewEvent) webview.Config

NewConfigFromViewEvent creates a webview.Config based on app.ViewEvent.

Types

type ClearCacheEvent 

type ClearCacheEvent struct {
	Error error
}

ClearCacheEvent is issued when clearing the storage is completed.

func (ClearCacheEvent) ImplementsEvent 

func (ClearCacheEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type ClearCacheOp 

type ClearCacheOp struct {
	Tag event.Tag
}

ClearCacheOp clears the cache of the webview.

The response in sent via ErrorEvent using the webview as tag. Also, one

func (ClearCacheOp) Add 

func (o ClearCacheOp) Add(op *op.Ops)

type CookiesEvent 

type CookiesEvent struct {
	Cookies []webview.CookieData
}

CookiesEvent is the event sent when ListCookieOp is executed.

func (CookiesEvent) ImplementsEvent 

func (c CookiesEvent) ImplementsEvent()

ImplementsEvent the event.Event interface.

type DestroyOp 

type DestroyOp struct{}

DestroyOp destroys the webview.

func (DestroyOp) Add 

func (o DestroyOp) Add(op *op.Ops)

Add adds a new DestroyOp to the queue.

type ErrorEvent 

type ErrorEvent struct {
	// contains filtered or unexported fields
}

ErrorEvent is issued when the webview encounters an error.

func (ErrorEvent) ImplementsEvent 

func (ErrorEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type ExecuteJavascriptOp 

type ExecuteJavascriptOp struct {
	Script string
}

ExecuteJavascriptOp executes given JavaScript in the webview.

func (ExecuteJavascriptOp) Add 

func (o ExecuteJavascriptOp) Add(op *op.Ops)

Add adds a new ExecuteJavascriptOp to the queue.

type InstallJavascriptOp 

type InstallJavascriptOp struct {
	Script string
}

InstallJavascriptOp installs given JavaScript in the webview, executing it every time the webview loads a new page. The script is executed before the page is fully loaded.

func (InstallJavascriptOp) Add 

func (o InstallJavascriptOp) Add(op *op.Ops)

Add adds a new ExecuteJavascriptOp to the queue.

type ListCookieOp 

type ListCookieOp struct {
	Tag event.Tag
	// Buffer is the buffer to use for the response,
	// that may prevent allocations.
	Buffer []webview.CookieData
}

ListCookieOp lists all cookies in the webview. The response in sent via CookiesEvent using the provided Tag.

func (ListCookieOp) Add 

func (o ListCookieOp) Add(op *op.Ops)

Add adds a new ListCookieOp to the queue.

type ListStorageOp 

type ListStorageOp struct {
	Tag   event.Tag
	Local StorageType
	// Buffer is the buffer to use for the response,
	// that may prevent allocations.
	Buffer []webview.StorageData
}

ListStorageOp lists all Storage in the webview.

The response in sent via StorageEvent using the provided Tag.

func (ListStorageOp) Add 

func (o ListStorageOp) Add(op *op.Ops)

Add adds a new ListStorageOp to the queue.

type MessageEvent 

type MessageEvent struct {
	Message string
}

MessageEvent is the event sent when receiving a message, from previously defined MessageReceiverOp.

func (MessageEvent) ImplementsEvent 

func (c MessageEvent) ImplementsEvent()

ImplementsEvent the event.Event interface.

type MessageReceiverOp 

type MessageReceiverOp struct {
	Tag  event.Tag
	Name string
}

MessageReceiverOp receives a message from the webview, and sends it to the provided Tag. The message is sent as a string.

You can use this to communicate with the webview, by using: 

window.callback.<name>(<message>);

Consider that <name> is the provided Name of the callback, and <message> is the message to send to Tag. The Tag will receive the message as a string, with MessageEvent.

For further information, see webview.JavascriptManager.

func (MessageReceiverOp) Add 

func (o MessageReceiverOp) Add(op *op.Ops)

Add adds a new ExecuteJavascriptOp to the queue. 

type NavigateOp struct {
	// URL is the URL to redirect to.
	URL string
}

NavigateOp redirects the last Display to the given URL. If the URL have unknown protocols, or malformed URL may lead to unknown behaviors. 

func (o NavigateOp) Add(op *op.Ops)

Add adds a new NavigateOp to the queue. 

type NavigationEvent webview.NavigationEvent

NavigationEvent is issued when the webview change the URL. 

func (NavigationEvent) ImplementsEvent()

ImplementsEvent the event.Event interface.

type OffsetOp 

type OffsetOp struct {
	Point f32.Point
}

OffsetOp moves the webview by the specified offset.

func NewOffsetOp 

func NewOffsetOp[POINT image.Point | f32.Point](v POINT) OffsetOp

NewOffsetOp creates a new OffsetOp.

func (OffsetOp) Add 

func (o OffsetOp) Add(op *op.Ops)

Add adds a new OffsetOp to the queue.

type RectOp 

type RectOp struct {
	Size           f32.Point
	SE, SW, NW, NE float32
}

RectOp shows the webview into the specified area. The RectOp is not context-aware, and will overlay any other widget on the screen.

RectOp also takes the foreground and clicks events and keyboard events will not be routed to Gio.

Performance: changing the size/bounds or radius can be expensive. If applicable, change the Rect, instead of changing the size.

Only one RectOp can be active at each frame for the same WebViewOp.

func NewRectOp 

func NewRectOp[POINT image.Point | f32.Point](v POINT) RectOp

NewRectOp creates a new RectOp.

func (RectOp) Add 

func (o RectOp) Add(op *op.Ops)

Add adds a new RectOp to the queue.

type RemoveCookieEvent 

type RemoveCookieEvent struct {
	Error error
}

RemoveCookieEvent is issued when removing a cookie is completed.

func (RemoveCookieEvent) ImplementsEvent 

func (RemoveCookieEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type RemoveCookieOp 

type RemoveCookieOp struct {
	Tag    event.Tag
	Cookie webview.CookieData
}

RemoveCookieOp sets given cookie in the webview.

func (RemoveCookieOp) Add 

func (o RemoveCookieOp) Add(op *op.Ops)

Add adds a new SetCookieOp to the queue.

type RemoveStorageEvent 

type RemoveStorageEvent struct {
	Error error
}

RemoveStorageEvent is issued when removing a storage is completed.

func (RemoveStorageEvent) ImplementsEvent 

func (RemoveStorageEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type RemoveStorageOp 

type RemoveStorageOp struct {
	Tag     event.Tag
	Local   StorageType
	Content webview.StorageData
}

RemoveStorageOp sets given Storage in the webview.

func (RemoveStorageOp) Add 

func (o RemoveStorageOp) Add(op *op.Ops)

Add adds a new RemoveStorageOp to the queue.

type SetCookieArrayEvent 

type SetCookieArrayEvent struct {
	Error error
}

SetCookieArrayEvent is issued when setting a cookie is completed.

func (SetCookieArrayEvent) ImplementsEvent 

func (SetCookieArrayEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type SetCookieArrayOp 

type SetCookieArrayOp struct {
	Tag    event.Tag
	Cookie []webview.CookieData
}

SetCookieArrayOp sets the given list of cookies in the webview.

func (SetCookieArrayOp) Add 

func (o SetCookieArrayOp) Add(op *op.Ops)

Add adds a new SetCookieOp to the queue.

type SetCookieEvent 

type SetCookieEvent struct {
	Error error
}

SetCookieEvent is issued when setting a cookie is completed.

func (SetCookieEvent) ImplementsEvent 

func (SetCookieEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type SetCookieOp 

type SetCookieOp struct {
	Tag    event.Tag
	Cookie webview.CookieData
}

SetCookieOp sets given cookie in the webview.

func (SetCookieOp) Add 

func (o SetCookieOp) Add(op *op.Ops)

Add adds a new SetCookieOp to the queue.

type SetStorageEvent 

type SetStorageEvent struct {
	Error error
}

SetStorageEvent is issued when setting a storage is completed.

func (SetStorageEvent) ImplementsEvent 

func (SetStorageEvent) ImplementsEvent()

ImplementsEvent implements the event.Event interface.

type SetStorageOp 

type SetStorageOp struct {
	Tag     event.Tag
	Local   StorageType
	Content webview.StorageData
}

SetStorageOp sets given Storage in the webview.

func (SetStorageOp) Add 

func (o SetStorageOp) Add(op *op.Ops)

Add adds a new SetStorageOp to the queue.

type StorageEvent 

type StorageEvent struct {
	Storage []webview.StorageData
}

StorageEvent is the event sent when ListStorageOp is executed.

func (StorageEvent) ImplementsEvent 

func (c StorageEvent) ImplementsEvent()

ImplementsEvent the event.Event interface.

type StorageType 

type StorageType int

StorageType is the type of storage. 

const (
	// StorageTypeLocal is the local storage.
	StorageTypeLocal StorageType = iota
	// StorageTypeSession is the session storage.
	StorageTypeSession
)

type TitleEvent 

type TitleEvent webview.TitleEvent

TitleEvent is issued when the webview change the title.

func (TitleEvent) ImplementsEvent 

func (TitleEvent) ImplementsEvent()

ImplementsEvent the event.Event interface.

type WebViewOp 

type WebViewOp struct {
	Tag event.Tag
	// contains filtered or unexported fields
}

WebViewOp shows the webview into the specified area. The RectOp is not context-aware, and will overlay any other widget on the screen.

WebViewOp also takes the foreground and clicks events and keyboard events will not be routed to Gio.

Performance: changing the size/bounds or radius can be expensive. If applicable, change the Offset, instead of changing the size.

func (WebViewOp) Pop 

func (o WebViewOp) Pop(op *op.Ops)

Pop stops using the WebViewOp.

func (WebViewOp) Push 

func (o WebViewOp) Push(op *op.Ops) WebViewOp

Push adds a new WebViewOp to the queue, any subsequent Ops (sucha as RectOp) will affect this WebViewOp. In order to stop using this WebViewOp, call Pop.

Source Files

View all Source files

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.