mirror of
https://github.com/taigrr/wails.git
synced 2026-04-14 10:50:53 -07:00
[v2] Docs update
This commit is contained in:
Lea Anthony
70
website/docs/about.md
Normal file
70
website/docs/about.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# About
|
||||
|
||||
## Overview
|
||||
|
||||
Wails is a project that enables you to write desktop apps using Go and web technologies.
|
||||
|
||||
Consider it a lightweight and fast Electron alternative for Go. You can easily build applications with the flexibility
|
||||
and power of Go, combined with a rich, modern frontend.
|
||||
|
||||
Wails doesn't hold back with the eye candy either! This is [xbar](https://xbarapp.com) - a desktop application for MacOS
|
||||
written using Wails. It has menus, supports light and dark desktop themes, and the main window uses translucency that
|
||||
gives it that 'frosty' effect of a native app.
|
||||
|
||||
<p class="text--center">
|
||||
<a href="https://xbarapp.com"><img src="/img/xbar-app-preview-2.png" width="75%"/></a>
|
||||
</p>
|
||||
|
||||
## Native Elements
|
||||
|
||||
Wails uses a purpose built library for handling native elements such as Window, Menus, Dialogs, etc, so you can build
|
||||
good-looking, feature rich desktop applications.
|
||||
|
||||
**It does not embed a browser**, so it is resource efficient. Instead, it uses the native rendering engine for the
|
||||
platform. On Windows, this is the new Microsoft Webview2 library, built on Chromium.
|
||||
|
||||
## Go & Javascript Interoperability
|
||||
|
||||
Wails automatically makes your Go methods available to Javascript, so you can call them by name from your frontend!
|
||||
It even generates Typescript versions of the structs used by your Go methods, so you can pass the same data structures
|
||||
between Go and Javascript.
|
||||
|
||||
## Runtime Library
|
||||
|
||||
Wails provides a runtime library, for both Go and Javascript, that handles a lot of the things modern applications need,
|
||||
like Eventing, Logging, Dialogs, etc.
|
||||
|
||||
## Live Development Experience
|
||||
|
||||
### Automatic Rebuilds
|
||||
|
||||
When you run your application in "dev" mode, Wails will build your application as a native desktop application, but will
|
||||
read your assets from disk. It will detect any changes to your Go code and automatically rebuild and relaunch your
|
||||
application.
|
||||
|
||||
### Automatic Reloads
|
||||
|
||||
When changes to your application assets are detected, your running application will "reload", reflecting your changes
|
||||
almost immediately.
|
||||
|
||||
### Develop your application in a Browser
|
||||
|
||||
If you prefer to debug and develop in a browser then Wails has you covered. The running application also has a webserver
|
||||
that will run your application in any browser that connects to it. It will even refresh when your assets change on disk.
|
||||
|
||||
## Production-ready Native Binaries
|
||||
|
||||
When you're ready to do the final build of your application, the CLI will compile it down to a single executable, with
|
||||
all the assets bundled into it. On Windows and MacOS, it is possible to create a native package for distribution. The
|
||||
assets used in packaging (icon, info.plist, manifest file, etc) are part of your project and may be customised, giving
|
||||
you total control over how your applications are built.
|
||||
|
||||
## Tooling
|
||||
|
||||
The Wails CLI provides a hassle-free way to generate, build and bundle your applications. It will do the heavy lifting
|
||||
of creating icons, compiling your application with optimal settings and delivering a distributable, production ready
|
||||
binary. Choose from a number of starter templates to get up and running quickly!
|
||||
4
website/docs/community/_category_.json
Normal file
4
website/docs/community/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Community",
|
||||
"position": 50
|
||||
}
|
||||
19
website/docs/community/links.mdx
Normal file
19
website/docs/community/links.mdx
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Links
|
||||
|
||||
This page serves as a list for community related links. Please submit a PR (click `Edit this page` at the bottom)
|
||||
to submit links.
|
||||
|
||||
## Support Channels
|
||||
|
||||
- [Gophers Slack Channel](https://gophers.slack.com/messages/CJ4P9F7MZ/)
|
||||
- [Gophers Slack Channel Invite](https://invite.slack.golangbridge.org/)
|
||||
- [Github Issues](https://github.com/wailsapp/wails/issues)
|
||||
- [v2 Beta Discussion Board](https://github.com/wailsapp/wails/discussions)
|
||||
|
||||
## Social Media
|
||||
|
||||
- [Twitter](https://twitter.com/wailsapp)
|
||||
4
website/docs/community/showcase/_category_.json
Normal file
4
website/docs/community/showcase/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Showcase",
|
||||
"position": 1
|
||||
}
|
||||
BIN
website/docs/community/showcase/encrypteasy.jpg
Normal file
BIN
website/docs/community/showcase/encrypteasy.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
10
website/docs/community/showcase/encrypteasy.mdx
Normal file
10
website/docs/community/showcase/encrypteasy.mdx
Normal file
@@ -0,0 +1,10 @@
|
||||
|
||||
# EncryptEasy
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="encrypteasy.jpg"></img><br/>
|
||||
</p>
|
||||
|
||||
**[EncryptEasy](https://www.encrypteasy.app) is a simple and easy to use PGP encryption tool, managing all your and your contacts keys. Encryption should be simple. Developed with Wails.**
|
||||
|
||||
Encrypting messages using PGP is the industry standard. Everyone has a private and a public key. Your private key, well, needs to be kept private so only you can read messages. Your public key is distributed to anyone who wants to send you secret, encrypted messages. Managing keys, encrypting messages and decrypting messages should be a smooth experience. EncryptEasy is all about making it easy.
|
||||
BIN
website/docs/community/showcase/filehound.jpg
Normal file
BIN
website/docs/community/showcase/filehound.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 286 KiB |
23
website/docs/community/showcase/filehound.mdx
Normal file
23
website/docs/community/showcase/filehound.mdx
Normal file
@@ -0,0 +1,23 @@
|
||||
|
||||
# FileHound Export Utility
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="filehound.jpg"></img><br/>
|
||||
</p>
|
||||
|
||||
|
||||
[FileHound Export Utility](https://www.filehound.co.uk/) FileHound is a cloud document management platform made for secure file retention, business process automation and SmartCapture capabilities.
|
||||
|
||||
The FileHound Export Utility allows FileHound Administrators the ability to run a secure document and data extraction tasks for alternative back-up and recovery purposes. This application will download all documents and/or meta data saved in FileHound based on the filters you choose. The metadata will be exported in both JSON and XML formats.
|
||||
|
||||
Backend built with:
|
||||
Go 1.15
|
||||
Wails 1.11.0
|
||||
go-sqlite3 1.14.6
|
||||
go-linq 3.2
|
||||
|
||||
Frontend with:
|
||||
Vue 2.6.11
|
||||
Vuex 3.4.0
|
||||
Typescript
|
||||
Tailwind 1.9.6
|
||||
9
website/docs/community/showcase/mollywallet.mdx
Normal file
9
website/docs/community/showcase/mollywallet.mdx
Normal file
@@ -0,0 +1,9 @@
|
||||
|
||||
# Molley Wallet
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="mollywallet.png"></img><br/>
|
||||
</p>
|
||||
|
||||
[Molly Wallet](https://github.com/grvlle/constellation_wallet/) the official $DAG wallet of the Constellation Network. It'll let users interact with the Hypergraph Network in various ways, not limited to producing $DAG transactions.
|
||||
|
||||
BIN
website/docs/community/showcase/mollywallet.png
Normal file
BIN
website/docs/community/showcase/mollywallet.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 632 KiB |
9
website/docs/community/showcase/optimus.mdx
Normal file
9
website/docs/community/showcase/optimus.mdx
Normal file
@@ -0,0 +1,9 @@
|
||||
|
||||
# Optimus
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="optimus.png"></img><br/>
|
||||
</p>
|
||||
|
||||
[Optimus](https://github.com/splode/optimus) is a desktop image optimization application. It supports conversion and compression between WebP, JPEG, and PNG image formats.
|
||||
|
||||
BIN
website/docs/community/showcase/optimus.png
Normal file
BIN
website/docs/community/showcase/optimus.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
BIN
website/docs/community/showcase/portfall.gif
Normal file
BIN
website/docs/community/showcase/portfall.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.9 MiB |
9
website/docs/community/showcase/portfall.mdx
Normal file
9
website/docs/community/showcase/portfall.mdx
Normal file
@@ -0,0 +1,9 @@
|
||||
|
||||
# Portfall
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="portfall.gif"></img><br/>
|
||||
</p>
|
||||
|
||||
[Portfall](https://github.com/rekon-oss/portfall) - A desktop k8s port-forwarding portal for easy access to all your cluster UIs
|
||||
|
||||
9
website/docs/community/showcase/surge.mdx
Normal file
9
website/docs/community/showcase/surge.mdx
Normal file
@@ -0,0 +1,9 @@
|
||||
|
||||
# Surge
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="surge.png"></img><br/>
|
||||
</p>
|
||||
|
||||
[Surge](https://surge.rule110.io/) is a p2p filesharing app designed to utilize blockchain technologies to enable 100% anonymous file transfers. Surge is end-to-end encrypted, decentralized and open source.
|
||||
|
||||
BIN
website/docs/community/showcase/surge.png
Normal file
BIN
website/docs/community/showcase/surge.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
9
website/docs/community/showcase/wally.mdx
Normal file
9
website/docs/community/showcase/wally.mdx
Normal file
@@ -0,0 +1,9 @@
|
||||
|
||||
# Wally
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="wally.png"></img><br/>
|
||||
</p>
|
||||
|
||||
[Wally](https://ergodox-ez.com/pages/wally) is the official firmware flasher for [Ergodox](https://ergodox-ez.com/) keyboards. It looks great and is a fantastic example of what you can achieve with Wails: the ability to combine the power of Go and the rich graphical tools of the web development world.
|
||||
|
||||
BIN
website/docs/community/showcase/wally.png
Normal file
BIN
website/docs/community/showcase/wally.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 177 KiB |
10
website/docs/community/showcase/wombat.mdx
Normal file
10
website/docs/community/showcase/wombat.mdx
Normal file
@@ -0,0 +1,10 @@
|
||||
|
||||
# Wombat
|
||||
|
||||
<p style={{"text-align": "center"}}>
|
||||
<img src="wombat.png"></img><br/>
|
||||
</p>
|
||||
|
||||
|
||||
[Wombat](https://github.com/rogchap/wombat) is a cross platform gRPC client.
|
||||
|
||||
BIN
website/docs/community/showcase/wombat.png
Normal file
BIN
website/docs/community/showcase/wombat.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 248 KiB |
25
website/docs/community/templates.mdx
Normal file
25
website/docs/community/templates.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Templates
|
||||
|
||||
This page serves as a list for community supported templates. Please submit a PR (click `Edit this page` at the bottom)
|
||||
to include your templates. To build your own template, please see the [Templates](/docs/guides/templates) guide.
|
||||
|
||||
To use these templates, run `wails init -n "Your Project Name" -t [the link below]`
|
||||
|
||||
Example: `wails init -n "Your Project Name" -t https://github.com/misitebao/wails-template-vue`
|
||||
|
||||
:::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.
|
||||
|
||||
:::
|
||||
|
||||
## Vue
|
||||
|
||||
- [wails-template-vue](https://github.com/misitebao/wails-template-vue) - A template using vue and vue-router
|
||||
|
||||
83
website/docs/credits.mdx
Normal file
83
website/docs/credits.mdx
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
sidebar_position: 99
|
||||
---
|
||||
|
||||
# Credits
|
||||
|
||||
- [Lea Anthony](https://github.com/leaanthony) - Project owner, lead developer
|
||||
- [Misitebao](https://github.com/misitebao) - Chinese documentation, Windows testing, Bug finder general
|
||||
- [Travis McLane](https://github.com/tmclane) - Cross-compilation work, MacOS testing
|
||||
- [Byron Chris](https://github.com/bh90210) - Linux distro wizard, Linux testing
|
||||
|
||||
## Sponsors
|
||||
|
||||
<div
|
||||
dangerouslySetInnerHTML={{
|
||||
__html: `
|
||||
<a href="https://github.com/sponsors/leaanthony" style="width:100px;">
|
||||
<img src="/img/bronze%20sponsor.png" width="100"/>
|
||||
</a>
|
||||
<a href="https://github.com/snider" style="width:100px;">
|
||||
<img src="https://github.com/snider.png?size=100" width="100"/>
|
||||
</a>
|
||||
<br/>
|
||||
<br/>
|
||||
<a href="https://github.com/matryer" style="width:100px">
|
||||
<img src="https://github.com/matryer.png" width="100"/>
|
||||
</a>
|
||||
<a href="https://www.jetbrains.com?from=Wails" style="width:100px">
|
||||
<img src="/img/jetbrains-grayscale.png" width="100"/>
|
||||
</a>
|
||||
<a href="https://github.com/tc-hib" style="width:55px">
|
||||
<img src="https://github.com/tc-hib.png?size=55" width="55"/>
|
||||
</a>
|
||||
<a href="https://github.com/picatz" style="width:50px">
|
||||
<img src="https://github.com/picatz.png?size=50" width="50"/>
|
||||
</a>
|
||||
<a href="https://github.com/tylertravisty" style="width:50px">
|
||||
<img src="https://github.com/tylertravisty.png?size=50" width="50"/>
|
||||
</a>
|
||||
<a href="https://github.com/akhudek" style="width:50px">
|
||||
<img src="https://github.com/akhudek.png?size=50" width="50"/>
|
||||
</a>
|
||||
<a href="https://github.com/trea" style="width:50px">
|
||||
<img src="https://github.com/trea.png?size=50" width="50"/>
|
||||
</a>
|
||||
<a href="https://github.com/LanguageAgnostic" style="width:55px">
|
||||
<img src="https://github.com/LanguageAgnostic.png?size=55" width="55"/>
|
||||
</a>
|
||||
<a href="https://github.com/fcjr" style="width:55px">
|
||||
<img src="https://github.com/fcjr.png?size=55" width="55"/>
|
||||
</a>
|
||||
<a href="https://github.com/nickarellano" style="width:60px">
|
||||
<img src="https://github.com/nickarellano.png?size=60" width="60"/>
|
||||
</a>
|
||||
<a href="https://github.com/bglw" style="width:65px">
|
||||
<img src="https://github.com/bglw.png?size=65" width="65"/>
|
||||
</a>
|
||||
<a href="https://github.com/jugglingjsons" style="width:50px">
|
||||
<img src="https://github.com/jugglingjsons.png?size=50" width="50"/>
|
||||
</a>
|
||||
<a href="https://github.com/marcus-crane" style="width:50px">
|
||||
<img src="https://github.com/marcus-crane.png?size=50" width="50"/>
|
||||
</a>
|
||||
`,
|
||||
}}
|
||||
/>
|
||||
|
||||
## Contributors
|
||||
|
||||
import Contributors from "react-contributors";
|
||||
|
||||
<Contributors owner="wailsapp" repo="wails" />
|
||||
|
||||
## Special Mentions
|
||||
|
||||
- [John Chadwick](https://github.com/jchv) - His amazing work on [go-webview2](https://github.com/jchv/go-webview2) and
|
||||
[go-winloader](https://github.com/jchv/go-winloader) have made the Windows version possible.
|
||||
- [Tad Vizbaras](https://github.com/tadvi) - His winc project was the first step down the path to a pure Go Wails.
|
||||
- [Mat Ryer](https://github.com/matryer) - For advice, support and bants.
|
||||
- [Dustin Krysak](https://wiki.ubuntu.com/bashfulrobot) - His support and feedback has been invaluable.
|
||||
- [Justen Walker](https://github.com/justenwalker/) - For helping wrangle COM issues which got v2 over the line.
|
||||
- [Wang, Chi](https://github.com/patr0nus/) - The DeskGap project was a huge influence on the direction of Wails v2.
|
||||
- [Serge Zaitsev](https://github.com/zserge) - Whilst Wails does not use the Webview project, it is still a source of inspiration.
|
||||
4
website/docs/gettingstarted/_category_.json
Normal file
4
website/docs/gettingstarted/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 10
|
||||
}
|
||||
19
website/docs/gettingstarted/building.mdx
Normal file
19
website/docs/gettingstarted/building.mdx
Normal file
@@ -0,0 +1,19 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Compiling your Project
|
||||
|
||||
From the project directory, run `wails build`.
|
||||
This will compile your project and save the production-ready binary in the `build/bin` directory.
|
||||
|
||||
If you run the binary, you should see the default application:
|
||||
|
||||
<div class="text--center">
|
||||
<img src="/img/defaultproject.png" width="50%" style={{"box-shadow": "rgb(255 255 255 / 20%) 0px 4px 8px 0px, rgb(104 104 104) 0px 6px 20px 0px"}}/>
|
||||
</div>
|
||||
<br/>
|
||||
|
||||
|
||||
For more details on compilation options, please refer to the [CLI Reference](/docs/reference/cli#build).
|
||||
|
||||
15
website/docs/gettingstarted/development.mdx
Normal file
15
website/docs/gettingstarted/development.mdx
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Developing your Application
|
||||
|
||||
You can run your application in development mode by running `wails dev` from your project directory. This will do the following things:
|
||||
|
||||
- Build your application and run it
|
||||
- Watch for modifications in your Go files and rebuild/re-run on change
|
||||
- Sets up a [webserver](http://localhost:34115) that will serve your application over a browser. This allows you to use your favourite browser extensions. You can even call your Go code from the console.
|
||||
|
||||
To get started, run `wails dev` in the project directory. More information on this can be found [here](/docs/reference/cli#dev).
|
||||
|
||||
Coming soon: Tutorial
|
||||
53
website/docs/gettingstarted/firstproject.mdx
Normal file
53
website/docs/gettingstarted/firstproject.mdx
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Creating a Project
|
||||
|
||||
## Project Generation
|
||||
|
||||
Now that the CLI is installed, you can generate a new project by using the `wails init` command.
|
||||
|
||||
To get up and running quickly, you can generate a default project by running `wails init -n myproject`. This will
|
||||
create a directory called `myproject` and populate it with the default template.
|
||||
|
||||
Other project templates are available and can be listed using `wails init -l`.
|
||||
|
||||
To see the other options available, you can run `wails init -help`.
|
||||
More details can be found in the [CLI Reference](/docs/reference/cli#init).
|
||||
|
||||
## Project Layout
|
||||
|
||||
Wails projects have the following layout:
|
||||
|
||||
```
|
||||
.
|
||||
├── build/
|
||||
│ ├── appicon.png
|
||||
│ ├── darwin/
|
||||
│ └── windows/
|
||||
├── frontend/
|
||||
├── go.mod
|
||||
├── go.sum
|
||||
├── main.go
|
||||
└── wails.json
|
||||
```
|
||||
|
||||
### Project structure rundown
|
||||
|
||||
- `/main.go` - The main application
|
||||
- `/frontend/` - Frontend project files
|
||||
- `/build/` - Project build directory
|
||||
- `/build/appicon.png` - The application icon
|
||||
- `/build/darwin/` - Mac specific project files
|
||||
- `/build/windows/` - Windows specific project files
|
||||
- `/wails.json` - The project configuration
|
||||
- `/go.mod` - Go module file
|
||||
- `/go.sum` - Go module checksum file
|
||||
|
||||
The `frontend` directory has nothing specific to Wails and can be any frontend project of your choosing.
|
||||
|
||||
The `build` directory is used during the build process. These files may be updated to customise your builds. If
|
||||
files are removed from the build directory, default versions will be regenerated.
|
||||
|
||||
The default module name in `go.mod` is "changeme". You should change this to something more appropriate.
|
||||
71
website/docs/gettingstarted/installation.mdx
Normal file
71
website/docs/gettingstarted/installation.mdx
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
- Windows 10
|
||||
- MacOS x64 & arm64 (due October '21)
|
||||
- Linux (due December '21)
|
||||
|
||||
## Dependencies
|
||||
|
||||
Wails has a number of common dependencies that are required before installation:
|
||||
|
||||
- Go 1.17+
|
||||
- npm (Node 14+)
|
||||
|
||||
### Go
|
||||
|
||||
Download Go from the [Go Downloads Page](https://golang.org/dl/).
|
||||
|
||||
Ensure that you follow the official [Go installation instructions](https://golang.org/doc/install#install). You will also need to ensure that your `PATH` environment variable also includes the path to your `~/go/bin` directory. Restart your terminal and do the following checks:
|
||||
|
||||
* Check Go is installed correctly: `go version`
|
||||
* Check "~/go/bin" is in your PATH variable: `echo $PATH | grep go/bin`
|
||||
|
||||
### npm
|
||||
|
||||
Download NPM from the [Node Downloads Page](https://nodejs.org/en/download/). It is best to use the latest release as that is what we generally test against.
|
||||
|
||||
Run `npm --version` to verify.
|
||||
|
||||
## Platform Specific Dependencies
|
||||
|
||||
You will also need to install platform specific dependencies:
|
||||
|
||||
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">
|
||||
Coming Soon...
|
||||
</TabItem>
|
||||
<TabItem value="Windows">
|
||||
Wails requires that the <a href='https://developer.microsoft.com/en-us/microsoft-edge/webview2/'>WebView2</a> runtime is installed.
|
||||
Some Windows installations will already have this installed. You can check using the `wails doctor` command (see below).
|
||||
</TabItem>
|
||||
<TabItem value="Linux">
|
||||
Coming Soon...
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Optional Dependencies
|
||||
|
||||
- [UPX](https://upx.github.io/) for compressing your applications.
|
||||
|
||||
## Installing Wails
|
||||
|
||||
Run `go get github.com/wailsapp/wails/v2/cmd/wails` to install the Wails CLI.
|
||||
|
||||
## System Check
|
||||
|
||||
Running `wails doctor` will check if you have the correct dependencies installed. If not, it will advise on what is missing and help on how to rectify any problems.
|
||||
4
website/docs/guides/_category_.json
Normal file
4
website/docs/guides/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Guides",
|
||||
"position": 50
|
||||
}
|
||||
179
website/docs/guides/application-development.mdx
Normal file
179
website/docs/guides/application-development.mdx
Normal file
@@ -0,0 +1,179 @@
|
||||
|
||||
# Application Development
|
||||
|
||||
There are no hard and fast rules for developing applications with Wails, but there are some basic guidelines.
|
||||
|
||||
## Application Setup
|
||||
|
||||
The pattern used by the default templates are that `main.go` is used for configuring and running the application, whilst
|
||||
`app.go` is used for defining the application logic.
|
||||
|
||||
The `app.go` file will define a struct that has 2 methods which act as hooks into the main application:
|
||||
|
||||
```go title="app.go"
|
||||
type App struct {
|
||||
ctx context.Context
|
||||
}
|
||||
|
||||
func NewApp() *App {
|
||||
return &App{}
|
||||
}
|
||||
|
||||
func (a *App) startup(ctx context.Context) {
|
||||
a.ctx = ctx
|
||||
}
|
||||
|
||||
func (a *App) shutdown(ctx context.Context) {
|
||||
}
|
||||
```
|
||||
|
||||
- The startup method is called as soon as Wails allocates the resources it needs and is a good place for creating resources,
|
||||
setting up event listeners and anything else the application needs at startup.
|
||||
It is given a `context.Context` which is usually saved in a struct field. This context is needed for calling the
|
||||
[runtime](/docs/reference/runtime/intro). If this method returns an error, the application will terminate.
|
||||
In dev mode, the error will be output to the console.
|
||||
|
||||
- The shutdown method will be called by Wails right at the end of the shutdown process. This is a good place to deallocate
|
||||
memory and perform any shutdown tasks.
|
||||
|
||||
The `main.go` file generally consists of a single call to `wails.Run()`, which accepts the application configuration.
|
||||
The pattern used by the templates is that before the call to `wails.Run()`, an instance of the struct we defined in
|
||||
`app.go` is created and saved in a variable called `app`. This configuration is where we add our callbacks:
|
||||
|
||||
```go {3,9,10} title="main.go"
|
||||
func main() {
|
||||
|
||||
app := NewApp()
|
||||
|
||||
err := wails.Run(&options.App{
|
||||
Title: "My App",
|
||||
Width: 800,
|
||||
Height: 600,
|
||||
OnStartup: app.startup,
|
||||
OnShutdown: app.shutdown,
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
More information on application lifecycle hooks can be found [here](/docs/howdoesitwork#application-lifecycle-callbacks).
|
||||
|
||||
## Binding Methods
|
||||
|
||||
It is likely that you will want to call Go methods from the frontend. This is normally done by adding public methods to
|
||||
the already defined struct in `app.go`:
|
||||
|
||||
```go {16-18} title="app.go"
|
||||
type App struct {
|
||||
ctx context.Context
|
||||
}
|
||||
|
||||
func NewApp() *App {
|
||||
return &App{}
|
||||
}
|
||||
|
||||
func (a *App) startup(ctx context.Context) {
|
||||
a.ctx = ctx
|
||||
}
|
||||
|
||||
func (a *App) shutdown(ctx context.Context) {
|
||||
}
|
||||
|
||||
func (a *App) Greet(name string) string {
|
||||
return fmt.Printf("Hello %s!", name)
|
||||
}
|
||||
```
|
||||
|
||||
In the main application configuration, the `Bind` key is where we can tell Wails what we want to bind:
|
||||
|
||||
```go {11-13} title="main.go"
|
||||
func main() {
|
||||
|
||||
app := NewApp()
|
||||
|
||||
err := wails.Run(&options.App{
|
||||
Title: "My App",
|
||||
Width: 800,
|
||||
Height: 600,
|
||||
OnStartup: app.startup,
|
||||
OnShutdown: app.shutdown,
|
||||
Bind: []interface{}{
|
||||
app,
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
This will bind all public methods in our `App` struct (it will never bind the startup and shutdown methods).
|
||||
|
||||
More information on Binding can be found [here](/docs/howdoesitwork#method-binding).
|
||||
|
||||
## Application Menu
|
||||
|
||||
Wails supports adding a menu to your application. This is done by passing a [Menu](/docs/reference/menus#menu) struct
|
||||
to application config. It's common to use a method that returns a Menu, and even more common for that to be a method on
|
||||
the `App` struct used for the lifecycle hooks.
|
||||
|
||||
```go {11} title="main.go"
|
||||
func main() {
|
||||
|
||||
app := NewApp()
|
||||
|
||||
err := wails.Run(&options.App{
|
||||
Title: "My App",
|
||||
Width: 800,
|
||||
Height: 600,
|
||||
OnStartup: app.startup,
|
||||
OnShutdown: app.shutdown,
|
||||
Menu: app.menu(),
|
||||
Bind: []interface{}{
|
||||
app,
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Assets
|
||||
|
||||
The great thing about the way Wails v2 handles assets is that it doesn't! The only thing you need to give Wails is an
|
||||
`embed.FS`. How you get to that is entirely up to you. You can use vanilla html/css/js files like the vanilla template.
|
||||
You could have some complicated build system, it doesn't matter.
|
||||
|
||||
When `wails build` is run, it will check the `wails.json` project file at the project root. There are 2 keys in the
|
||||
project file that are read:
|
||||
|
||||
- "frontend:install"
|
||||
- "frontend:build"
|
||||
|
||||
The first, if given, will be executed in the `frontend` directory to install the node modules.
|
||||
The second, if given, will be executed in the `frontend` directory to build the frontend project.
|
||||
|
||||
If these 2 keys aren't given, then Wails does absolutely nothing with the frontend. It is only expecting that `embed.FS`.
|
||||
|
||||
## Live Reloading
|
||||
|
||||
Running `wails dev` will start a file watcher in your project directory. By default, if any file changes, wails checks
|
||||
if it was an application file (default: `.go`, configurable with `-e` flag). If it was, then it will rebuild your
|
||||
application and relaunch it. If the changed file was in the `assetdir` directory, it will issue a reload.
|
||||
|
||||
Some frameworks come with their own live-reloading server, however they will not be able to take advantage of the Wails
|
||||
Go bindings. In this scenario, it is best to run a watcher script that rebuilds the project into the build directory, which
|
||||
Wails will be watching. For an example, see the default svelte template that uses [rollup](https://rollupjs.org/guide/en/).
|
||||
For [create-react-app](https://create-react-app.dev/), it's possible to use
|
||||
[this script](https://gist.github.com/int128/e0cdec598c5b3db728ff35758abdbafd) to achieve a similar result.
|
||||
|
||||
## Go Module
|
||||
|
||||
The default Wails templates generate a `go.mod` file that contains the module name "changeme". You should change this
|
||||
to something more appropriate after project generation.
|
||||
39
website/docs/guides/developing-wails.mdx
Normal file
39
website/docs/guides/developing-wails.mdx
Normal file
@@ -0,0 +1,39 @@
|
||||
|
||||
# Contributing
|
||||
|
||||
This page is a guide on how to contribute to the Wails project.
|
||||
|
||||
First, a word of warning: Wails v2 has been through a number of iterations and pivots. There is a lot of code that
|
||||
is either on hold or deprecated. Reading the whole project and trying to understand it may be confusing. This document
|
||||
aims to focus on what is current and how to understand that.
|
||||
|
||||
## Bugs
|
||||
|
||||
For raising bugs, please open a ticket on GitHub and give it the \[v2\] label. Include the output of `wails doctor`
|
||||
in the ticket to help us understand your environment.
|
||||
|
||||
For fixing bugs, please comment on a ticket that you'd like to take it on and we will put a label on the ticket.
|
||||
It is best to use Windows as it is done in pure Go, making debugging much easier.
|
||||
|
||||
## Features
|
||||
|
||||
To request a new feature, raise a ticket so that it may be discussed. The ticket should be given the
|
||||
"Feature Request" label. These will be discussed and if selected for development will be given the label
|
||||
"Ready for Development".
|
||||
|
||||
To implement a new feature, raise a ticket as above or select a ticket with the "Ready for Development" label.
|
||||
|
||||
When raising a PR, be mindful to state what platforms the PR has been tested on. Any new feature will not be accepted unless it works
|
||||
on all platforms (if it can).
|
||||
|
||||
:::warning What not to do
|
||||
|
||||
PRs for features with no tickets aren't helpful as there's no context to the PR and it will not be prioritised.
|
||||
|
||||
:::
|
||||
|
||||
## Documentation
|
||||
|
||||
Contributing to the documentation is easy by clicking on the "Edit this page" link on any of the pages. Documentation
|
||||
updates can be done ad-hoc, without a ticket.
|
||||
|
||||
35
website/docs/guides/frameless.mdx
Normal file
35
website/docs/guides/frameless.mdx
Normal file
@@ -0,0 +1,35 @@
|
||||
|
||||
# Frameless Applications
|
||||
|
||||
Wails supports applications with no frame. This can be achieved by using the [frameless](/docs/reference/options#frameless)
|
||||
field in [Application Options](/docs/reference/options#application-options).
|
||||
|
||||
Wails offers a simple solution for dragging the window: Any HTML element that has the attribute "data-wails-drag" will
|
||||
act as a "drag handle". This property applies to all nested elements. If you need to indicate that a nested element
|
||||
should not drag, then use the attribute 'data-wails-no-drag' on that element.
|
||||
|
||||
The default vanilla template uses this, even though it is not frameless. The whole `body` element is tagged as draggable.
|
||||
The `<div id="input" data-wails-no-drag>` is tagged as being not draggable.
|
||||
|
||||
```html
|
||||
<html>
|
||||
<head>
|
||||
<link rel="stylesheet" href="/main.css" />
|
||||
</head>
|
||||
|
||||
<body data-wails-drag>
|
||||
<div id="logo"></div>
|
||||
<div id="input" data-wails-no-drag>
|
||||
<input id="name" type="text" />
|
||||
<button onclick="greet()">Greet</button>
|
||||
</div>
|
||||
<div id="result"></div>
|
||||
|
||||
<script src="/main.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
:::info Fullscreen
|
||||
If you allow your application to go fullscreen, this drag functionality will be disabled.
|
||||
:::
|
||||
116
website/docs/guides/ides.mdx
Normal file
116
website/docs/guides/ides.mdx
Normal file
@@ -0,0 +1,116 @@
|
||||
|
||||
# IDEs
|
||||
|
||||
Wails aims to provide a great development experience. To that aim, we now support generating IDE specific configuration
|
||||
to provide smoother project setup.
|
||||
|
||||
Currently, we support [Visual Studio Code](https://code.visualstudio.com/) but aim to support other IDEs such as Goland.
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
<p className="text--center">
|
||||
<img src="/img/vscode.png" style={{"width": "75%"}}></img>
|
||||
</p>
|
||||
|
||||
When generating a project using the `-vscode` flag, IDE files will be created alongside the other project files.
|
||||
These files are placed into the `.vscode` directory and provide the correct configuration for debugging your application.
|
||||
|
||||
The 2 files generated are `tasks.json` and `launch.json`. Below are the files generated for the default vanilla project:
|
||||
|
||||
```json title="tasks.json"
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "build",
|
||||
"type": "shell",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
"command": "go",
|
||||
"args": ["build", "-tags", "dev", "-gcflags", "all=-N -l", "-o", "build/bin/myproject.exe"]
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json title="launch.json"
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Wails: Debug myproject",
|
||||
"type": "go",
|
||||
"request": "launch",
|
||||
"mode": "exec",
|
||||
"program": "${workspaceFolder}/build/bin/myproject.exe",
|
||||
"preLaunchTask": "build",
|
||||
"cwd": "${workspaceFolder}",
|
||||
"env": {},
|
||||
"args": ["-assetdir", "frontend/src"]
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Configuring the install and build steps
|
||||
|
||||
The `tasks.json` file is simple for the default project as there is no `npm install` or `npm run build` step needed.
|
||||
For projects that have a frontend build step, such as the svelte template, we would need to edit `tasks.json` to
|
||||
add the install and build steps:
|
||||
|
||||
```json title="tasks.json"
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "npm install",
|
||||
"type": "npm",
|
||||
"script": "install",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}/frontend"
|
||||
},
|
||||
"presentation": {
|
||||
"clear": true,
|
||||
"panel": "shared",
|
||||
"showReuseMessage": false
|
||||
},
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "npm run build",
|
||||
"type": "npm",
|
||||
"script": "build",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}/frontend"
|
||||
},
|
||||
"presentation": {
|
||||
"clear": true,
|
||||
"panel": "shared",
|
||||
"showReuseMessage": false
|
||||
},
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "build",
|
||||
"type": "shell",
|
||||
"options": {
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
"command": "go",
|
||||
"args": ["build", "-tags", "dev", "-gcflags", "all=-N -l", "-o", "build/bin/vscode.exe"],
|
||||
"dependsOn":[
|
||||
"npm install",
|
||||
"npm run build"
|
||||
]
|
||||
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
:::info Future Enhancement
|
||||
|
||||
In the future, we hope to generate a `tasks.json` that includes the install and build steps automatically.
|
||||
|
||||
:::
|
||||
99
website/docs/guides/manual-builds.mdx
Normal file
99
website/docs/guides/manual-builds.mdx
Normal file
@@ -0,0 +1,99 @@
|
||||
|
||||
# Manual builds
|
||||
|
||||
The Wails CLI does a lot of heavy lifting for the project, but sometimes it's desirable to manually build your project.
|
||||
This document will discuss the different operations the CLI does and how this may be achieved in different ways.
|
||||
|
||||
## Build Process
|
||||
|
||||
When either `wails build` or `wails dev` are used, the Wails CLI performs a common build process:
|
||||
|
||||
- Install frontend dependencies
|
||||
- Build frontend project
|
||||
- Generate build assets
|
||||
- Compile application
|
||||
- [optional] Compress application
|
||||
|
||||
### Install frontend dependencies
|
||||
|
||||
#### CLI Steps
|
||||
|
||||
- If the `-s` flag is given, this step is skipped
|
||||
- Checks `wails.json` to see if there is an install command in the key `frontend:install`
|
||||
- If there isn't, it skips this step
|
||||
- If there is, it checks if `package.json` exists in the frontend directory. If it doesn't exist, it skips this step
|
||||
- An MD5 sum is generated from the `package.json` file contents
|
||||
- It checks for the existence of `package.json.md5` and if it exists, will compare the contents of it (an MD5 sum)
|
||||
with the one generated to see if the contents have changed. If they are the same, this step is skipped
|
||||
- If `package.json.md5` does not exist, it creates it using the generated MD5 sum
|
||||
- If a build is now required, or `node_modules` does not exist, or the `-f` flag is given, the install command is
|
||||
executed in the frontend directory
|
||||
|
||||
#### Manual Steps
|
||||
|
||||
This step could be done from the command line or a script with `npm install`.
|
||||
|
||||
### Build frontend project
|
||||
|
||||
#### Wails CLI
|
||||
|
||||
- If the `-s` flag is given, this step is skipped
|
||||
- Checks `wails.json` to see if there is a build command in the key `frontend:build`
|
||||
- If there isn't, it skips this step
|
||||
- If there is, it is executed in the frontend directory
|
||||
|
||||
#### Manual Steps
|
||||
|
||||
This step could be done from the command line or a script with `npm run build` or whatever the frontend build script is.
|
||||
|
||||
### Generate assets
|
||||
|
||||
#### Wails CLI
|
||||
|
||||
- If `-nopackage` flag is set, this stage is skipped
|
||||
- If the `build/appicon.png` file does not exist, a default one is created
|
||||
- For Windows, see [Bundling for Windows](#windows)
|
||||
- If `build/windows/icon.ico` does not exist, it will create it from the `build/appicon.png` image.
|
||||
|
||||
##### Windows
|
||||
|
||||
- It creates icon sizes of 256, 128, 64, 48, 32 and 16. This is done using [winicon](https://github.com/leaanthony/winicon).
|
||||
- If the `build/windows/<projectname>.manifest` file does not exist, it creates it from a default version.
|
||||
- Compiles the application as a production build (above)
|
||||
- Uses [winres](https://github.com/tc-hib/winres) to bundle the icon and manifest into a `.syso` file ready for linking.
|
||||
|
||||
#### Manual Steps
|
||||
|
||||
- Create `icon.ico` using the [winicon](https://github.com/leaanthony/winicon) CLI tool (or any other tool).
|
||||
- Create / Update a `.manifest` file for your application
|
||||
- Use the [winres CLI](https://github.com/tc-hib/go-winres) to generate a `.syso` file.
|
||||
|
||||
### Compile application
|
||||
|
||||
#### Wails CLI
|
||||
|
||||
- If the `-clean` flag is provided, the `build` directory is deleted and recreated
|
||||
- For `wails dev`, the following default Go flags are used: `-tags dev -gcflags "all=-N -l"`
|
||||
- For `wails build`, the following default Go flags are used: `-tags desktop,production -ldflags "-w -s"`
|
||||
- On Windows, `-ldflags "-w -h -H windowsgui"`
|
||||
- Additional tags passed to the CLI using `-tags` are added to the defaults
|
||||
- Additional ldflags passed to the CLI using `-ldflags` are added to the defaults
|
||||
- The `-o` flag is passed through
|
||||
- The Go compiler specified by `-compiler` will be used for compilation
|
||||
|
||||
#### Manual steps
|
||||
|
||||
- For dev build, the minimum command would be: `go build -tags dev -gcflags "all=-N -l"`
|
||||
- For production build, the minimum command would be: `go build -tags desktop,production -ldflags "-w -s -H windowsgui"`
|
||||
- Ensure that you compile in the same directory as the `.syso` file
|
||||
|
||||
### Compress application
|
||||
|
||||
#### Wails CLI
|
||||
|
||||
- If the `-upx` flag has been given, the `upx` program will be run to compress the application with the default settings
|
||||
- If `-upxflags` is also passed, these flags are used instead of the default ones
|
||||
|
||||
#### Manual steps
|
||||
|
||||
- Run `upx [flags]` manually to compress the application.
|
||||
205
website/docs/guides/migrating.mdx
Normal file
205
website/docs/guides/migrating.mdx
Normal file
@@ -0,0 +1,205 @@
|
||||
|
||||
# Migrating from v1
|
||||
|
||||
## Overview
|
||||
|
||||
Wails v2 is a significant change from v1. This document aims to highlight the changes and the steps in migrating an existing project.
|
||||
|
||||
### Creating the Application
|
||||
|
||||
In v1, the main application is created using `wails.CreateApp`, bindings are added with `app.Bind`, then the
|
||||
application is run using `app.Run()`.
|
||||
|
||||
Example:
|
||||
|
||||
```go title="v1"
|
||||
app := wails.CreateApp(&wails.AppConfig{
|
||||
Title: "MyApp",
|
||||
Width: 1024,
|
||||
Height: 768,
|
||||
JS: js,
|
||||
CSS: css,
|
||||
Colour: "#131313",
|
||||
})
|
||||
app.Bind(basic)
|
||||
app.Run()
|
||||
```
|
||||
|
||||
In v2, there is just a single method, `wails.Run()`, that accepts [application options](/docs/reference/options#application-options).
|
||||
|
||||
```go title="v2"
|
||||
err := wails.Run(&options.App{
|
||||
Title: "MyApp",
|
||||
Width: 800,
|
||||
Height: 600,
|
||||
Assets: assets,
|
||||
Bind: []interface{}{
|
||||
basic,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Binding
|
||||
|
||||
In v1, it was possible to bind both arbitrary functions and structs. In v2, this has been simplified to only binding structs.
|
||||
The struct instances that were previously passed to the `Bind()` method in v1, are now specified in the `Bind` field of
|
||||
the [application options](/docs/reference/options#application-options):
|
||||
|
||||
```go title="v1"
|
||||
app := wails.CreateApp(/* options */)
|
||||
app.Bind(basic)
|
||||
```
|
||||
|
||||
```go title="v2"
|
||||
err := wails.Run(&options.App{
|
||||
/* other options */
|
||||
Bind: []interface{}{
|
||||
basic,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
In v1, bound methods were available to the frontend at `window.backend`. This has changed to `window.go`.``
|
||||
|
||||
### Application Lifecycle
|
||||
|
||||
In v1, there were 2 special methods in a bound struct: `WailsInit()` and `WailsShutdown()`. These have
|
||||
been replaced with 3 lifecycle hooks as part of the [application options](/docs/reference/options#application-options):
|
||||
|
||||
- [OnStartup](/docs/reference/options#onstartup)
|
||||
- [OnShutdown](/docs/reference/options#onshutdown)
|
||||
- [OnDomReady](/docs/reference/options#ondomready)
|
||||
|
||||
Note: [OnDomReady](/docs/reference/options#ondomready) replaces the `wails:ready` system event in v1.
|
||||
|
||||
These methods can be standard functions, but a common practice is to have them part of a struct:
|
||||
|
||||
```go title="v2"
|
||||
basic := NewBasicApp()
|
||||
err := wails.Run(&options.App{
|
||||
/* Other Options */
|
||||
OnStartup: basic.startup,
|
||||
OnShutdown: basic.shutdown,
|
||||
OnDomReady: basic.domready,
|
||||
})
|
||||
...
|
||||
type Basic struct {
|
||||
ctx context.Context
|
||||
}
|
||||
func (b *Basic) startup(ctx context.Context) {
|
||||
b.ctx = ctx
|
||||
}
|
||||
...
|
||||
```
|
||||
|
||||
### Runtime
|
||||
|
||||
The runtime in v2 is much richer than v1 with support for menus, window manipulation
|
||||
and better dialogs. The signature of the methods has changed slightly - please refer
|
||||
the the [Runtime Reference](/docs/reference/runtime/intro).
|
||||
|
||||
In v1, the [runtime](/docs/reference/runtime/intro) was available via a struct passed to `WailsInit()`.
|
||||
In v2, the runtime has been moved out to its own package. Each method in the runtime takes the
|
||||
`context.Context` that is passed to the [OnStartup](/docs/reference/options#onstartup) method.
|
||||
|
||||
```go title="Runtime Example"
|
||||
package main
|
||||
|
||||
import "github.com/wailsapp/wails/v2/pkg/runtime"
|
||||
|
||||
type Basic struct {
|
||||
ctx context.Context
|
||||
}
|
||||
|
||||
// startup is called at application startup
|
||||
func (a *App) startup(ctx context.Context) {
|
||||
a.ctx = ctx
|
||||
runtime.LogInfo(ctx, "Application Startup called!")
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Assets
|
||||
|
||||
The _biggest_ change in v2 is how assets are handled.
|
||||
|
||||
In v1, assets were passed via 2 application options:
|
||||
|
||||
- `JS` - The application's Javascript
|
||||
- `CSS` - The application's CSS
|
||||
|
||||
This meant that the responsibility of generating a single JS and CSS file was on the
|
||||
developer. This essentially required the use of complicated packers such as webpack.
|
||||
|
||||
In v2, Wails makes no assumptions about your frontend assets, just like a webserver.
|
||||
All of your application assets are passed to the application options as an `embed.FS`.
|
||||
|
||||
**This means there is no requirement to bundle your assets, encode images as Base64 or
|
||||
attempt the dark art of bundler configuration to use custom fonts**.
|
||||
|
||||
At startup, Wails
|
||||
will scan the given `embed.FS` for `index.html` and use its location as the root path
|
||||
for all the other application assets - just like a webserver would.
|
||||
|
||||
Example: An application has the following project layout. All final assets are placed in the
|
||||
`frontend/dist` directory:
|
||||
|
||||
```shell
|
||||
.
|
||||
├── build/
|
||||
├── frontend/
|
||||
│ └── dist/
|
||||
│ ├── index.html
|
||||
│ ├── main.js
|
||||
│ ├── main.css
|
||||
│ └── logo.svg
|
||||
├── main.go
|
||||
└── wails.json
|
||||
```
|
||||
|
||||
Those assets may be used by the application by simply creating an `embed.FS`:
|
||||
|
||||
```go title="Assets Example"
|
||||
//go:embed frontend/dist
|
||||
var assets embed.FS
|
||||
|
||||
func main() {
|
||||
err := wails.Run(&options.App{
|
||||
/* Other Options */
|
||||
Assets: assets,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Of course, bundlers can be used if you wish to. The only requirement is to pass
|
||||
the final application assets directory to Wails using an `embed.FS` in the `Assets`
|
||||
key of the [application options](/docs/reference/options#application-options).
|
||||
|
||||
### Project Configuration
|
||||
|
||||
In v1, the project configuration was stored in the `project.json` file in the project root.
|
||||
In v2, the project configuration is stored in the `wails.json` file in the project root.
|
||||
|
||||
The format of the file is slightly different. Here is a comparison:
|
||||
|
||||
<p align="center">
|
||||
|
||||
| v1 | v2 | Notes |
|
||||
| ------------------ | ---------------- | --------------------------------------------------- |
|
||||
| name | name | |
|
||||
| description | | Removed |
|
||||
| author / name | author / name | |
|
||||
| author / email | author / email | |
|
||||
| version | version | |
|
||||
| binaryname | outputfilename | Changed |
|
||||
| frontend / dir | | Removed |
|
||||
| frontend / install | frontend:install | Changed |
|
||||
| frontend / build | frontend:build | Changed |
|
||||
| frontend / bridge | | Removed |
|
||||
| frontend / serve | | Removed |
|
||||
| tags | | Removed |
|
||||
| | wailsjsdir | The directory to generate wailsjs modules |
|
||||
| | assetdir | The directory of the frontend assets for `dev` mode |
|
||||
|
||||
</p>
|
||||
|
||||
95
website/docs/guides/templates.mdx
Normal file
95
website/docs/guides/templates.mdx
Normal file
@@ -0,0 +1,95 @@
|
||||
|
||||
# Templates
|
||||
|
||||
Wails generates projects from pre-created templates. In v1, this was a difficult to maintain set of projects that were
|
||||
subject to going out of date. In v2, to empower the community, a couple of new features have been added for templates:
|
||||
|
||||
- Ability to generate projects from [Remote Templates](/docs/reference/cli#remote-templates)
|
||||
- Tooling to help create your own templates
|
||||
|
||||
## Creating Templates
|
||||
|
||||
To create a template, you can use the `wails generate template` command. To generate a default template, run:
|
||||
|
||||
`wails generate template -name mytemplate `
|
||||
|
||||
This creates the directory "mytemplate" with default files:
|
||||
|
||||
```shell title=mytemplate/
|
||||
.
|
||||
|-- NEXTSTEPS.md
|
||||
|-- README.md
|
||||
|-- app.tmpl.go
|
||||
|-- frontend
|
||||
| `-- dist
|
||||
| |-- assets
|
||||
| | |-- fonts
|
||||
| | | |-- OFL.txt
|
||||
| | | `-- nunito-v16-latin-regular.woff2
|
||||
| | `-- images
|
||||
| | `-- logo-dark.svg
|
||||
| |-- index.html
|
||||
| |-- main.css
|
||||
| `-- main.js
|
||||
|-- go.mod.tmpl
|
||||
|-- main.tmpl.go
|
||||
|-- template.json
|
||||
`-- wails.tmpl.json
|
||||
```
|
||||
|
||||
### Template Overview
|
||||
|
||||
The default template consists of the following files and directories:
|
||||
|
||||
| Filename / Dir | Description |
|
||||
| --------------- | -------------------------------------------- |
|
||||
| NEXTSTEPS.md | Instructions on how to complete the template |
|
||||
| README.md | The README published with the template |
|
||||
| app.tmpl.go | `app.go` template file |
|
||||
| frontend/ | The directory containing frontend assets |
|
||||
| go.mod.tmpl | `go.mod` template file |
|
||||
| main.tmpl.go | `main.go` template file |
|
||||
| template.json | The template metadata |
|
||||
| wails.tmpl.json | `wails.json` template file |
|
||||
|
||||
At this point it is advisable to follow the steps in `NEXTSTEPS.md`.
|
||||
|
||||
## Creating a Template from an Existing Project
|
||||
|
||||
It's possible to create a template from an existing frontend project by passing the path to the project when generating
|
||||
the template. We will now walk through how to create a Vue 3 template:
|
||||
|
||||
- Install the vue cli: `npm install -g @vue/cli`
|
||||
- Create the default project: `vue create vue3-base`
|
||||
- Select `Default (Vue 3) ([Vue 3] babel, eslint)`
|
||||
- After the project has been generated, run:
|
||||
|
||||
```shell
|
||||
> wails generate template -name wails-vue3-template -frontend .\vue3-base\
|
||||
Extracting base template files...
|
||||
Migrating existing project files to frontend directory...
|
||||
Updating package.json data...
|
||||
Renaming package.json -> package.tmpl.json...
|
||||
Updating package-lock.json data...
|
||||
Renaming package-lock.json -> package-lock.tmpl.json...
|
||||
```
|
||||
|
||||
- The template may now be customised as specified in the `NEXTSTEPS.md` file
|
||||
- Once the files are ready, it can be tested by running: `wails init -n my-vue3-project -t .\wails-vue3-template\`
|
||||
- To test the new project, run: `cd my-vue3-project` then `wails build`
|
||||
- Once the project has compiled, run it: `.\build\bin\my-vue3-project.exe`
|
||||
- You should have a fully functioning Vue3 application:
|
||||
|
||||
<div className="text--center">
|
||||
<img src="/img/vue3-template.png" width="50%" />
|
||||
</div>
|
||||
|
||||
## Publishing Templates
|
||||
|
||||
Publishing a template is simply pushing the files to GitHub. The following best practice is encouraged:
|
||||
|
||||
- Remove any unwanted files and directories (such as `.git`) from your frontend directory
|
||||
- Ensure that `template.json` is complete, especially `helpurl`
|
||||
- Push the files to GitHub
|
||||
- Create a PR on the [Community Templates](/docs/community/templates) page
|
||||
- Announce the template on the [Template Announcement](https://github.com/wailsapp/wails/discussions/825) discussion board
|
||||
37
website/docs/guides/windows.mdx
Normal file
37
website/docs/guides/windows.mdx
Normal file
@@ -0,0 +1,37 @@
|
||||
|
||||
# Windows
|
||||
|
||||
This page has miscellaneous guides related to developing Wails applications for Windows.
|
||||
|
||||
## Handling the WebView2 Runtime Dependency
|
||||
|
||||
Wails applications built for Windows have a runtime requirement on the Microsoft [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
|
||||
Windows 11 will have this installed by default, but some machines won't. Wails offers an easy approach to dealing with this dependency.
|
||||
|
||||
By using the `-webview2` flag when building, you can decide what your application will do when a suitable runtime is not detected (including if the installed runtime is too old).
|
||||
The four options are:
|
||||
|
||||
1. Download
|
||||
2. Embed
|
||||
3. Browser
|
||||
4. Error
|
||||
|
||||
### Download
|
||||
|
||||
This option will prompt the user that no suitable runtime has been found and then offer to download and run the official
|
||||
bootstrapper from Microsoft's WebView2 site. If the user proceeds, the official bootstrapper will be downloaded and run.
|
||||
|
||||
### Embed
|
||||
|
||||
This option embeds the official bootstrapper within the application. If no suitable runtime has been found, the
|
||||
application will offer to run the bootstrapper. This adds ~150k to the binary size.
|
||||
|
||||
### Browser
|
||||
|
||||
This option will prompt the user that no suitable runtime has been found and then offer to open a browser to the official
|
||||
WebView2 page where the bootstrapper can be downloaded and installed. The application will then exit, leaving the installation
|
||||
up to the user.
|
||||
|
||||
### Error
|
||||
|
||||
If no suitable runtime is found, an error is given to the user and no further action taken.
|
||||
324
website/docs/howdoesitwork.mdx
Normal file
324
website/docs/howdoesitwork.mdx
Normal file
@@ -0,0 +1,324 @@
|
||||
---
|
||||
sidebar_position: 20
|
||||
---
|
||||
|
||||
# How does it work?
|
||||
|
||||
A Wails application is a standard Go application, with a webkit frontend. The Go part of the application consists of the
|
||||
application code and a runtime library that provides a number of useful operations, like controlling the application
|
||||
window. The frontend is a webkit window that will display the frontend assets. Also available to the frontend is a Javascript
|
||||
version of the runtime library. Finally, it is possible to bind Go methods to the frontend, and these will appear as
|
||||
Javascript methods that can be called, just as if they were local Javascript methods.
|
||||
|
||||
<div className="text--center">
|
||||
<img src="/img/architecture.svg" width='75%'/>
|
||||
</div>
|
||||
|
||||
## The Main Application
|
||||
|
||||
### Overview
|
||||
The main application consists of a single call to `wails.Run()`. It accepts the
|
||||
application configuration which describes the size of the application window, the window title,
|
||||
what assets to use, etc. A basic application might look like this:
|
||||
|
||||
```go title="main.go"
|
||||
package main
|
||||
|
||||
import (
|
||||
"embed"
|
||||
"log"
|
||||
|
||||
"github.com/wailsapp/wails/v2"
|
||||
"github.com/wailsapp/wails/v2/pkg/options"
|
||||
)
|
||||
|
||||
//go:embed frontend/dist
|
||||
var assets embed.FS
|
||||
|
||||
func main() {
|
||||
|
||||
app := &App{}
|
||||
|
||||
err := wails.Run(&options.App{
|
||||
Title: "Basic Demo",
|
||||
Width: 1024,
|
||||
Height: 768,
|
||||
Assets: &assets,
|
||||
OnStartup: app.startup,
|
||||
OnShutdown: app.shutdown,
|
||||
Bind: []interface{}{
|
||||
app,
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
type App struct {
|
||||
ctx context.Context
|
||||
}
|
||||
|
||||
func (b *App) startup(ctx context.Context) {
|
||||
b.ctx = ctx
|
||||
}
|
||||
|
||||
func (b *App) shutdown(ctx context.Context) {}
|
||||
|
||||
func (b *App) Greet(name string) string {
|
||||
return fmt.Sprintf("Hello %s!", name)
|
||||
}
|
||||
```
|
||||
|
||||
### Options rundown
|
||||
|
||||
This example has the following options set:
|
||||
|
||||
- `Title` - The text that should appear in the window's title bar
|
||||
- `Width` & `Height` - The dimensions of the window
|
||||
- `Assets` - The application's frontend assets
|
||||
- `OnStartup` - A callback for when the window is created and is about to start loading the frontend assets
|
||||
- `OnShutdown` - A callback for when the application is about to quit
|
||||
- `Bind` - A slice of struct instances that we wish to expose to the frontend
|
||||
|
||||
A full list of application options can be found in the [Options Reference](/docs/reference/options).
|
||||
|
||||
#### Assets
|
||||
|
||||
The `Assets` option is mandatory as you can't have a Wails application without frontend assets. Those assets can be
|
||||
any files you would expect to find in a web application - html, js, css, svg, png, etc. **There is no requirement to
|
||||
generate asset bundles** - plain files will do. When the application starts, it will attempt to load `index.html`
|
||||
from your assets and the frontend will essentially work as a browser from that point on. It is worth noting that
|
||||
there is no requirement on where in the `embed.FS` the files live. It is likely that the embed path uses a nested
|
||||
directory relative to your main application code, such as `frontend/dist`:
|
||||
|
||||
```go title="main.go"
|
||||
// go:embed frontend/dist
|
||||
var assets embed.FS
|
||||
```
|
||||
|
||||
At startup, Wails will iterate the embedded files looking for the directory containing `index.html`. All other assets will be loaded relative
|
||||
to this directory.
|
||||
|
||||
As production binaries use the files contained in `embed.FS`, there are no external files required to be shipped with
|
||||
the application.
|
||||
|
||||
When running in development mode using the `wails dev` command, the assets are loaded off disk, and any changes result
|
||||
in a "live reload". The location of the assets needs to be passed to the `wails dev` command using the `-assetdir` flag
|
||||
and is likely to be the same as the embed path. It is hoped that in the future we can calculate this from the `embed.FS`
|
||||
itself.
|
||||
|
||||
More details can be found in the [Application Development Guide](/docs/guides/appdev).
|
||||
|
||||
#### Application Lifecycle Callbacks
|
||||
|
||||
Just before the frontend is about to load `index.html`, a callback is made to the function provided in [OnStartup](/docs/reference/options#OnStartup).
|
||||
A standard Go context is passed to this method. This context is required when calling the runtime so a standard pattern is to save
|
||||
a reference to in this method. Just before the application shuts down, the [OnShutdown](/docs/reference/options#OnShutdown) callback is called in the same way,
|
||||
again with the context. There is also an [OnDomReady](/docs/reference/options#OnDomReady) callback for when the frontend
|
||||
has completed loading all assets in `index.html` and is equivalent of the [`body onload`](https://www.w3schools.com/jsref/event_onload.asp) event in Javascript.
|
||||
|
||||
#### Method Binding
|
||||
|
||||
The `Bind` option is one of the most important options in a Wails application. It specifies which struct methods
|
||||
to expose to the frontend. When the application starts, it examines the struct instances listed in `Bind`, determines
|
||||
which methods are public (starts with an uppercase letter) and will generate Javascript versions of those methods that
|
||||
can be called by the frontend code.
|
||||
|
||||
These methods are located in the frontend at `window.go.<packagename>.<struct>.<method>`.
|
||||
In the example above, we bind `app`, which has one public method `Greet`.
|
||||
This can be called in Javascript by calling `window.go.main.App.Greet`.
|
||||
These methods return a promise. A successful call will result in the first return value from the Go call to be passed
|
||||
to the resolve handler. An unsuccessful call is when a Go method that has an error type as it's second return value,
|
||||
passes an error instance back to the caller. This is passed back via the reject handler.
|
||||
In the example above, `Greet` only returns a `string` so the Javascript call will never reject - unless invalid data
|
||||
is passed to it.
|
||||
|
||||
All data types are correctly translated between Go and Javascript. Even structs. If you return a struct from a Go call,
|
||||
it will be returned to your frontend as a Javascript map. Note: If you wish to use structs, you **must** define `json` struct
|
||||
tags for your fields! It is also possible to send structs back to Go. Any Javascript map passed as an argument that
|
||||
is expecting a struct, will be converted to that struct type. To make this process a lot easier, in `dev` mode,
|
||||
a TypeScript module is generated, defining all the struct types used in bound methods. Using this module, it's possible
|
||||
to construct and send native Javascript objects to the Go code.
|
||||
|
||||
More information on Binding can be found in the [Binding Methods](/docs/guides/application-development#binding-methods)
|
||||
section of the [Application Development Guide](/docs/guides/application-development).
|
||||
|
||||
## The Frontend
|
||||
|
||||
### Overview
|
||||
The frontend is a collection of files rendered by webkit. It's like a browser and webserver in one.
|
||||
There is virtually[^1] no limit to which frameworks or libraries you can use. The main points of interaction between
|
||||
the frontend and your Go code are:
|
||||
- Calling bound Go methods
|
||||
- Calling runtime methods
|
||||
|
||||
[^1]: There is a very small subset of libraries that use features unsupported in WebViews. There are often alternatives and
|
||||
workarounds for such cases.
|
||||
|
||||
### Calling bound Go methods
|
||||
|
||||
All bound Go methods are available at `window.go.<package>.<struct>.<method>`. As stated in
|
||||
the previous section, these return a Promise where a successful call returns a value to the
|
||||
resolve handler and an error returns a value to the reject handler.
|
||||
|
||||
```go title="mycode.js"
|
||||
window.go.main.App.Greet("Bill").then((result) => {
|
||||
console.log("The greeting is: " + result);
|
||||
})
|
||||
```
|
||||
|
||||
When running the application in `dev` mode, a javascript module is generated that wraps these
|
||||
methods with JSDoc annotations. This really help with development, especially as most
|
||||
IDEs will process JSDoc to provide code completion and type hinting. This module is called `go`
|
||||
and is generated in the directory specified by the `wailsjsdir` flag. In this module is a file
|
||||
called `bindings.js` containing these wrappers. For the above example, the file contains the
|
||||
following code:
|
||||
|
||||
```js title="bindings.js"
|
||||
const go = {
|
||||
"main": {
|
||||
"App": {
|
||||
/**
|
||||
* Greet
|
||||
* @param {Person} arg1 - Go Type: string
|
||||
* @returns {Promise<string>} - Go Type: string
|
||||
*/
|
||||
"Greet": (arg1) => {
|
||||
return window.go.main.App.Greet(arg1);
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
};
|
||||
export default go;
|
||||
```
|
||||
|
||||
#### Support for structs
|
||||
|
||||
There is also additional support for Go methods that use structs in their signature. All Go structs
|
||||
specified by bound method (either as parameters or return types) will have Typescript versions auto
|
||||
generated as part of the Go code wrapper module. Using these, it's possible to share the same data
|
||||
model between Go and Javascript. These models align with the JSDoc annotations, empowering IDE code
|
||||
completion.
|
||||
|
||||
Example: We update our `Greet` method to accept a `Person` instead of a string:
|
||||
|
||||
```go title="main.go"
|
||||
type Person struct {
|
||||
Name string `json:"name"`
|
||||
Age uint8 `json:"age"`
|
||||
Address *Address `json:"address"`
|
||||
}
|
||||
|
||||
type Address struct {
|
||||
Street string `json:"street"`
|
||||
Postcode string `json:"postcode"`
|
||||
}
|
||||
|
||||
func (a *App) Greet(p Person) string {
|
||||
return fmt.Sprintf("Hello %s (Age: %d)!", p.Name, p.Age)
|
||||
}
|
||||
```
|
||||
Our `bindings.js` file has now been updated to reflect the change:
|
||||
|
||||
```js title="bindings.js"
|
||||
const go = {
|
||||
"main": {
|
||||
"App": {
|
||||
/**
|
||||
* Greet
|
||||
* @param {Person} arg1 - Go Type: main.Person
|
||||
* @returns {Promise<string>} - Go Type: string
|
||||
*/
|
||||
"Greet": (arg1) => {
|
||||
return window.go.main.App.Greet(arg1);
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
};
|
||||
export default go;
|
||||
```
|
||||
Alongside `bindings.js`, there is a file called `models.ts`. This contains our Go structs in TypeScript form:
|
||||
```ts title="models.ts"
|
||||
export class Address {
|
||||
street: string;
|
||||
postcode: string;
|
||||
|
||||
static createFrom(source: any = {}) {
|
||||
return new Address(source);
|
||||
}
|
||||
|
||||
constructor(source: any = {}) {
|
||||
if ('string' === typeof source) source = JSON.parse(source);
|
||||
this.street = source["street"];
|
||||
this.postcode = source["postcode"];
|
||||
}
|
||||
}
|
||||
export class Person {
|
||||
name: string;
|
||||
age: number;
|
||||
address?: Address;
|
||||
|
||||
static createFrom(source: any = {}) {
|
||||
return new Person(source);
|
||||
}
|
||||
|
||||
constructor(source: any = {}) {
|
||||
if ('string' === typeof source) source = JSON.parse(source);
|
||||
this.name = source["name"];
|
||||
this.age = source["age"];
|
||||
this.address = this.convertValues(source["address"], Address);
|
||||
}
|
||||
|
||||
convertValues(a: any, classs: any, asMap: boolean = false): any {
|
||||
if (!a) {
|
||||
return a;
|
||||
}
|
||||
if (a.slice) {
|
||||
return (a as any[]).map(elem => this.convertValues(elem, classs));
|
||||
} else if ("object" === typeof a) {
|
||||
if (asMap) {
|
||||
for (const key of Object.keys(a)) {
|
||||
a[key] = new classs(a[key]);
|
||||
}
|
||||
return a;
|
||||
}
|
||||
return new classs(a);
|
||||
}
|
||||
return a;
|
||||
}
|
||||
}
|
||||
```
|
||||
So long as you have TypeScript as part of your frontend build configuration, you can use these models in
|
||||
the following way:
|
||||
```js title="mycode.js"
|
||||
import go from "./wailsjs/go/bindings";
|
||||
import {Person} from "./wailsjs/go/models";
|
||||
|
||||
let name = "";
|
||||
|
||||
function greet(name) {
|
||||
let p = new Person();
|
||||
p.name = name;
|
||||
p.age = 42;
|
||||
go.main.App.Greet(p).then((result) => {
|
||||
console.log(result);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The combination of JSDoc and TypeScript generated models makes for a powerful development environment.
|
||||
|
||||
### Calling runtime methods
|
||||
|
||||
The Javascript runtime is located at `window.runtime` and contains many methods to do various
|
||||
tasks such as emit an event or perform logging operations:
|
||||
|
||||
```js title="mycode.js"
|
||||
window.runtime.EventsEmit("my-event", 1);
|
||||
```
|
||||
|
||||
More details about the JS runtime can be found in the [Runtime Reference](/docs/reference/runtime/intro).
|
||||
4
website/docs/reference/_category_.json
Normal file
4
website/docs/reference/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Reference",
|
||||
"position": 40
|
||||
}
|
||||
178
website/docs/reference/cli.mdx
Normal file
178
website/docs/reference/cli.mdx
Normal 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
233
website/docs/reference/menus.mdx
Normal 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
275
website/docs/reference/options.mdx
Normal 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
24
website/docs/reference/project-config.mdx
Normal 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
4
website/docs/reference/runtime/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Runtime",
|
||||
"position": 1
|
||||
}
|
||||
20
website/docs/reference/runtime/browser.mdx
Normal file
20
website/docs/reference/runtime/browser.mdx
Normal 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
140
website/docs/reference/runtime/dialog.mdx
Normal 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
51
website/docs/reference/runtime/events.mdx
Normal 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
16
website/docs/reference/runtime/intro.mdx
Normal 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
114
website/docs/reference/runtime/log.mdx
Normal 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
25
website/docs/reference/runtime/menu.mdx
Normal 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
184
website/docs/reference/runtime/window.mdx
Normal 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;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
24
website/docs/stats.mdx
Normal file
24
website/docs/stats.mdx
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
sidebar_position: 100
|
||||
---
|
||||
|
||||
# Website Stats
|
||||
|
||||
To enable us to understand how better to focus our efforts on translations and platform support,
|
||||
we use [Plausible](https://plausible.io/privacy-focused-web-analytics) to gather **anonymous** stats like country and platform.
|
||||
We chose Plausible because we believe in respecting the privacy of our users.
|
||||
We also believe in transparency, therefore have made the dashboard public.
|
||||
|
||||
If you have any concerns or suggestions, please raise them in the projects github discussions.
|
||||
|
||||
<head>
|
||||
<script async src="https://plausible.io/js/embed.host.js"></script>
|
||||
</head>
|
||||
|
||||
export const NewComponent = () => (
|
||||
<div>
|
||||
<iframe plausible-embed="true" src="https://plausible.io/share/beta.wails.io?auth=wJa_HtqinG_eosqMjP-T1&embed=true&theme=system" scrolling="no" frameBorder={0} loading="lazy" style={{width: '1px', minWidth: '100%', height: '1600px'}} />
|
||||
</div>
|
||||
);
|
||||
|
||||
<NewComponent/>
|
||||
Reference in New Issue
Block a user