-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: leaanthony <[email protected]> Co-authored-by: Lea Anthony <[email protected]>
- Loading branch information
1 parent
e32c2b0
commit 03545e3
Showing
41 changed files
with
2,385 additions
and
34 deletions.
There are no files selected for viewing
204 changes: 204 additions & 0 deletions
204
...8n/fr/docusaurus-plugin-content-docs/current/guides/custom-protocol-schemes.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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, | ||
}, | ||
}) | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
81 changes: 81 additions & 0 deletions
81
.../i18n/fr/docusaurus-plugin-content-docs/current/guides/single-instance-lock.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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()) | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.