1.1 - Wailsx - A Testable, Idiomatic Wrapper for Wails

I love Wails and have been using it to create some great applications. Unfortunately, the Wails v2 API is not very testable or idiomatic. Wailsx is a wrapper around the Wails API that makes it easier to test and use in a more idiomatic way.

1.1 - Wailsx - A Testable, Idiomatic Wrapper for Wails
1.1.1 - Installation
1.2 - Runtime and API
1.2.1 - The API Interface
1.2.1.1 - Error Handling
1.2.2 - Protecting Wails API Calls
1.2.2.2 - Testing Invalid Wails API Calls
1.3 - Clipboard
1.3.1 - The ClipboardManager Interface
1.4 - Dialogs
1.4.1 - The DialogManager Interface
1.5 - Events
1.5.1 - The EventManager Interface
1.5.2 - The Manager Type
1.5.2.1 - Creating a New Manager
1.5.3 - The CallbackFn Type
1.5.4 - The CancelFn Type
1.6 - Messages
1.6.1 - The Messenger Interface
1.6.2 - The ErrorMessenger Interface
1.7 - Logging
1.7.1 - The WailsLogger Interface
1.8 - Menus
1.8.1 - The MenuManager Interface
1.9 - State Data
1.9.1 - The DataProvider Interface
1.9.2 - The Data Interface
1.10 - Window Management
1.10.1 - The WindowManager Interface
1.10.2 - The MaximiseManager Interface
1.10.3 - The PositionManager Interface
1.10.4 - The ReloadManager Interface
1.10.5 - The ThemeManager Interface
1.10.6 - The Toggler Interface
1.11 - Using the API
1.11.1 - The API type
1.11.2 - Nil API Calls
1.11.3 - Nop API Calls

1.1.1 - Installation

Wailsx is a Go module and can be installed with go get.

go get github.com/markbates/wailsx

Figure 1.1: Installing github.com/markbates/wailsx with go get.

Once imported, you can use the wailsx package in your application.

$ go doc -short github.com/markbates/wailsx.NewAPI

func NewAPI() *API
    NewAPI returns a new API with all the functions, and interfaces, set to
    their default implementations.

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.2: The wailsx.NewAPI function

1.2 - Runtime and API

1.2.1 - The API Interface

The wailsx.API interface, Listing 1.1 declares an idiomatic interface for the github.com/wailsapp/wails/v2/pkg/runtime package.

$ go doc github.com/markbates/wailsx/wailsrun.API

package wailsrun // import "github.com/markbates/wailsx/wailsrun"

