README
¶
wvapp
wvapp is a lightweight library for creating cross-platform desktop applications using WebView. It leverages WebKit (Linux/macOS) and WebView2 (Windows) to render web content in native windows.
Features
- Cross-platform support: Works on Windows, macOS, and Linux.
- WebView integration: Uses WebKit on Linux/macOS and WebView2 on Windows.
- Customizable window options: Configure window size, position, title, and more.
- JavaScript bindings: Bind JavaScript functions to native C/Go callbacks.
- Debugging tools: Enable developer tools for debugging web content.
- Lightweight: Minimal dependencies and optimized for performance.
Compatibility and Stability
To maximize stability across different OS versions and graphics stacks, wvapp applies conservative defaults and offers opt-in overrides:
-
Linux (GTK/WebKitGTK)
- Defaults set only if not customized by user:
- WEBKIT_DISABLE_DMABUF_RENDERER=1 (disable dmabuf to avoid black screen/crash on some drivers); override with WVAPP_DMABUF=1 to enable.
- JSC_SIGNAL_FOR_GC=12 (SIGUSR2 as default GC signal); override with WVAPP_JSC_SIGNAL.
- GTK3/GTK4 compatible code paths; WebKitGTK 4.1 preferred, auto-fallback to 4.0 in Makefile.
- Event loop returns true when no active windows remain, ensuring Go Run() can exit.
- Defaults set only if not customized by user:
-
Windows (WebView2)
- Fullscreen/maximize/minimize/restore unified APIs; DPI awareness enabled with layered fallback.
- Event loop returns true on WM_QUIT to align exit semantics.
-
macOS (WKWebView)
- Bind/unbind uses a robust “clear-and-rebuild scripts” strategy to avoid stale handlers across navigations.
- Event loop returns true when no windows remain, matching other platforms.
Troubleshooting (Linux)
- If you see a black/blank window, try keeping dmabuf disabled (default). To test enabling it:
- Set WVAPP_DMABUF=1 (which sets WEBKIT_DISABLE_DMABUF_RENDERER=0).
- Ensure WebKitGTK and GTK dev packages are installed; Makefile auto-detects webkit2gtk-4.1 and falls back to 4.0.
- On Wayland, verify XDG_RUNTIME_DIR is valid and has correct permissions.
Stability Tips
- Prefer SetHtml for quick diagnostics (no network) before testing SetURL.
- Re-bind functions after navigation/DOMReady to ensure bridges are available.
- Avoid heavy work on the UI thread—offload to worker pool and use EvalJS for UI updates.
Documentation
¶
Index ¶
- Variables
- func CleanupGlobalURIScheme() error
- func GetGlobalURIScheme() string
- func InitializeGlobalWorkerPool(workerCount int, queueSize int)
- func PollMainTasks()
- func ProcessEvents() bool
- func RegisterGlobalURIScheme(schemeName string, handler ResourceHandler) error
- func RegisterGlobalURISchemeWithFS(schemeName string, fsys fs.FS) error
- func Run()
- func ShutdownGlobalWorkerPool()
- type BindCallback
- type CallPayload
- type EventCallback
- type EventType
- type HandlerFunc
- type Job
- type Resource
- type ResourceHandler
- type Scheduler
- type Webview
- func (w *Webview) BeginDragAt(x, y int)
- func (w *Webview) Bind(name string, fn BindCallback, userData unsafe.Pointer)
- func (w *Webview) Destroy()
- func (w *Webview) EvalJS(js string)
- func (w *Webview) InitializeJavaScriptRuntime()
- func (w *Webview) Maximize()
- func (w *Webview) Minimize()
- func (w *Webview) Restore()
- func (w *Webview) SetDebug(debug bool)
- func (w *Webview) SetEventCallback(callback EventCallback)
- func (w *Webview) SetFrameless(frameless bool)
- func (w *Webview) SetFullscreen(fullscreen bool)
- func (w *Webview) SetHtml(html string)
- func (w *Webview) SetSize(width, height int)
- func (w *Webview) SetTitle(title string)
- func (w *Webview) SetURL(url string)
- func (w *Webview) SetWindowPosition(position WindowPosition)
- func (w *Webview) Terminate()
- func (w *Webview) Unbind(name string)
- type WindowOptions
- type WindowPosition
- type WorkerPool
Constants ¶
This section is empty.
Variables ¶
var UserFunctionRegistry = make(map[string]HandlerFunc)
UserFunctionRegistry stores the Go functions that can be called from JavaScript. The key is the function name (string) as called from JavaScript. The value is the Go function that handles the call.
Functions ¶
func InitializeGlobalWorkerPool ¶
InitializeGlobalWorkerPool creates the global worker pool. This should be called once during application startup.
func PollMainTasks ¶
func PollMainTasks()
func ProcessEvents ¶
func ProcessEvents() bool
func RegisterGlobalURIScheme ¶
func RegisterGlobalURIScheme(schemeName string, handler ResourceHandler) error
RegisterGlobalURIScheme 注册全局URI
func RegisterGlobalURISchemeWithFS ¶
RegisterGlobalURISchemeWithFS 使用文件系统注册全局URI
func ShutdownGlobalWorkerPool ¶
func ShutdownGlobalWorkerPool()
ShutdownGlobalWorkerPool stops the global worker pool. This should be called during application shutdown to ensure graceful termination.
Types ¶
type BindCallback ¶
type CallPayload ¶
type CallPayload struct {
Func string `json:"func"`
Args []any `json:"args"`
PromiseID int `json:"promiseId,omitempty"` // omitempty if JS doesn't always send it
}
CallPayload defines the structure of messages from JavaScript. Ensure this matches the structure sent by your runtime.js/goCall.
type EventCallback ¶
type HandlerFunc ¶
type Job ¶
type Job struct {
Webview *Webview // The wvapp instance to interact with (e.g., for EvalJS)
Payload CallPayload // The original payload from JavaScript
Handler HandlerFunc // The Go function to execute
}
Job represents a task to be executed by a worker.
type ResourceHandler ¶
ResourceHandler 资源处理函数类型
func NewResourceHandlerFromFS ¶
func NewResourceHandlerFromFS(fsys fs.FS) ResourceHandler
NewResourceHandlerFromFS 从文件系统创建资源处理函数
func NewResourceHandlerFromStaticCache ¶
func NewResourceHandlerFromStaticCache(staticCache map[string][]byte) ResourceHandler
NewResourceHandlerFromStaticCache 从静态缓存创建资源处理函数
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
func NewScheduler ¶
func NewScheduler() *Scheduler
func (*Scheduler) PollTasks ¶
func (s *Scheduler) PollTasks()
PollTasks executes all pending tasks without blocking
func (*Scheduler) RunInMainThread ¶
func (s *Scheduler) RunInMainThread(f func())
func (*Scheduler) RunInMainThreadWithResult ¶
Run a function in the main thread and return its result
type Webview ¶
type Webview struct{}
func NewWebview ¶
func NewWebview(options *WindowOptions) (*Webview, error)
func (*Webview) BeginDragAt ¶
func (*Webview) Bind ¶
func (w *Webview) Bind(name string, fn BindCallback, userData unsafe.Pointer)
func (*Webview) InitializeJavaScriptRuntime ¶
func (w *Webview) InitializeJavaScriptRuntime()
func (*Webview) SetEventCallback ¶
func (w *Webview) SetEventCallback(callback EventCallback)
func (*Webview) SetFrameless ¶
func (*Webview) SetFullscreen ¶
func (*Webview) SetWindowPosition ¶
func (w *Webview) SetWindowPosition(position WindowPosition)
type WindowOptions ¶
type WindowOptions struct {
Width int
Height int
MinWidth int // 最小宽度（0表示不限制）
MinHeight int // 最小高度（0表示不限制）
MaxWidth int // 最大宽度（0表示不限制）
MaxHeight int // 最大高度（0表示不限制）
ZoomLevel float32 // 缩放级别（0表示默认缩放，1表示100%）
Position WindowPosition // 窗口位置
Debug bool // 是否开启开发者工具
Title string // 窗口标题
Icon []byte // 图标字节切片，通常是PNG或ICO格式
Opaque bool // 窗口是否不透明（true=不透明，false=透明）
HasShadow bool // 是否有阴影
DisableResize bool // 是否禁用窗口大小调整（true=禁用，false=允许）
EnableFileAccess bool // 是否启用本地文件访问
EnableClipboard bool // 是否启用剪贴板访问
EnableWebGL bool // 是否启用WebGL
}
窗口选项结构体（仅用于初始化或批量设置）
type WindowPosition ¶
type WindowPosition int32
const ( WindowPositionCenter WindowPosition = iota WindowPositionLeftTop WindowPositionRightTop WindowPositionLeftBottom WindowPositionRightBottom )
type WorkerPool ¶
type WorkerPool struct {
// contains filtered or unexported fields
}
WorkerPool manages a pool of worker goroutines.
func NewWorkerPool ¶
func NewWorkerPool(workerCount int, queueSize int) *WorkerPool
NewWorkerPool creates and starts a new worker pool.
func (*WorkerPool) Shutdown ¶
func (wp *WorkerPool) Shutdown()
Shutdown gracefully stops all workers. It first signals workers to stop accepting new jobs, then closes the job queue, and finally waits for all active jobs to complete.
func (*WorkerPool) Submit ¶
func (wp *WorkerPool) Submit(job Job) error
Submit adds a job to the worker pool's queue. It returns an error if the pool is shutting down or the queue is full.
Source Files
Directories