Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/markbates/wailsx
WIP: Tools for working with Wails.io
https://github.com/markbates/wailsx
Last synced: about 2 months ago
JSON representation
WIP: Tools for working with Wails.io
- Host: GitHub
- URL: https://github.com/markbates/wailsx
- Owner: markbates
- License: other
- Created: 2024-02-27T17:37:22.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-03-21T22:37:11.000Z (9 months ago)
- Last Synced: 2024-10-10T20:43:02.466Z (2 months ago)
- Language: Go
- Homepage:
- Size: 268 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 1.1 - Wailsx - A Testable, Idiomatic Wrapper for Wails
I love [Wails](https://wails.io) 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](#heading-0)
* [1.1.1 - Installation](#heading-1)
* [1.2 - Runtime and API](#heading-2)
* [1.2.1 - The API Interface](#heading-3)
* [1.2.1.1 - Error Handling](#heading-4)
* [1.2.2 - Protecting Wails API Calls](#heading-5)
* [1.2.2.2 - Testing Invalid Wails API Calls](#heading-6)
* [1.3 - Clipboard](#heading-7)
* [1.3.1 - The `ClipboardManager` Interface](#heading-8)
* [1.4 - Dialogs](#heading-9)
* [1.4.1 - The `DialogManager` Interface](#heading-10)
* [1.5 - Events](#heading-11)
* [1.5.1 - The `EventManager` Interface](#heading-12)
* [1.5.2 - The `Manager` Type](#heading-13)
* [1.5.2.1 - Creating a New Manager](#heading-14)
* [1.5.3 - The `CallbackFn` Type](#heading-15)
* [1.5.4 - The `CancelFn` Type](#heading-16)
* [1.6 - Messages](#heading-17)
* [1.6.1 - The `Messenger` Interface](#heading-18)
* [1.6.2 - The `ErrorMessenger` Interface](#heading-19)
* [1.7 - Logging](#heading-20)
* [1.7.1 - The `WailsLogger` Interface](#heading-21)
* [1.8 - Menus](#heading-22)
* [1.8.1 - The `MenuManager` Interface](#heading-23)
* [1.9 - State Data](#heading-24)
* [1.9.1 - The `DataProvider` Interface](#heading-25)
* [1.9.2 - The `Data` Interface](#heading-26)
* [1.10 - Window Management](#heading-27)
* [1.10.1 - The `WindowManager` Interface](#heading-28)
* [1.10.2 - The `MaximiseManager` Interface](#heading-29)
* [1.10.3 - The `PositionManager` Interface](#heading-30)
* [1.10.4 - The `ReloadManager` Interface](#heading-31)
* [1.10.5 - The `ThemeManager` Interface](#heading-32)
* [1.10.6 - The `Toggler` Interface](#heading-33)
* [1.11 - Using the API](#heading-34)
* [1.11.1 - The `API` type](#heading-35)
* [1.11.2 - `Nil` API Calls](#heading-36)
* [1.11.3 - `Nop` API Calls](#heading-37)
Wailsx is a Go module and can be installed with `go get`.
```bash
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.
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#NewAPI) function*
---
The [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) interface, [Listing 1.1](#listing-1-1) declares an idiomatic interface for the [`github.com/wailsapp/wails/v2/pkg/runtime`](https://pkg.go.dev/github.com/wailsapp/wails/v2/pkg/runtime) package.
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#API) interface*
In particular, the [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) improves error handling by adding error returns to the methods that previously returned nothing. For example, the [`runtime.MenuSetApplicationMenu`](https://pkg.go.dev/github.com/wailsapp/wails/v2/pkg/runtime#MenuSetApplicationMenu), [Listing 1.2](#listing-1-2), method now returns an error, [Listing 1.3](#listing-1-3).
```shell
$ 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`](https://pkg.go.dev/github.com/wailsapp/wails/v2/pkg/runtime#MenuSetApplicationMenu) method*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/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`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun#API) interface, [Listing 1.1](#listing-1-1), is implemented in two different files, [Listing 1.4](#listing-1-4) and [Listing 1.5](#listing-1-5).
The `wailsrun/wailscalls_prod.go` file, [Listing 1.4](#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`.
```go
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](#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.
```go
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](#listing-1-6).
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/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`](https://pkg.go.dev/github.com/markbates/wailsx/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](#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`.
```go
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`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun#ErrNotAvailable) method*
When running the tests outside of a Wails application, the [`wailsrun.ErrNotAvailable`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun#ErrNotAvailable) method will return the `ErrNotAvailable` error, [Listing 1.6](#listing-1-6).
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun#ErrNotAvailable) method output.*
If the tests are run in a Wails application, using one of the known build tags, the [`wailsrun.ErrNotAvailable`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun#ErrNotAvailable) method will call the actual Wails API method, [Listing 1.4](#listing-1-4). The result is a call to [`log.Fatal`](https://pkg.go.dev/log#Fatal) because we don't have a valid Wails context.
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun#ErrNotAvailable) method output in `production`.*
---
## 1.3.1 - The ClipboardManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/clipx#ClipboardManager) interface*
---
## 1.4.1 - The DialogManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/dialogx#DialogManager) interface*
---
## 1.5.1 - The EventManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#EventManager) interface*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#Manager) type*
### 1.5.2.1 - Creating a New Manager
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#NewManager) function*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#NopManager) function*
## 1.5.3 - The CallbackFn Type
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#CallbackFn) type*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#CancelFn) type*
---
## 1.6.1 - The Messenger Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx/msgx#Messenger) interface*
## 1.6.2 - The ErrorMessenger Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/eventx/msgx#ErrorMessenger) interface*
---
## 1.7.1 - The WailsLogger Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/logx#WailsLogger) interface*
---
## 1.8.1 - The MenuManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/menux#MenuManager) interface*
---
## 1.9.1 - The DataProvider Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/statedata#DataProvider) interface*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/statedata#Data) interface*
---
## 1.10.1 - The WindowManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/windowx#WindowManager) interface*
## 1.10.2 - The MaximiseManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/windowx#MaximiseManager) interface*
## 1.10.3 - The PositionManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/windowx#PositionManager) interface*
## 1.10.4 - The ReloadManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/windowx#ReloadManager) interface*
## 1.10.5 - The ThemeManager Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/windowx#ThemeManager) interface*
## 1.10.6 - The Toggler Interface
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx/windowx#Toggler) interface*
---
While the [`github.com/markbates/wailsx/wailsrun`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun) package can be used directly, it is recommended to use the [`github.com/markbates/wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx.API) type to create a testable, idiomatic wrapper around the Wails API.
The [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) type is a wrapper around the [`github.com/markbates/wailsx/wailsrun`](https://pkg.go.dev/github.com/markbates/wailsx/wailsrun) package. By default, if the [`wailsx.API`](https://pkg.go.dev/github.com/markbates/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`](https://pkg.go.dev/github.com/markbates/wailsx#API) type in your application without having to worry about the [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) being `nil`.
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#API) type*
The [`wailsx.NewAPI`](https://pkg.go.dev/github.com/markbates/wailsx#NewAPI) function can be used to create a new [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) type. This function will populate the [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) type with implementations of its embedded interfaces. For example, using [`eventx.NewManager`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#NewManager) to create a new [`eventx.Manager`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#Manager) that will fill the needed [`eventx.EventManager`](https://pkg.go.dev/github.com/markbates/wailsx/eventx#EventManager) in the [`wailsx.API`](https://pkg.go.dev/github.com/markbates/wailsx#API) type.
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#NewAPI) function*
```go
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`](https://pkg.go.dev/github.com/markbates/wailsx#API).*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#API).*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#API) in production mode.*
```shell
$ 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`](https://pkg.go.dev/github.com/markbates/wailsx#NopAPI) function*
```go
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`](https://pkg.go.dev/github.com/markbates/wailsx#API).*