Skip to content

Commit

Permalink
docs: sync translations (#3001)
Browse files Browse the repository at this point in the history
Co-authored-by: leaanthony <[email protected]>
Co-authored-by: Lea Anthony <[email protected]>
  • Loading branch information
3 people authored Nov 8, 2023
1 parent e32c2b0 commit 03545e3
Show file tree
Hide file tree
Showing 41 changed files with 2,385 additions and 34 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
# Custom Protocol Scheme association

Custom Protocols feature allows you to associate specific custom protocol with your app so that when users open links with this protocol,
your app is launched to handle them. This can be particularly useful to connect your desktop app with your web app.
In this guide, we'll walk through the steps to implement custom protocols in Wails app.

## Set Up Custom Protocol Schemes Association:

To set up custom protocol, you need to modify your application's wails.json file.
In "info" section add a "protocols" section specifying the protocols your app should be associated with.

For example:

```json
{
"info": {
"protocols": [
{
"scheme": "myapp",
"description": "My App Protocol",
"role": "Editor"
}
]
}
}
```

| Property | Description |
| :---------- | :------------------------------------------------------------------------------------ |
| scheme | Custom Protocol scheme. e.g. myapp |
| description | Windows-only. The description. |
| role | macOS-only. The app’s role with respect to the type. Corresponds to CFBundleTypeRole. |

## Platform Specifics:

### macOS

When you open custom protocol with your app, the system will launch your app and call the `OnUrlOpen` function in your Wails app. Example:

```go title="main.go"
func main() {
// Create application with options
err := wails.Run(&options.App{
Title: "wails-open-file",
Width: 1024,
Height: 768,
AssetServer: &assetserver.Options{
Assets: assets,
},
BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
Mac: &mac.Options{
OnUrlOpen: func(url string) { println(url) },
},
Bind: []interface{}{
app,
},
})

if err != nil {
println("Error:", err.Error())
}
}
```

### Windows

On Windows Custom Protocol Schemes is supported only with NSIS installer. During installation, the installer will create a
registry entry for your schemes. When you open url with your app, new instance of app is launched and url is passed
as argument to your app. To handle this you should parse command line arguments in your app. Example:

```go title="main.go"
func main() {
argsWithoutProg := os.Args[1:]

if len(argsWithoutProg) != 0 {
println("launchArgs", argsWithoutProg)
}
}
```

You also can enable single instance lock for your app. In this case, when you open url with your app, new instance of app is not launched
and arguments are passed to already running instance. Check single instance lock guide for details. Example:

```go title="main.go"
func main() {
// Create application with options
err := wails.Run(&options.App{
Title: "wails-open-file",
Width: 1024,
Height: 768,
AssetServer: &assetserver.Options{
Assets: assets,
},
BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
SingleInstanceLock: &options.SingleInstanceLock{
UniqueId: "e3984e08-28dc-4e3d-b70a-45e961589cdc",
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
},
Bind: []interface{}{
app,
},
})
}
```

### Linux

Currently, Wails doesn't support bundling for Linux. So, you need to create file associations manually.
For example if you distribute your app as a .deb package, you can create file associations by adding required files in you bundle.
You can use [nfpm](https://nfpm.goreleaser.com/) to create .deb package for your app.

1. Create a .desktop file for your app and specify file associations there (note that `%u` is important in Exec). Example:

```ini
[Desktop Entry]
Categories=Office
Exec=/usr/bin/wails-open-file %u
Icon=wails-open-file.png
Name=wails-open-file
Terminal=false
Type=Application
MimeType=x-scheme-handler/myapp;
```

2. Prepare postInstall/postRemove scripts for your package. Example:

```sh
# reload desktop database to load app in list of available
update-desktop-database /usr/share/applications
```

3. Configure nfpm to use your scripts and files. Example:

```yaml
name: "wails-open-file"
arch: "arm64"
platform: "linux"
version: "1.0.0"
section: "default"
priority: "extra"
maintainer: "FooBarCorp <[email protected]>"
description: "Sample Package"
vendor: "FooBarCorp"
homepage: "http://example.com"
license: "MIT"
contents:
- src: ../bin/wails-open-file
dst: /usr/bin/wails-open-file
- src: ./main.desktop
dst: /usr/share/applications/wails-open-file.desktop
- src: ../appicon.svg
dst: /usr/share/icons/hicolor/scalable/apps/wails-open-file.svg
# copy icons to Yaru theme as well. For some reason Ubuntu didn't pick up fileicons from hicolor theme
- src: ../appicon.svg
dst: /usr/share/icons/Yaru/scalable/apps/wails-open-file.svg
scripts:
postinstall: ./postInstall.sh
postremove: ./postRemove.sh
```
6. Build your .deb package using nfpm:
```sh
nfpm pkg --packager deb --target .
```

7. Now when your package is installed, your app will be associated with custom protocol scheme. When you open url with your app,
new instance of app is launched and file path is passed as argument to your app.
To handle this you should parse command line arguments in your app. Example:

```go title="main.go"
func main() {
argsWithoutProg := os.Args[1:]

if len(argsWithoutProg) != 0 {
println("launchArgs", argsWithoutProg)
}
}
```

You also can enable single instance lock for your app. In this case, when you open url with your app, new instance of app is not launched
and arguments are passed to already running instance. Check single instance lock guide for details. Example:

```go title="main.go"
func main() {
// Create application with options
err := wails.Run(&options.App{
Title: "wails-open-file",
Width: 1024,
Height: 768,
AssetServer: &assetserver.Options{
Assets: assets,
},
BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
SingleInstanceLock: &options.SingleInstanceLock{
UniqueId: "e3984e08-28dc-4e3d-b70a-45e961589cdc",
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
},
Bind: []interface{}{
app,
},
})
}
```
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,31 @@ func main() {
}
```

You also can enable single instance lock for your app. In this case, when you open file with your app, new instance of app is not launched
and arguments are passed to already running instance. Check single instance lock guide for details. Example:

```go title="main.go"
func main() {
// Create application with options
err := wails.Run(&options.App{
Title: "wails-open-file",
Width: 1024,
Height: 768,
AssetServer: &assetserver.Options{
Assets: assets,
},
BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
SingleInstanceLock: &options.SingleInstanceLock{
UniqueId: "e3984e08-28dc-4e3d-b70a-45e961589cdc",
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
},
Bind: []interface{}{
app,
},
})
}
```

### Linux

Currently, Wails doesn't support bundling for Linux. So, you need to create file associations manually.
Expand Down Expand Up @@ -193,7 +218,27 @@ func main() {
}
```

## Limitations:
You also can enable single instance lock for your app. In this case, when you open file with your app, new instance of app is not launched
and arguments are passed to already running instance. Check single instance lock guide for details. Example:

On Windows and Linux when associated file is opened, new instance of your app is launched.
Currently, Wails doesn't support opening files in already running app. There is plugin for single instance support for v3 in development.
```go title="main.go"
func main() {
// Create application with options
err := wails.Run(&options.App{
Title: "wails-open-file",
Width: 1024,
Height: 768,
AssetServer: &assetserver.Options{
Assets: assets,
},
BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
SingleInstanceLock: &options.SingleInstanceLock{
UniqueId: "e3984e08-28dc-4e3d-b70a-45e961589cdc",
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
},
Bind: []interface{}{
app,
},
})
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Single Instance Lock

Single instance lock is a mechanism that allows you to prevent multiple instances of your app from running at the same time.
It is useful for apps that are designed to open files from the command line or from the OS file explorer.

## Important

Single Instance Lock does not implement a secure communications protocol between instances. When using single instance lock,
your app should treat any data passed to it from second instance callback as untrusted.
You should verify that args that you receive are valid and don't contain any malicious data.

## How it works

Windows: Single instance lock is implemented using a named mutex. The mutex name is generated from the unique id that you provide. Data is passed to the first instance via a shared window using [SendMessage](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendmessage)
macOS: Single instance lock is implemented using a named mutex. The mutex name is generated from the unique id that you provide. Data is passed to the first instance via [NSDistributedNotificationCenter](https://developer.apple.com/documentation/foundation/nsdistributednotificationcenter)
Linux: Single instance lock is implemented using [dbus](https://www.freedesktop.org/wiki/Software/dbus/). The dbus name is generated from the unique id that you provide. Data is passed to the first instance via [dbus](https://www.freedesktop.org/wiki/Software/dbus/)

## Usage

When creating your app, you can enable single instance lock by passing a `SingleInstanceLock` struct to the `App` struct.
Use the `UniqueId` field to specify a unique id for your app.
This id is used to generate the mutex name on Windows and macOS and the dbus name on Linux. Use a UUID to ensure that the id is unique.
The `OnSecondInstanceLaunch` field is used to specify a callback that is called when a second instance of your app is launched.
The callback receives a `SecondInstanceData` struct that contains the command line arguments passed to the second instance and the working directory of the second instance.

Note that OnSecondInstanceLaunch don't trigger windows focus.
You need to call `runtime.WindowUnminimise` and `runtime.Show` to bring your app to the front.
Note that on linux systems window managers may prevent your app from being brought to the front to avoid stealing focus.

```go title="main.go"
var wailsContext *context.Context

// NewApp creates a new App application struct
func NewApp() *App {
return &App{}
}

// startup is called when the app starts. The context is saved
// so we can call the runtime methods
func (a *App) startup(ctx context.Context) {
wailsContext = &ctx
}

func (a *App) onSecondInstanceLaunch(secondInstanceData options.SecondInstanceData) {
secondInstanceArgs = secondInstanceData.Args

println("user opened second instance", strings.Join(secondInstanceData.Args, ","))
println("user opened second from", secondInstanceData.WorkingDirectory)
runtime.WindowUnminimise(*wailsContext)
runtime.Show(*wailsContext)
go runtime.EventsEmit(*wailsContext, "launchArgs", secondInstanceArgs)
}

func main() {
// Create an instance of the app structure
app := NewApp()

// Create application with options
err := wails.Run(&options.App{
Title: "wails-open-file",
Width: 1024,
Height: 768,
AssetServer: &assetserver.Options{
Assets: assets,
},
BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
OnStartup: app.startup,
SingleInstanceLock: &options.SingleInstanceLock{
UniqueId: "e3984e08-28dc-4e3d-b70a-45e961589cdc",
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
},
Bind: []interface{}{
app,
},
})

if err != nil {
println("Error:", err.Error())
}
}
```
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Wails est livré avec un certain nombre de modèles préconfigurés qui vous per

Wails utilise une bibliothèque conçue pour gérer les éléments natifs tels que les fenêtres, menus, boîtes de dialogues, etc, pour que vous puissiez construire des applications de bureau riches en fonctionnalités.

**Il n'embarque pas de navigateur**, il est donc efficace sur les ressources. Au lieu de cela, il utilise le moteur de rendu natif de la plate-forme. Sous Windows, c'est la nouvelle bibliothèque Microsoft Webview2, construite sur Chromium.
**It does not embed a browser**, so it delivers a small runtime. Instead, it reuses the native rendering engine for the platform. Sous Windows, c'est la nouvelle bibliothèque Microsoft Webview2, construite sur Chromium.

### Interopérabilité Go & Javascript

Expand Down
6 changes: 6 additions & 0 deletions website/i18n/fr/docusaurus-plugin-content-pages/changelog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Le format est basé sur [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)

### Ajouts

- Update the description of `ZoomFactor` and `IsZoomControlEnabled` attributes in the document. Added by @biuaxia in [PR](https://github.com/wailsapp/wails/pull/3013)
- Added Single Instance Lock support with passing arguments to first instance. Added by @APshenkin in [PR](https://github.com/wailsapp/wails/pull/2951)
- Added support for enabling/disabling swipe gestures for Windows WebView2. Added by @leaanthony in [PR](https://github.com/wailsapp/wails/pull/2878)
- When building with `-devtools` flag, CMD/CTRL+SHIFT+F12 can be used to open the devtools. Added by @leaanthony in [PR](https://github.com/wailsapp/wails/pull/2915) – Added file association support for macOS and Windows. Added by @APshenkin in [PR](https://github.com/wailsapp/wails/pull/2918)
- Added support for setting some of the Webview preferences, `textInteractionEnabled` and `tabFocusesLinks` on Mac. Added by @fkhadra in [PR](https://github.com/wailsapp/wails/pull/2937)
Expand All @@ -23,17 +25,21 @@ Le format est basé sur [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
- New task created for linting v2 `task v2:lint`. Workflow updated to run the task. Added by @mikeee in [PR](https://github.com/wailsapp/wails/pull/2957)
- Added new community template wails-htmx-templ-chi-tailwind. Added by [@pylotlight](https://github.com/pylotlight) in [PR](https://github.com/wailsapp/wails/pull/2984)
- Added CPU/GPU/Memory detection for `wails doctor`. Added by @leaanthony in #d51268b8d0680430f3a614775b13e6cd2b906d1c
- The [AssetServer](/docs/reference/options#assetserver) now injects the runtime/IPC into all index html files and into all html files returned when requesting a folder path. Added by @stffabi in [PR](https://github.com/wailsapp/wails/pull/2203)
- Added Custom Protocol Schemes associations support for macOS and Windows. Added by @APshenkin in [PR](https://github.com/wailsapp/wails/pull/3000)

### Changements

- AssetServer requests are now processed asynchronously without blocking the main thread on Windows. Changed by @stffabi in [PR](https://github.com/wailsapp/wails/pull/2926)
- AssetServer requests are now processed concurrently by spawning a goroutine per request. Changed by @stffabi in [PR](https://github.com/wailsapp/wails/pull/2926)
- Now building with `-devtools` flag doesn't enable the default context-menu. Changed by @mmghv in [PR](https://github.com/wailsapp/wails/pull/2923)
- Change Window Level. Changed by @almas1992 in [PR](https://github.com/wailsapp/wails/pull/2944)

#### Corrections

- Fixed typo on docs/reference/options page. Added by [@pylotlight](https://github.com/pylotlight) in [PR](https://github.com/wailsapp/wails/pull/2887)
- Fixed issue with npm being called npm20 on openSUSE-Tumbleweed. Fixed by @TuffenDuffen in [PR] in (https://github.com/wailsapp/wails/pull/2941)
- Fixed memory corruption on Windows when using accelerator keys. Fixed by @stffabi in [PR] in (https://github.com/wailsapp/wails/pull/3002)

## v2.6.0 - 2023-09-06

Expand Down
Loading

0 comments on commit 03545e3

Please sign in to comment.