type API interface {
	BrowserOpenURL(ctx context.Context, url string) error
	ClipboardGetText(ctx context.Context) (string, error)
	ClipboardSetText(ctx context.Context, text string) error
	EventsEmit(ctx context.Context, event string, data ...any) error
	EventsOff(ctx context.Context, event string, additional ...string) error
	EventsOffAll(ctx context.Context) error
	EventsOn(ctx context.Context, event string, callback CallbackFn) (CancelFn, error)
	EventsOnMultiple(ctx context.Context, event string, callback CallbackFn, counter int) (CancelFn, error)
	EventsOnce(ctx context.Context, event string, callback CallbackFn) (CancelFn, error)
	Hide(ctx context.Context) error
	LogDebug(ctx context.Context, message string) error
	LogDebugf(ctx context.Context, format string, args ...any) error
	LogError(ctx context.Context, message string) error
	LogErrorf(ctx context.Context, format string, args ...any) error
	LogFatal(ctx context.Context, message string) error
	LogFatalf(ctx context.Context, format string, args ...any) error
	LogInfo(ctx context.Context, message string) error
	LogInfof(ctx context.Context, format string, args ...any) error
	LogPrint(ctx context.Context, message string) error
	LogPrintf(ctx context.Context, format string, args ...any) error
	LogSetLogLevel(ctx context.Context, level logger.LogLevel) error
	LogTrace(ctx context.Context, message string) error
	LogTracef(ctx context.Context, format string, args ...any) error
	LogWarning(ctx context.Context, message string) error
	LogWarningf(ctx context.Context, format string, args ...any) error
	MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu) error
	MenuUpdateApplicationMenu(ctx context.Context) error
	MessageDialog(ctx context.Context, dialogOptions MessageDialogOptions) (string, error)
	OpenDirectoryDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)
	OpenFileDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)
	OpenMultipleFilesDialog(ctx context.Context, dialogOptions OpenDialogOptions) ([]string, error)
	Quit(ctx context.Context) error
	SaveFileDialog(ctx context.Context, dialogOptions SaveDialogOptions) (string, error)
	Show(ctx context.Context) error
	WindowCenter(ctx context.Context) error
	WindowExecJS(ctx context.Context, js string) error
	WindowFullscreen(ctx context.Context) error
	WindowGetPosition(ctx context.Context) (int, int, error)
	WindowGetSize(ctx context.Context) (int, int, error)
	WindowHide(ctx context.Context) error
	WindowIsFullscreen(ctx context.Context) (bool, error)
	WindowIsMaximised(ctx context.Context) (bool, error)
	WindowIsMinimised(ctx context.Context) (bool, error)
	WindowIsNormal(ctx context.Context) (bool, error)
	WindowMaximise(ctx context.Context) error
	WindowMinimise(ctx context.Context) error
	WindowPrint(ctx context.Context) error
	WindowReload(ctx context.Context) error
	WindowReloadApp(ctx context.Context) error
	WindowSetAlwaysOnTop(ctx context.Context, b bool) error
	WindowSetBackgroundColour(ctx context.Context, R, G, B, A uint8) error
	WindowSetDarkTheme(ctx context.Context) error
	WindowSetLightTheme(ctx context.Context) error
	WindowSetMaxSize(ctx context.Context, width int, height int) error
	WindowSetMinSize(ctx context.Context, width int, height int) error
	WindowSetPosition(ctx context.Context, x int, y int) error
	WindowSetSize(ctx context.Context, width int, height int) error
	WindowSetSystemDefaultTheme(ctx context.Context) error
	WindowSetTitle(ctx context.Context, title string) error
	WindowShow(ctx context.Context) error
	WindowToggleMaximise(ctx context.Context) error
	WindowUnfullscreen(ctx context.Context) error
	WindowUnmaximise(ctx context.Context) error
	WindowUnminimise(ctx context.Context) error
	ScreenGetAll(ctx context.Context) ([]Screen, error)
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.1: The wailsx.API interface

1.2.1.1 - Error Handling

In particular, the wailsx.API improves error handling by adding error returns to the methods that previously returned nothing. For example, the runtime.MenuSetApplicationMenu, Listing 1.2, method now returns an error, Listing 1.3.

$ go doc github.com/wailsapp/wails/v2/pkg/runtime.MenuSetApplicationMenu

package runtime // import "github.com/wailsapp/wails/v2/pkg/runtime"

func MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu)

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.2: The runtime.MenuSetApplicationMenu method

$ go doc github.com/markbates/wailsx/wailsrun.API.MenuSetApplicationMenu

package wailsrun // import "github.com/markbates/wailsx/wailsrun"

