taigrr/wails
1
0
Fork 0
mirror of https://github.com/taigrr/wails.git synced 2026-04-14 10:50:53 -07:00
Code Issues Packages Projects Releases Wiki Activity

[v2] Docs update

Browse Source
This commit is contained in:
Lea Anthony
2021-09-27 19:35:30 +10:00
parent 511d0da2cb
commit 589eb3864f
150 changed files with 19195 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
website/docs/reference/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Reference",
"position": 40
}

178
website/docs/reference/cli.mdx Normal file
View File

@@ -0,0 +1,178 @@
---
sidebar_position: 2
---
# CLI
The Wails CLI has a number of commands that are used for managing your projects. All commands are run in the following way:
`wails <command> <flags>`
## init
`wails init` is used for generating projects.
| Flag | Description | Default |
| :------------------- | :------------------------------------- | :------------------------- |
| -n "project name" | Name of the project. **Mandatory**. | |
| -d "project dir" | Project directory to create | Name of the project |
| -g | Initialise git repository | |
| -l | List available project templates | |
| -q | Suppress output to console | |
| -t "template name" | The project template to use. This can be the name of a default template or a URL to a remote template hosted on github. | vanilla |
| -vscode | Generate VSCode project files | |
| -f | Force build application | false |
Example:
`wails init -n test -d mytestproject -g -vscode -q`
This will generate a a project called "test" in the "mytestproject" directory, initialise git,
generate vscode project files and do so silently.
More information on using IDEs with Wails can be found [here](/docs/guides/ides).
### Remote Templates
Remote templates (hosted on GitHub) are supported and can be installed by using the template's project URL.
Example:
`wails init -n test -t https://github.com/leaanthony/testtemplate`
A list of community maintained templates can be found [here](/docs/community/templates)
:::warning Attention
**The Wails project does not maintain, is not responsible nor liable for 3rd party templates!**
If you are unsure about a template, inspect `package.json` and `wails.json` for what scripts are run and what packages are installed.
:::
## build
`wails build` is used for compiling your project to a production-ready binary.
| Flag | Description | Default |
| :------------------- | :-------------------------------------- | :------------------------- |
| -clean | Cleans the `build/bin` directory | |
| -compiler "compiler"| Use a different go compiler to build, eg go1.15beta1 | go |
| -ldflags "flags" | Additional ldflags to pass to the compiler | |
| -nopackage | Do not package application | |
| -o filename | Output filename | |
| -s | Skip building the frontend | |
| -f | Force build application | false |
| -tags "extra tags" | Build tags to pass to compiler (quoted and space separated) | |
| -upx | Compress final binary using "upx" | |
| -upxflags | Flags to pass to upx | |
| -v int | Verbosity level (0 - silent, 1 - default, 2 - verbose) | 1 |
| -webview2 | WebView2 installer strategy: download,embed,browser,error | download |
If you prefer to build using standard Go tooling, please consult the [Manual Builds](/docs/guides/manual-builds)
guide.
Example:
`wails build -clean -o myproject.exe`
## doctor
`wails doctor` will run diagnostics to ensure that your system is ready for development.
Example:
```
Wails CLI v2.0.0-beta
Scanning system - Please wait (this may take a long time)...Done.
System
------
OS: Windows 10 Pro
Version: 2009 (Build: 19043)
ID: 21H1
Go Version: go1.17
Platform: windows
Architecture: amd64
Dependency Package Name Status Version
---------- ------------ ------ -------
WebView2 N/A Installed 93.0.961.52
npm N/A Installed 6.14.15
*upx N/A Installed upx 3.96
* - Optional Dependency
Diagnosis
---------
Your system is ready for Wails development!
```
## dev
`wails dev` is used to run your application in a "live development" mode. This means:
- The application is compiled and run automatically
- A watcher is started and will trigger a rebuild of your dev app if it detects changes to your go files
- A webserver is started on `http://localhost:34115` which serves your application (not just frontend) over http. This allows you to use your favourite browser development extensions
- All application assets are loaded from disk. If they are changed, the application will automatically reload (not rebuild). All connected browsers will also reload
- A JS module is generated that provides the following:
- Javascript wrappers of your Go methods with autogenerated JSDoc, providing code hinting
- TypeScript versions of your Go structs, that can be constructed and passed to your go methods
- A second JS module is generated that provides a wrapper + TS declaration for the runtime
| Flag | Description | Default |
| :------------------- | :-------------------------------------- | :------------------------- |
| -assetdir "./path/to/assets" | The path to your compiled assets | Value in `wails.json` |
| -browser | Opens a browser to `http://localhost:34115` on startup | |
| -compiler "compiler"| Use a different go compiler to build, eg go1.15beta1 | go |
| -e | Extensions to trigger rebuilds (comma separated) | go |
| -ldflags "flags" | Additional ldflags to pass to the compiler | |
| -tags "extra tags" | Build tags to pass to compiler (quoted and space separated) | |
| -loglevel "loglevel"| Loglevel to use - Trace, Debug, Info, Warning, Error | Debug |
| -noreload | Disable automatic reload when assets change | |
| -v | Verbosity level (0 - silent, 1 - standard, 2 - verbose) | 1 |
| -wailsjsdir | The directory to generate the generated Wails JS modules | Value store in `wails.json` |
If the `-assetdir` or `-wailsjsdir` flags are provided on the command line, they are saved in `wails.json`, and become
the defaults for subsequent invocations.
Example:
`wails dev -assetdir ./frontend/dist -wailsjsdir ./frontend/src -browser`
This command will do the following:
- Build the application and run it (more details [here](/docs/guides/manual-builds)
- Generate the Wails JS modules in `./frontend/src`
- Watch for updates to files in `./frontend/dist` and reload on any change
- Open a browser and connect to the application
There is more information on using this feature with existing framework scripts [here](/docs/guides/application-development#live-reloading).
## generate
### template
Wails uses templates for project generation. The `wails generate template` command helps scaffold a template so that
it may be used for generating projects.
| Flag | Description |
| :------------------- | :------------------------------------------- |
| -name | The template name (Mandatory) |
| -frontend "path" | Path to frontend project to use in template |
For more details on creating templates, consult the [Templates guide](/docs/guides/templates).
## update
`wails update` will update the version of the Wails CLI.
| Flag | Description |
| :------------------- | :-------------------------------------- |
| -pre | Update to latest pre-release version |
| -version "version" | Install a specific version of the CLI |
## version
`wails version` will simply output the current CLI version.

233
website/docs/reference/menus.mdx Normal file
View File

@@ -0,0 +1,233 @@
---
sidebar_position: 4
---
# Menus
It is possible to add an application menu to Wails projects. This is achieved by defining a [Menu](#menu) struct and
calling the runtime method [MenuSetApplicationMenu](/docs/reference/runtime/menu#menusetapplicationmenu).
It is also possible to dynamically update the menu, by updating the menu struct and calling
[MenuUpdateApplicationMenu](/docs/reference/runtime/menu#menuupdateapplicationmenu).
Example:
```go
myMenu := menu.NewMenuFromItems(
menu.SubMenu("File", menu.NewMenuFromItems(
menu.Text("&Open", keys.CmdOrCtrl("o"), openFile),
menu.Separator(),
menu.Text("Quit", keys.CmdOrCtrl("q"), func(_ *menu.CallbackData) {
runtime.Quit()
}),
)),
)
runtime.MenuSetApplicationMenu(myMenu)
```
The example above uses helper methods, however it's possible to build the menu structs manually.
## Menu
A Menu is a collection of MenuItems:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu"
type Menu struct {
Items []*MenuItem
}
```
For the Application menu, each MenuItem represents a single menu such as "Edit".
A simple helper method is provided for building menus:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu"
func NewMenuFromItems(first *MenuItem, rest ...*MenuItem) *Menu
```
This makes the layout of the code more like that of a menu without the need to add the menu items manually after creating them.
Alternatively, you can just create the menu items and add them to the menu manually.
## MenuItem
A MenuItem represents an item within a Menu.
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu"
// MenuItem represents a menu item contained in a menu
type MenuItem struct {
Label string
Role Role
Accelerator *keys.Accelerator
Type Type
Disabled bool
Hidden bool
Checked bool
SubMenu *Menu
Click Callback
}
```
| Field | Type | Notes |
| ---------------- | ---------------------------------- | ----------------------------------------------------- |
| Label | string | The menu text |
| Accelerator | [\*keys.Accelerator](#accelerator) | Key binding for this menu item |
| Type | [Type](#type) | Type of MenuItem |
| Disabled | bool | Disables the menu item |
| Hidden | bool | Hides this menu item |
| Checked | bool | Adds check to item (Checkbox & Radio types) |
| SubMenu | [\*Menu](#menu) | Sets the submenu |
| Click | [Callback](#callback) | Callback function when menu clicked |
### Accelerator
Accelerators (sometimes called keyboard shortcuts) define a binding between a keystroke and a menu item. Wails defines
an Accelerator as a combination or key + [Modifier](#modifier). They are available in the `"github.com/wailsapp/wails/v2/pkg/menu/keys"` package.
Example:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu/keys"
// Defines cmd+o on Mac and ctrl-o on Window/Linux
myShortcut := keys.CmdOrCtrl("o")
```
Keys are any single character on a keyboard with the exception of `+`, which is defined as `plus`.
Some keys cannot be represented as characters so there are a set of named characters that may be used:
- `backspace`
- `tab`
- `return`
- `enter`
- `escape`
- `left`
- `right`
- `up`
- `down`
- `space`
- `delete`
- `home`
- `end`
- `page up`
- `page down`
- `f1`
- `f2`
- `f3`
- `f4`
- `f5`
- `f6`
- `f7`
- `f8`
- `f9`
- `f10`
- `f11`
- `f12`
- `f13`
- `f14`
- `f15`
- `f16`
- `f17`
- `f18`
- `f19`
- `f20`
- `f21`
- `f22`
- `f23`
- `f24`
- `f25`
- `f26`
- `f27`
- `f28`
- `f29`
- `f30`
- `f31`
- `f32`
- `f33`
- `f34`
- `f35`
- `numlock`
Wails also supports parsing accelerators using the same syntax as Electron. This is useful for storing accelerators in
config files.
Example:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu/keys"
// Defines cmd+o on Mac and ctrl-o on Window/Linux
myShortcut, err := keys.Parse("Ctrl+Option+A")
```
#### Modifier
The following modifiers are keys that may be used in combination with the accelerator key:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu/keys"
const (
// CmdOrCtrlKey represents Command on Mac and Control on other platforms
CmdOrCtrlKey Modifier = "cmdorctrl"
// OptionOrAltKey represents Option on Mac and Alt on other platforms
OptionOrAltKey Modifier = "optionoralt"
// ShiftKey represents the shift key on all systems
ShiftKey Modifier = "shift"
// ControlKey represents the control key on all systems
ControlKey Modifier = "ctrl"
)
```
A number of helper methods are available to create Accelerators using modifiers:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu/keys"
func CmdOrCtrl(key string) *Accelerator
func OptionOrAlt(key string) *Accelerator
func Shift(key string) *Accelerator
func Control(key string) *Accelerator
```
Modifiers can be combined using `keys.Combo(key string, modifier1 Modifier, modifier2 Modifier, rest ...Modifier)`:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu/keys"
// Defines "Ctrl+Option+A" on Mac and "Ctrl+Alt+A" on Window/Linux
myShortcut := keys.Combo("a", ControlKey, OptionOrAltKey)
```
### Type
Each menu item must have a type and there are 5 types available:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu"
const (
TextType Type = "Text"
SeparatorType Type = "Separator"
SubmenuType Type = "Submenu"
CheckboxType Type = "Checkbox"
RadioType Type = "Radio"
)
```
For convenience, helper methods are provided to quickly create a menu item:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu"
func Text(label string, accelerator *keys.Accelerator, click Callback) *MenuItem
func Separator() *MenuItem
func Radio(label string, selected bool, accelerator *keys.Accelerator, click Callback) *MenuItem
func Checkbox(label string, checked bool, accelerator *keys.Accelerator, click Callback) *MenuItem
func SubMenu(label string, menu *Menu) *MenuItem
```
A note on radio groups: A radio group is defined as a number of radio menu items that are next to each other in the menu.
This means that you do not need to group items together as it is automatic. However, that also means you cannot have 2
radio groups next to each other - there must be a non-radio item between them.
### Callback
Each menu item may have a callback that is executed when the item is clicked:
```go title="Package: github.com/wailsapp/wails/v2/pkg/menu"
type Callback func(*CallbackData)
type CallbackData struct {
MenuItem *MenuItem
}
```
The function is given a `CallbackData` struct which indicates which menu item triggered the callback. This is useful when
using radio groups that may share a callback.

275
website/docs/reference/options.mdx Normal file
View File

@@ -0,0 +1,275 @@
---
sidebar_position: 3
---
# Options
## Application Options
The `Options.App` struct contains the application configuration.
It is passed to the `wails.Run()` method:
```go title="Example"
import "github.com/wailsapp/wails/v2/pkg/options"
func main() {
err := wails.Run(&options.App{
Title: "Menus Demo",
Width: 800,
Height: 600,
DisableResize: false,
Fullscreen: false,
Frameless: true,
MinWidth: 400,
MinHeight: 400,
MaxWidth: 1280,
MaxHeight: 1024,
StartHidden: false,
HideWindowOnClose: false,
RGBA: &options.RGBA{R: 0, G: 0, B: 0, A: 255},
Assets: assets,
Menu: app.applicationMenu(),
Logger: nil,
LogLevel: logger.DEBUG,
OnStartup: app.startup,
OnDomReady: app.domready,
OnShutdown: app.shutdown,
Bind: []interface{}{
app,
},
Windows: &windows.Options{
WebviewIsTransparent: false,
WindowIsTranslucent: false,
DisableWindowIcon: false,
},
})
if err != nil {
log.Fatal(err)
}
}
```
### Title
Name: Title
Type: string
The text shown in the window's title bar.
### Width
Name: Width
Type: int
The initial width of the window.
Default: 1024.
### Height
Name: Height
Type: int
The initial height of the window.
Default: 768
### DisableResize
Name: DisableResize
Type: bool
By default, the main window is resizable. Setting this to `true` will keep it a fixed size.
### Fullscreen
Name: Fullscreen
Type: bool
Setting this to `true` will make the window fullscreen at startup.
### Frameless
Name: Frameless
Type: bool
When set to `true`, the window will have no borders or title bar.
Also see [Frameless Windows](/docs/guides/frameless).
### MinWidth
Name: MinWidth
Type: int
This sets the minimum width for the window. If the value given in `Width` is less than this value,
the window will be set to `MinWidth` by default.
### MinHeight
Name: MinHeight
Type: int
This sets the minimum height for the window. If the value given in `Height` is less than this value,
the window will be set to `MinHeight` by default.
### MaxWidth
Name: MaxWidth
Type: int
This sets the maximum width for the window. If the value given in `Width` is more than this value,
the window will be set to `MaxWidth` by default.
### MaxHeight
Name: MaxHeight
Type: int
This sets the maximum height for the window. If the value given in `Height` is more than this value,
the window will be set to `MaxHeight` by default.
### StartHidden
Name: StartHidden
Type: bool
When set to `true`, the application will be hidden until [WindowShow](/docs/reference/runtime/window#WindowShow)
is called.
### HideWindowOnClose
Name: HideWindowOnClose
Type: bool
By default, closing the window will close the application. Setting this to `true` means closing the window will
hide the window instead.
### RGBA
Name: RGBA
Type: int (0xRRGGBBAA)
Example: 0xFF000088 - Red at 50% transparency
This value is the RGBA value to set the window by default.
Default: 0xFFFFFFFF.
### Assets
Name: Assets
Type: \*embed.FS
The frontend assets to be used by the application. Requires an `index.html` file.
### Menu
Name: Menu
Type: \*menu.Menu
The menu to be used by the application. More details about Menus in the [Menu Reference](/docs/reference/runtime/menu).
### Logger
Name: Logger
Type: logger.Logger
Default: Logger to Stdout
The logger to be used by the application. More details about logging in the [Log Reference](/docs/reference/runtime/log).
### LogLevel
Name: LogLevel
Type: logger.LogLevel
Default: `Info` in dev mode, `Error` in production mode
The default log level. More details about logging in the [Log Reference](/docs/reference/runtime/log).
### OnStartup
Name: OnStartup
Type: func(ctx context.Context)
This callback is called after the frontend has been created, but before `index.html` has been loaded. It is given
the application context.
### OnDomReady
Name: OnDomReady
Type: func(ctx context.Context)
This callback is called after the frontend has loaded `index.html` and the DOM is ready. It is given
the application context.
### OnShutdown
Name: OnShutdown
Type: func(ctx context.Context)
This callback is called after the frontend has been destroyed, just before the application terminates. It is given
the application context.
### Bind
Name: Bind
Type: []interface{}
A slice of struct instances defining methods that need to be bound to the frontend.
### Windows
Name: Windows
Type: \*windows.Options
This defines [Windows specific options](#windows-specific-options).
## Windows Specific Options
### WebviewIsTransparent
Name: WebviewIsTransparent
Type: bool
Setting this to `true` will make the webview background transparent when an alpha value of `0` is used.
This means that if you use `rgba(0,0,0,0)`, the host window will show through.
Often combined with [WindowIsTranslucent](#WindowIsTranslucent) to make frosty-looking applications.
### WindowIsTranslucent
Name: WindowIsTranslucent
Type: bool
Setting this to `true` will make the window background translucent. Often combined
with [WebviewIsTransparent](#WebviewIsTransparent) to make frosty-looking applications.
### DisableWindowIcon
Name: DisableWindowIcon
Type: bool
Setting this to true will remove the icon in the top left corner of the title bar.

24
website/docs/reference/project-config.mdx Normal file
View File

@@ -0,0 +1,24 @@
---
sidebar_position: 5
---
# Project Config
The project config resides in the `wails.json` file in the project directory. The structure of the config is:
```json
{
"name": "[The project name]",
"assetdir": "[Relative path to your assets directory]",
"frontend:install": "[The command to install node dependencies, run in the frontend directory - often `npm install`]",
"frontend:build": "[The command to build the assets, run in the frontend directory - often `npm run build`]",
"wailsjsdir": "[Relative path to the directory that the auto-generated JS modules will be created]",
"version": "[Project config version]",
"outputfilename": "[The name of the binary]"
}
```
This file is read by the Wails CLI when running `wails build` or `wails dev`.
The `assetdir` and `wailsjsdir` flags in `wails build/dev` will update the project config and thus become defaults for
subsequent runs.

4
website/docs/reference/runtime/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Runtime",
"position": 1
}

20
website/docs/reference/runtime/browser.mdx Normal file
View File

@@ -0,0 +1,20 @@
---
sidebar_position: 7
---
# Browser
## Overview
These methods are related to the system browser.
### BrowserOpenURL
Go Signature: `BrowserOpenURL(ctx context.Context, url string)`
JS Signature: `BrowserOpenURL(url string)`
Opens the given URL in the system browser.

140
website/docs/reference/runtime/dialog.mdx Normal file
View File

@@ -0,0 +1,140 @@
---
sidebar_position: 5
---
# Dialog
## Overview
This part of the runtime provides access to native dialogs, such as File Selectors and Message boxes.Context
:::info Javascript
Dialog is currently unsupported in the JS runtime.
:::
### OpenDirectoryDialog
Go Signature: `OpenDirectoryDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)`
Returns: Selected directory (blank if the user cancelled) or an error
Opens a dialog that prompts the user to select a directory. Can be customised using [OpenDialogOptions](#OpenDialogOptions).
### OpenFileDialog
Go Signature: `OpenFileDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)`
Returns: Selected file (blank if the user cancelled) or an error
Opens a dialog that prompts the user to select a file. Can be customised using [OpenDialogOptions](#OpenDialogOptions).
### OpenMultipleFilesDialog
Go Signature: `OpenMultipleFilesDialog(ctx context.Context, dialogOptions OpenDialogOptions) ([]string, error)`
Returns: Selected files (nil if the user cancelled) or an error
Opens a dialog that prompts the user to select multiple files. Can be customised using [OpenDialogOptions](#OpenDialogOptions).
### SaveFileDialog
Go Signature: `SaveFileDialog(ctx context.Context, dialogOptions SaveDialogOptions) (string, error)`
Returns: The selected file (blank if the user cancelled) or an error
Opens a dialog that prompts the user to select a filename for the purposes of saving. Can be customised using [SaveDialogOptions](#SaveDialogOptions).
### MessageDialog
Go Signature: `MessageDialog(ctx context.Context, dialogOptions MessageDialogOptions) (string, error)`
Returns: The text of the selected button or an error
Displays a message using a message dialog. Can be customised using [MessageDialogOptions](#MessageDialogOptions).
## Options
### OpenDialogOptions
```go
type OpenDialogOptions struct {
DefaultDirectory string
DefaultFilename string
Title string
Filters []FileFilter
AllowFiles bool // Mac Only
AllowDirectories bool // Mac Only
ShowHiddenFiles bool // Mac Only
CanCreateDirectories bool // Mac Only
ResolvesAliases bool // Mac Only
TreatPackagesAsDirectories bool // Mac Only
}
```
### SaveDialogOptions
```go
type SaveDialogOptions struct {
DefaultDirectory string
DefaultFilename string
Title string
Filters []FileFilter
ShowHiddenFiles bool // Mac Only
CanCreateDirectories bool // Mac Only
TreatPackagesAsDirectories bool // Mac Only
}
```
### MessageDialogOptions
```go
type MessageDialogOptions struct {
Type DialogType
Title string
Message string
Buttons []string
DefaultButton string // Mac Only
CancelButton string // Mac Only
Icon string // Mac Only
}
```
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="Windows"
values={[
{label: 'Windows', value: 'Windows'},
{label: 'MacOS', value: 'MacOS'},
{label: 'Linux', value: 'Linux'},
]}>
<TabItem value="MacOS">
Both "DefaultButton" and "CancelButton" should match a value in "Buttons".
</TabItem>
<TabItem value="Windows">
Windows has standard dialog types and the buttons are not customisable. The
value returned will be one of: "Ok", "Cancel", "Abort", "Retry", "Ignore", "Yes", "No", "Try Again" or "Continue"
</TabItem>
<TabItem value="Linux">
Coming Soon...
</TabItem>
</Tabs>
#### DialogType
```go
const (
InfoDialog DialogType = "info"
WarningDialog DialogType = "warning"
ErrorDialog DialogType = "error"
QuestionDialog DialogType = "question"
)
```
### FileFilter
```go
type FileFilter struct {
DisplayName string // Filter information EG: "Image Files (*.jpg, *.png)"
Pattern string // semi-colon separated list of extensions, EG: "*.jpg;*.png"
}
```

51
website/docs/reference/runtime/events.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
sidebar_position: 2
---
# Events
## Overview
The Wails runtime provides a unified events system, where events can be emitted or received by either Go or Javascript.
Optionally, data may be passed with the events. Listeners will receive the data in the local data types.
### EventsOn
Go Signature: `EventsOn(ctx context.Context, eventName string, callback func(optionalData ...interface{}))`
JS Signature: `EventsOn(eventName string, callback function(optionalData?: any))`
This method sets up a listener for the given event name. When an event of type `eventName` is [emitted](#EventsEmit),
the callback is triggered. Any additional data sent with the emitted event will be passed to the callback.
### EventsOff
Go Signature: `EventsOff(ctx context.Context, eventName string)`
JS Signature: `EventsOff(eventName string)`
This method unregisters the listener for the given event name.
### EventsOnce
Go Signature: `EventsOnce(ctx context.Context, eventName string, callback func(optionalData ...interface{}))`
JS Signature: `EventsOnce(eventName string, callback function(optionalData?: any))`
This method sets up a listener for the given event name, but will only trigger once.
### EventsOnMultiple
Go Signature: `EventsOnMultiple(ctx context.Context, eventName string, callback func(optionalData ...interface{}), counter int)`
JS Signature: `EventsOnMultiple(eventName string, callback function(optionalData?: any), counter int)`
This method sets up a listener for the given event name, but will only trigger a maximum of `counter` times.
### EventsEmit
Go Signature: `Events(ctx context.Context, eventName string, optionalData ...interface{})`
JS Signature: `Events(ctx context, optionalData function(optionalData?: any))`
This method emits the given event. Optional data may be passed with the event. This will trigger any event listeners.

16
website/docs/reference/runtime/intro.mdx Normal file
View File

@@ -0,0 +1,16 @@
---
sidebar_position: 1
---
# Introduction
The runtime is a library that provides utility methods for your application. There is both a Go and Javascript runtime
and the aim is to try and keep them at parity where possible.
The Go Runtime is available through importing `github.com/wailsapp/wails/v2/pkg/runtime`. All methods in this package
take a context as the first parameter. This context can be obtained from the [OnStartup](/docs/reference/options#OnStartup)
or [OnDomReady](/docs/reference/options#OnDomReady) hooks.
The Javascript library is available to the frontend via the `window.runtime` map. There is a runtime package generated when using `dev`
mode that provides Typescript declarations for the runtime. This should be located in the `wailsjs` directory in your
frontend directory.

114
website/docs/reference/runtime/log.mdx Normal file
View File

@@ -0,0 +1,114 @@
---
sidebar_position: 3
---
# Log
## Overview
The Wails runtime provides a logging mechanism that may be called from Go or Javascript. Like most
loggers, there are a number of log levels:
- Trace
- Debug
- Info
- Warning
- Error
- Fatal
The logger will output any log message at the current, or higher, log level. Example: The `Debug` log
level will output all messages except `Trace` messages.
### LogPrint
Go Signature: `LogPrint(ctx context.Context, message string)`
JS Signature: `LogPrint(message: string)`
Logs the given message as a raw message.
### LogTrace
Go Signature: `LogTrace(ctx context.Context, message string)`
JS Signature: `LogTrace(message: string)`
Logs the given message at the `Trace` log level.
### LogDebug
Go Signature: `LogDebug(ctx context.Context, message string)`
JS Signature: `LogDebug(message: string)`
Logs the given message at the `Debug` log level.
### LogInfo
Go Signature: `LogInfo(ctx context.Context, message string)`
JS Signature: `LogInfo(message: string)`
Logs the given message at the `Info` log level.
### LogWarning
Go Signature: `LogWarning(ctx context.Context, message string)`
JS Signature: `LogWarning(message: string)`
Logs the given message at the `Warning` log level.
### LogError
Go Signature: `LogError(ctx context.Context, message string)`
JS Signature: `LogError(message: string)`
Logs the given message at the `Error` log level.
### LogFatal
Go Signature: `LogFatal(ctx context.Context, message string)`
JS Signature: `LogFatal(message: string)`
Logs the given message at the `Fatal` log level.
### LogSetLogLevel
Go Signature: `LogSetLogLevel(ctx context.Context, level logger.LogLevel)`
JS Signature: `LogSetLogLevel(level: number)`
Sets the log level. In Javascript, the number relates to the following log levels:
| Value | Log Level |
| ----- | --------- |
| 1 | Trace |
| 2 | Debug |
| 3 | Info |
| 4 | Warning |
| 5 | Error |
## Using a Custom Logger
A custom logger may be used by providing it using the [Logger](/docs/reference/options#logger)
application option. The only requirement is that the logger implements the `logger.Logger` interface
defined in `github.com/wailsapp/wails/v2/pkg/logger`:
```go title="logger.go"
type Logger interface {
Print(message string)
Trace(message string)
Debug(message string)
Info(message string)
Warning(message string)
Error(message string)
Fatal(message string)
}
```

25
website/docs/reference/runtime/menu.mdx Normal file
View File

@@ -0,0 +1,25 @@
---
sidebar_position: 6
---
# Menu
## Overview
These methods are related to the application menu.
:::info Javascript
Menu is currently unsupported in the JS runtime.
:::
### MenuSetApplicationMenu
Go Signature: `MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu)`
Sets the application menu to the given [menu](/docs/reference/menus) .
### MenuUpdateApplicationMenu
Go Signature: `MenuUpdateApplicationMenu(ctx context.Context)`
Updates the application menu, picking up any changes to the menu passed to `MenuSetApplicationMenu`.

184
website/docs/reference/runtime/window.mdx Normal file
View File

@@ -0,0 +1,184 @@
---
sidebar_position: 4
---
# Window
## Overview
These methods give control of the application window.
### WindowSetTitle
Go Signature: `WindowSetTitle(ctx context.Context, title string)`
JS Signature: `WindowSetTitle(title: string)`
Sets the text in the window title bar.
### WindowFullscreen
Go Signature: `WindowFullscreen(ctx context.Context)`
JS Signature: `WindowFullscreen()`
Makes the window full screen.
### WindowUnFullscreen
Go Signature: `WindowUnFullscreen(ctx context.Context)`
JS Signature: `WindowUnFullscreen()`
Restores the previous window dimensions and position prior to full screen.
### WindowCenter
Go Signature: `WindowCenter(ctx context.Context)`
JS Signature: `WindowCenter()`
Centers the window on the monitor the window is currently on.
### WindowReload
Go Signature: `WindowReload(ctx context.Context)`
JS Signature: `WindowReload()`
Performs a "reload" (Reloads index.html)
### WindowShow
Go Signature: `WindowShow(ctx context.Context)`
JS Signature: `WindowShow()`
Shows the window, if it is currently hidden.
### WindowHide
Go Signature: `WindowHide(ctx context.Context)`
JS Signature: `WindowHide()`
Hides the window, if it is currently visible.
### WindowSetSize
Go Signature: `WindowSetSize(ctx context.Context, width int, height int)`
JS Signature: `WindowSetSize(size: Size)`
Sets the width and height of the window.
### WindowGetSize
Go Signature: `WindowGetSize(ctx context.Context) (width int, height int)`
JS Signature: `WindowGetSize() : Size`
Gets the width and height of the window.
### WindowSetMinSize
Go Signature: `WindowSetMinSize(ctx context.Context, width int, height int)`
JS Signature: `WindowSetMinSize(size: Size)`
Sets the minimum window size.
Will resize the window if the window is currently smaller than the given dimensions.
Setting a size of `0,0` will disable this constraint.
### WindowSetMaxSize
Go Signature: `WindowSetMaxSize(ctx context.Context, width int, height int)`
JS Signature: `WindowSetMaxSize(size: Size)`
Sets the maximum window size.
Will resize the window if the window is currently larger than the given dimensions.
Setting a size of `0,0` will disable this constraint.
### WindowSetPosition
Go Signature: `WindowSetPosition(ctx context.Context, x int, y int)`
JS Signature: `WindowSetPosition(position: Position)`
Sets the window position relative to the monitor the window is currently on.
### WindowGetPosition
Go Signature: `WindowGetPosition(ctx context.Context) (x int, y int)`
JS Signature: `WindowGetPosition() : Position`
Gets the window position relative to the monitor the window is currently on.
### WindowMaximise
Go Signature: `WindowMaximise(ctx context.Context)`
JS Signature: `WindowMaximise()`
Maximises the window to fill the screen.
### WindowUnmaximise
Go Signature: `WindowUnmaximise(ctx context.Context)`
JS Signature: `WindowUnmaximise()`
Restores the window to the dimensions and position prior to maximising.
### WindowMinimise
Go Signature: `WindowMinimise(ctx context.Context)`
JS Signature: `WindowMinimise()`
Minimises the window.
### WindowUnminimise
Go Signature: `WindowUnminimise(ctx context.Context)`
JS Signature: `WindowUnminimise()`
Restores the window to the dimensions and position prior to minimising.
### WindowSetRGBA
Go Signature: `WindowSetRGBA(ctx context.Context, col *options.RGBA)`
JS Signature: `WindowSetRGBA(col: RGBA)`
Sets the background colour of the window to the given [RGBA](window#rgba) colour definition.
This colour will show through for all transparent pixels.
Valid values for R, G, B and A are 0-255.
:::info Windows
On Windows, only alpha values of 0 or 255 are supported.
Any value that is not 0 will be considered 255.
:::
## Typescript Object Definitions
### Position
```ts
interface Position {
x: number;
y: number;
}
```
### Size
```ts
interface Size {
w: number;
h: number;
}
```
### RGBA
```ts
interface RGBA {
r,
g,
b,
a: number;
}
```