type API interface {
	MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.3: The wailsrun.API.MenuSetApplicationMenu method

1.2.2 - Protecting Wails API Calls

Wailsx uses Go build tags to protect the Wails API calls from being called in a production environment. The wailsrun.API interface, Listing 1.1, is implemented in two different files, Listing 1.4 and Listing 1.5.

The wailsrun/wailscalls_prod.go file, Listing 1.4, is only built when any of the following builds are provided: wails || dev || desktop || production. This file contains the actual Wails API calls and most returned errors are nil.

import (
	"context"

	"github.com/wailsapp/wails/v2/pkg/logger"
	"github.com/wailsapp/wails/v2/pkg/menu"
	"github.com/wailsapp/wails/v2/pkg/runtime"
)

func BrowserOpenURL(ctx context.Context, url string) error {
	runtime.BrowserOpenURL(ctx, url)
	return nil
}

source: wailsrun/wailscalls_prod.go:BrowserOpenURL

Listing 1.4: Production Wails API calls: wailsrun/wailscalls_prod.go

In all other environments, such as testing, the wailsrun/wailscalls.go file, Listing 1.5, is built in all environments and contains the Wailsx API calls. The Wailsx API calls are then used to call the Wails API calls in the development environment.

import (
	"context"

	"github.com/wailsapp/wails/v2/pkg/logger"
	"github.com/wailsapp/wails/v2/pkg/menu"
)

func BrowserOpenURL(ctx context.Context, url string) error {
	return ErrNotAvailable("BrowserOpenURL")
}

source: wailsrun/wailscalls.go:BrowserOpenURL

Listing 1.5: Stubbed Wails API calls: wailsrun/wailscalls.go

In these environments all of the Wails API calls will return the ErrNotAvailable error, Listing 1.6.

$ go doc github.com/markbates/wailsx/wailsrun.ErrNotAvailable

package wailsrun // import "github.com/markbates/wailsx/wailsrun"

type ErrNotAvailable string

func (e ErrNotAvailable) Error() string

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.6: The wailsrun.ErrNotAvailable error

1.2.2.2 - Testing Invalid Wails API Calls

With the help of Go build tags, any direct calls made to the Wails API, outside of a running Wails application, will return the wailsrun.ErrNotAvailable error. This allows for testing of the Wails API calls in a non-Wails environment.

In the test seen in Listing 1.7 we are making a direct call to the Wails API and checking the error returned. The test passes when the error returned is ErrNotAvailable.

func Test_ErrNotAvailable(t *testing.T) {
	t.Parallel()

	r := require.New(t)

	ctx := context.Background()

	err := wailsrun.BrowserOpenURL(ctx, "https://example.com")
	r.Error(err)

	exp := wailsrun.ErrNotAvailable("BrowserOpenURL")
	r.Equal(exp, err)
}

source: wailsrun/api_calls_test.go:err-not-available

Listing 1.7: Testing the wailsrun.ErrNotAvailable method

When running the tests outside of a Wails application, the wailsrun.ErrNotAvailable method will return the ErrNotAvailable error, Listing 1.6.

$ go test -v -run Test_ErrNotAvailable

testing: warning: no tests to run
PASS
ok  	github.com/markbates/wailsx	0.006s

go: downloading github.com/markbates/safe v1.1.0
go: downloading github.com/wailsapp/wails/v2 v2.8.0
go: downloading github.com/stretchr/testify v1.9.0
go: downloading github.com/davecgh/go-spew v1.1.1
go: downloading github.com/pmezard/go-difflib v1.0.0
go: downloading gopkg.in/yaml.v3 v3.0.1
go: downloading github.com/leaanthony/slicer v1.6.0
go: downloading github.com/leaanthony/u v1.1.1

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.8: Testing the wailsrun.ErrNotAvailable method output.

If the tests are run in a Wails application, using one of the known build tags, the wailsrun.ErrNotAvailable method will call the actual Wails API method, Listing 1.4. The result is a call to log.Fatal because we don't have a valid Wails context.

$ go test -v -run Test_ErrNotAvailable -tags wails

testing: warning: no tests to run
PASS
ok  	github.com/markbates/wailsx	0.003s

go: downloading github.com/markbates/safe v1.1.0
go: downloading github.com/wailsapp/wails/v2 v2.8.0
go: downloading github.com/stretchr/testify v1.9.0
go: downloading github.com/davecgh/go-spew v1.1.1
go: downloading github.com/pmezard/go-difflib v1.0.0
go: downloading gopkg.in/yaml.v3 v3.0.1
go: downloading github.com/leaanthony/slicer v1.6.0
go: downloading github.com/leaanthony/u v1.1.1

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.9: Testing the wailsrun.ErrNotAvailable method output in production.

1.3 - Clipboard

1.3.1 - The `ClipboardManager` Interface

$ go doc github.com/markbates/wailsx/clipx.ClipboardManager

package clipx // import "github.com/markbates/wailsx/clipx"

type ClipboardManager interface {
	ClipboardGetText(ctx context.Context) (string, error)
	ClipboardSetText(ctx context.Context, text string) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.3: The clipx.ClipboardManager interface

1.4 - Dialogs

1.4.1 - The `DialogManager` Interface

$ go doc github.com/markbates/wailsx/dialogx.DialogManager

package dialogx // import "github.com/markbates/wailsx/dialogx"

type DialogManager interface {
	MessageDialog(ctx context.Context, opts MessageDialogOptions) (string, error)
	OpenDirectoryDialog(ctx context.Context, opts OpenDialogOptions) (string, error)
	OpenFileDialog(ctx context.Context, opts OpenDialogOptions) (string, error)
	OpenMultipleFilesDialog(ctx context.Context, opts OpenDialogOptions) ([]string, error)
	SaveFileDialog(ctx context.Context, opts SaveDialogOptions) (string, error)
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.10: The dialogx.DialogManager interface

1.5 - Events

1.5.1 - The `EventManager` Interface

$ go doc github.com/markbates/wailsx/eventx.EventManager

package eventx // import "github.com/markbates/wailsx/eventx"

type EventManager interface {
	EventsEmit(ctx context.Context, event string, args ...any) (err error)
	EventsOff(ctx context.Context, name string, additional ...string) error
	EventsOffAll(ctx context.Context) error
	EventsOn(ctx context.Context, name string, callback CallbackFn) (CancelFn, error)
	EventsOnMultiple(ctx context.Context, name string, callback CallbackFn, counter int) (CancelFn, error)
	EventsOnce(ctx context.Context, name string, callback CallbackFn) (CancelFn, error)
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.11: The eventx.EventManager interface

1.5.2 - The `Manager` Type

$ go doc github.com/markbates/wailsx/eventx.Manager

package eventx // import "github.com/markbates/wailsx/eventx"

type Manager struct {
	DisableWildcardEmits bool
	DisableStateData     bool

	EventsEmitFn       func(ctx context.Context, name string, data ...any) error
	EventsOffAllFn     func(ctx context.Context) error
	EventsOffFn        func(ctx context.Context, name string, additional ...string) error
	EventsOnFn         func(ctx context.Context, name string, callback CallbackFn) (CancelFn, error)
	EventsOnMultipleFn func(ctx context.Context, name string, callback CallbackFn, counter int) (CancelFn, error)
	EventsOnceFn       func(ctx context.Context, name string, callback CallbackFn) (CancelFn, error)

	NowFn func() time.Time

	// Has unexported fields.
}

func NewManager() *Manager
func NopManager() *Manager
func (em *Manager) EventsEmit(ctx context.Context, event string, args ...any) (err error)
func (em *Manager) EventsOff(ctx context.Context, name string, additional ...string) error
func (em *Manager) EventsOffAll(ctx context.Context) error
func (em *Manager) EventsOn(ctx context.Context, name string, callback CallbackFn) (CancelFn, error)
func (em *Manager) EventsOnMultiple(ctx context.Context, name string, callback CallbackFn, counter int) (CancelFn, error)
func (em *Manager) EventsOnce(ctx context.Context, name string, callback CallbackFn) (CancelFn, error)
func (em *Manager) MarshalJSON() ([]byte, error)
func (em *Manager) Now() time.Time
func (em *Manager) PluginName() string
func (em *Manager) StateData(ctx context.Context) (statedata.Data[*EventsData], error)
func (em *Manager) WithPlugins(fn plugins.FeederFn) error

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.12: The eventx.Manager type

1.5.2.1 - Creating a New Manager

$ go doc github.com/markbates/wailsx/eventx.NewManager

package eventx // import "github.com/markbates/wailsx/eventx"

func NewManager() *Manager

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.13: The eventx.NewManager function

$ go doc github.com/markbates/wailsx/eventx.NopManager

package eventx // import "github.com/markbates/wailsx/eventx"

func NopManager() *Manager
    NopManager returns a new Manager with all the functions set to no-ops This
    is useful for testing. The NowFn is set to wailstest.NowTime

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.14: The eventx.NopManager function

1.5.3 - The `CallbackFn` Type

$ go doc github.com/markbates/wailsx/wailsrun.CallbackFn

package wailsrun // import "github.com/markbates/wailsx/wailsrun"

type CallbackFn func(data ...any) error

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.15: The eventx.CallbackFn type

1.5.4 - The `CancelFn` Type

$ go doc github.com/markbates/wailsx/wailsrun.CancelFn

package wailsrun // import "github.com/markbates/wailsx/wailsrun"

type CancelFn func() error

func EventsOn(ctx context.Context, event string, callback CallbackFn) (CancelFn, error)
func EventsOnMultiple(ctx context.Context, event string, callback CallbackFn, counter int) (CancelFn, error)
func EventsOnce(ctx context.Context, event string, callback CallbackFn) (CancelFn, error)

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.16: The eventx.CancelFn type

1.6 - Messages

1.6.1 - The `Messenger` Interface

$ go doc github.com/markbates/wailsx/eventx/msgx.Messenger

package msgx // import "github.com/markbates/wailsx/eventx/msgx"

type Messenger interface {
	MsgEvent() string
	MsgText() string
	MsgTime() time.Time
	MsgData() any
}

func NewMessage(event string, now time.Time, arg any) Messenger

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.17: The msgx.Messenger interface

1.6.2 - The `ErrorMessenger` Interface

$ go doc github.com/markbates/wailsx/eventx/msgx.ErrorMessenger

package msgx // import "github.com/markbates/wailsx/eventx/msgx"

type ErrorMessenger interface {
	Messenger
	MsgError() error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.18: The msgx.ErrorMessenger interface

1.7 - Logging

1.7.1 - The `WailsLogger` Interface

$ go doc github.com/markbates/wailsx/logx.WailsLogger

package logx // import "github.com/markbates/wailsx/logx"

type WailsLogger interface {
	LogDebug(ctx context.Context, message string) error
	LogDebugf(ctx context.Context, format string, args ...any) error
	LogError(ctx context.Context, message string) error
	LogErrorf(ctx context.Context, format string, args ...any) error
	LogFatal(ctx context.Context, message string) error
	LogFatalf(ctx context.Context, format string, args ...any) error
	LogInfo(ctx context.Context, message string) error
	LogInfof(ctx context.Context, format string, args ...any) error
	LogPrint(ctx context.Context, message string) error
	LogPrintf(ctx context.Context, format string, args ...any) error
	LogSetLogLevel(ctx context.Context, level wailsrun.LogLevel) error
	LogTrace(ctx context.Context, message string) error
	LogTracef(ctx context.Context, format string, args ...any) error
	LogWarning(ctx context.Context, message string) error
	LogWarningf(ctx context.Context, format string, args ...any) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.19: The logx.WailsLogger interface

1.8 - Menus

1.8.1 - The `MenuManager` Interface

$ go doc github.com/markbates/wailsx/menux.MenuManager

package menux // import "github.com/markbates/wailsx/menux"

type MenuManager interface {
	MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu) error
	MenuUpdateApplicationMenu(ctx context.Context) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.20: The menux.MenuManager interface

1.9 - State Data

1.9.1 - The `DataProvider` Interface

$ go doc github.com/markbates/wailsx/statedata.DataProvider

package statedata // import "github.com/markbates/wailsx/statedata"

type DataProvider[T any] interface {
	StateData(ctx context.Context) (Data[T], error)
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.21: The statedata.DataProvider interface

1.9.2 - The `Data` Interface

$ go doc github.com/markbates/wailsx/statedata.Data

package statedata // import "github.com/markbates/wailsx/statedata"

type Data[T any] struct {
	Name string `json:"name,omitempty"` // name of the data
	Data T      `json:"data,omitempty"` // data for the state
}

func (sd Data[T]) PluginName() string
func (sd Data[T]) StateData(ctx context.Context) (Data[T], error)

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.22: The statedata.Data interface

1.10 - Window Management

1.10.1 - The `WindowManager` Interface

$ go doc github.com/markbates/wailsx/windowx.WindowManager

package windowx // import "github.com/markbates/wailsx/windowx"

type WindowManager interface {
	MaximiseManager
	PositionManager
	ReloadManager
	ThemeManager
	Toggler

	ScreenGetAll(ctx context.Context) ([]Screen, error)
	WindowExecJS(ctx context.Context, js string) error
	WindowPrint(ctx context.Context) error
	WindowSetAlwaysOnTop(ctx context.Context, b bool) error
	WindowSetTitle(ctx context.Context, title string) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.23: The windowx.WindowManager interface

1.10.2 - The `MaximiseManager` Interface

$ go doc github.com/markbates/wailsx/windowx.MaximiseManager

package windowx // import "github.com/markbates/wailsx/windowx"

type MaximiseManager interface {
	WindowFullscreen(ctx context.Context) error
	WindowIsFullscreen(ctx context.Context) (bool, error)
	WindowIsMaximised(ctx context.Context) (bool, error)
	WindowIsMinimised(ctx context.Context) (bool, error)
	WindowIsNormal(ctx context.Context) (bool, error)
	WindowMaximise(ctx context.Context) error
	WindowMinimise(ctx context.Context) error
	WindowToggleMaximise(ctx context.Context) error
	WindowUnfullscreen(ctx context.Context) error
	WindowUnmaximise(ctx context.Context) error
	WindowUnminimise(ctx context.Context) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.24: The windowx.MaximiseManager interface

1.10.3 - The `PositionManager` Interface

$ go doc github.com/markbates/wailsx/windowx.PositionManager

package windowx // import "github.com/markbates/wailsx/windowx"

type PositionManager interface {
	WindowCenter(ctx context.Context) error
	WindowGetPosition(ctx context.Context) (int, int, error)
	WindowGetSize(ctx context.Context) (int, int, error)
	WindowSetMaxSize(ctx context.Context, width int, height int) error
	WindowSetMinSize(ctx context.Context, width int, height int) error
	WindowSetPosition(ctx context.Context, x int, y int) error
	WindowSetSize(ctx context.Context, width int, height int) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.25: The windowx.PositionManager interface

1.10.4 - The `ReloadManager` Interface

$ go doc github.com/markbates/wailsx/windowx.ReloadManager

package windowx // import "github.com/markbates/wailsx/windowx"

type ReloadManager interface {
	WindowReload(ctx context.Context) error
	WindowReloadApp(ctx context.Context) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.26: The windowx.ReloadManager interface

1.10.5 - The `ThemeManager` Interface

$ go doc github.com/markbates/wailsx/windowx.ThemeManager

package windowx // import "github.com/markbates/wailsx/windowx"

type ThemeManager interface {
	WindowSetBackgroundColour(ctx context.Context, R, G, B, A uint8) error
	WindowSetDarkTheme(ctx context.Context) error
	WindowSetLightTheme(ctx context.Context) error
	WindowSetSystemDefaultTheme(ctx context.Context) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.27: The windowx.ThemeManager interface

1.10.6 - The `Toggler` Interface

$ go doc github.com/markbates/wailsx/windowx.Toggler

package windowx // import "github.com/markbates/wailsx/windowx"

type Toggler interface {
	Hide(ctx context.Context) error
	Show(ctx context.Context) error
	WindowHide(ctx context.Context) error
	WindowShow(ctx context.Context) error
}

--------------------------------------------------------------------------------
Go Version: go1.22.1

Listing 1.28: The windowx.Toggler interface

1.11 - Using the API

While the github.com/markbates/wailsx/wailsrun package can be used directly, it is recommended to use the github.com/markbates/wailsx.API type to create a testable, idiomatic wrapper around the Wails API.

1.11.1 - The `API` type

The wailsx.API type is a wrapper around the github.com/markbates/wailsx/wailsrun package. By default, if the wailsx.API type is nil, or zero (i.e. &API{}), all methods will be will be mapped directly to the wailsrun package. This allows you to use the wailsx.API type in your application without having to worry about the wailsx.API being nil.

$ go doc -short github.com/markbates/wailsx.API

type API struct {
	clipx.ClipboardManager
	dialogx.DialogManager
	eventx.EventManager
	logx.WailsLogger
	menux.MenuManager
	windowx.WindowManager

	BrowserOpenURLFn func(ctx context.Context, url string) error
	QuitFn           func(ctx context.Context) error
}

func NewAPI() *API
func NopAPI() *API
func (api *API) BrowserOpenURL(ctx context.Context, url string) error
func (api *API) ClipboardGetText(ctx context.Context) (string, error)
func (api *API) ClipboardSetText(ctx context.Context, text string) error
func (api *API) EventsEmit(ctx context.Context, event string, data ...any) error
func (api *API) EventsOff(ctx context.Context, event string, additional ...string) error
func (api *API) EventsOffAll(ctx context.Context) error
func (api *API) EventsOn(ctx context.Context, event string, callback wailsrun.CallbackFn) (wailsrun.CancelFn, error)
func (api *API) EventsOnMultiple(ctx context.Context, event string, callback wailsrun.CallbackFn, counter int) (wailsrun.CancelFn, error)
func (api *API) EventsOnce(ctx context.Context, event string, callback wailsrun.CallbackFn) (wailsrun.CancelFn, error)
func (api *API) Hide(ctx context.Context) error
func (api *API) LogDebug(ctx context.Context, message string) error
func (api *API) LogDebugf(ctx context.Context, format string, args ...any) error
func (api *API) LogError(ctx context.Context, message string) error
func (api *API) LogErrorf(ctx context.Context, format string, args ...any) error
func (api *API) LogFatal(ctx context.Context, message string) error
func (api *API) LogFatalf(ctx context.Context, format string, args ...any) error
func (api *API) LogInfo(ctx context.Context, message string) error
func (api *API) LogInfof(ctx context.Context, format string, args ...any) error
func (api *API) LogPrint(ctx context.Context, message string) error
func (api *API) LogPrintf(ctx context.Context, format string, args ...any) error
func (api *API) LogSetLogLevel(ctx context.Context, level logger.LogLevel) error
func (api *API) LogTrace(ctx context.Context, message string) error
func (api *API) LogTracef(ctx context.Context, format string, args ...any) error
func (api *API) LogWarning(ctx context.Context, message string) error
func (api *API) LogWarningf(ctx context.Context, format string, args ...any) error
func (api *API) MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu) error
func (api *API) MenuUpdateApplicationMenu(ctx context.Context) error
func (api *API) MessageDialog(ctx context.Context, opts wailsrun.MessageDialogOptions) (string, error)
func (api *API) OpenDirectoryDialog(ctx context.Context, opts wailsrun.OpenDialogOptions) (string, error)
func (api *API) OpenFileDialog(ctx context.Context, opts wailsrun.OpenDialogOptions) (string, error)
func (api *API) OpenMultipleFilesDialog(ctx context.Context, opts wailsrun.OpenDialogOptions) ([]string, error)
func (api *API) Quit(ctx context.Context) error
func (api *API) SaveFileDialog(ctx context.Context, opts wailsrun.SaveDialogOptions) (string, error)
func (api *API) ScreenGetAll(ctx context.Context) ([]wailsrun.Screen, error)
func (api *API) Show(ctx context.Context) error
func (api *API) StateData(ctx context.Context) (statedata.Data[*APIData], error)
func (api *API) WindowCenter(ctx context.Context) error
func (api *API) WindowExecJS(ctx context.Context, js string) error
func (api *API) WindowFullscreen(ctx context.Context) error
func (api *API) WindowGetPosition(ctx context.Context) (int, int, error)
func (api *API) WindowGetSize(ctx context.Context) (int, int, error)
func (api *API) WindowHide(ctx context.Context) error
func (api *API) WindowIsFullscreen(ctx context.Context) (bool, error)
func (api *API) WindowIsMaximised(ctx context.Context) (bool, error)
func (api *API) WindowIsMinimised(ctx context.Context) (bool, error)
func (api *API) WindowIsNormal(ctx context.Context) (bool, error)
func (api *API) WindowMaximise(ctx context.Context) error
func (api *API) WindowMinimise(ctx context.Context) error
func (api *API) WindowPrint(ctx context.Context) error
func (api *API) WindowReload(ctx context.Context) error
func (api *API) WindowReloadApp(ctx context.Context) error
func (api *API) WindowSetAlwaysOnTop(ctx context.Context, b bool) error
func (api *API) WindowSetBackgroundColour(ctx context.Context, R, G, B, A uint8) error
func (api *API) WindowSetDarkTheme(ctx context.Context) error
func (api *API) WindowSetLightTheme(ctx context.Context) error
func (api *API) WindowSetMaxSize(ctx context.Context, width int, height int) error
func (api *API) WindowSetMinSize(ctx context.Context, width int, height int) error
func (api *API) WindowSetPosition(ctx context.Context, x int, y int) error
func (api *API) WindowSetSize(ctx context.Context, width int, height int) error
func (api *API) WindowSetSystemDefaultTheme(ctx context.Context) error
func (api *API) WindowSetTitle(ctx context.Context, title string) error
func (api *API) WindowShow(ctx context.Context) error
func (api *API) WindowToggleMaximise(ctx context.Context) error
func (api *API) WindowUnfullscreen(ctx context.Context) error
func (api *API) WindowUnmaximise(ctx context.Context) error
func (api *API) WindowUnminimise(ctx context.Context) error

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.4: The wailsx.API type

The wailsx.NewAPI function can be used to create a new wailsx.API type. This function will populate the wailsx.API type with implementations of its embedded interfaces. For example, using eventx.NewManager to create a new eventx.Manager that will fill the needed eventx.EventManager in the wailsx.API type.

$ go doc -short github.com/markbates/wailsx.NewAPI

func NewAPI() *API
    NewAPI returns a new API with all the functions, and interfaces, set to
    their default implementations.

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.5: The wailsx.NewAPI function

1.11.2 - `Nil` API Calls

func Test_Nil_API_Call(t *testing.T) {
	t.Parallel()
	r := require.New(t)

	var api *API

	ctx := context.Background()

	err := api.Show(ctx)
	r.Error(err)

	exp := wailsrun.ErrNotAvailable("Show")
	r.Equal(exp, err)
}

source: doc_test.go:nil-api

Figure 1.6: Calling methods on a nil wailsx.API.

$ go test -v -run Test_Nil_API_Call

=== RUN   Test_Nil_API_Call
=== PAUSE Test_Nil_API_Call
=== CONT  Test_Nil_API_Call
--- PASS: Test_Nil_API_Call (0.00s)
PASS
ok  	github.com/markbates/wailsx	0.005s

go: downloading github.com/markbates/safe v1.1.0
go: downloading github.com/wailsapp/wails/v2 v2.8.0
go: downloading github.com/stretchr/testify v1.9.0
go: downloading github.com/davecgh/go-spew v1.1.1
go: downloading github.com/pmezard/go-difflib v1.0.0
go: downloading gopkg.in/yaml.v3 v3.0.1
go: downloading github.com/leaanthony/slicer v1.6.0
go: downloading github.com/leaanthony/u v1.1.1

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.7: Running the test for calling methods on a nil wailsx.API.

$ go test -v -run Test_Nil_API_Call -tags wails

=== RUN   Test_Nil_API_Call
=== PAUSE Test_Nil_API_Call
=== CONT  Test_Nil_API_Call
2024/03/13 03:52:45 cannot call 'github.com/wailsapp/wails/v2/pkg/runtime.Show': An invalid context was passed. This method requires the specific context given in the lifecycle hooks:
https://wails.io/docs/reference/runtime/intro
exit status 1
FAIL	github.com/markbates/wailsx	0.007s

go: downloading github.com/markbates/safe v1.1.0
go: downloading github.com/wailsapp/wails/v2 v2.8.0
go: downloading github.com/stretchr/testify v1.9.0
go: downloading github.com/davecgh/go-spew v1.1.1
go: downloading github.com/pmezard/go-difflib v1.0.0
go: downloading gopkg.in/yaml.v3 v3.0.1
go: downloading github.com/leaanthony/slicer v1.6.0
go: downloading github.com/leaanthony/u v1.1.1

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.8: Running the test for calling methods on a nil wailsx.API in production mode.

1.11.3 - `Nop` API Calls

$ go doc -short github.com/markbates/wailsx.NopAPI

func NopAPI() *API
    NopAPI returns a new API with all the functions, and interfaces, set to
    no-ops. This is useful for testing.

--------------------------------------------------------------------------------
Go Version: go1.22.1

Figure 1.9: The wailsx.NopAPI function

func Test_Nop_API_Call(t *testing.T) {
	t.Parallel()
	r := require.New(t)

	api := NopAPI()

	ctx := context.Background()

	err := api.Show(ctx)
	r.NoError(err)
}

source: doc_test.go:nop-api

Figure 1.10: Calling methods on a nop wailsx.API.

1.1 - Wailsx - A Testable, Idiomatic Wrapper for Wails

1.1.1 - Installation

1.2 - Runtime and API

1.2.1 - The API Interface

1.2.1.1 - Error Handling

1.2.2 - Protecting Wails API Calls

1.2.2.2 - Testing Invalid Wails API Calls

1.3 - Clipboard

1.3.1 - The ClipboardManager Interface

1.4 - Dialogs

1.4.1 - The DialogManager Interface

1.5 - Events

1.5.1 - The EventManager Interface

1.5.2 - The Manager Type

1.5.2.1 - Creating a New Manager

1.5.3 - The CallbackFn Type

1.5.4 - The CancelFn Type

1.6 - Messages

1.6.1 - The Messenger Interface

1.6.2 - The ErrorMessenger Interface

1.7 - Logging

1.7.1 - The WailsLogger Interface

1.8 - Menus

1.8.1 - The MenuManager Interface

1.9 - State Data

1.9.1 - The DataProvider Interface

1.9.2 - The Data Interface

1.10 - Window Management

1.10.1 - The WindowManager Interface

1.10.2 - The MaximiseManager Interface

1.10.3 - The PositionManager Interface

1.10.4 - The ReloadManager Interface

1.10.5 - The ThemeManager Interface

1.10.6 - The Toggler Interface