Atalhos globais

Atalhos globais são atalhos de teclado disponíveis em todo o sistema e acionados independentemente do aplicativo que está em foco no momento, enquanto seu aplicativo Wails estiver em execução. Eles são ideais para teclas de atalho de exibir/ocultar, ferramentas de captura rápida, controles de mídia e outros recursos que os usuários esperam poder acessar de qualquer lugar.

Os atalhos globais são implementados diretamente com os recursos nativos de cada plataforma e não adicionam dependências de terceiros.

Como acessar o gerenciador de atalhos globais

O gerenciador está disponível na propriedade GlobalShortcut da instância do seu aplicativo:

app := application.New(application.Options{
    Name: "Global Shortcuts Demo",
})

globalShortcuts := app.GlobalShortcut

Como registrar um atalho

Register recebe um acelerador e um callback. O callback é executado em sua própria goroutine sempre que o atalho é pressionado.

err := app.GlobalShortcut.Register("CmdOrCtrl+Shift+G", func() {
    // Runs even when another application is focused.
    window.Show()
    window.Focus()
})
if err != nil {
    app.Logger.Error("could not register shortcut", "error", err)
}

Você pode registrar atalhos antes de chamar app.Run. A associação com o sistema operacional é então realizada automaticamente quando o aplicativo é iniciado.

Formato do acelerador

Os atalhos globais usam o mesmo formato de acelerador que os aceleradores de menu e as associações de teclas:

"CmdOrCtrl+Shift+G"  // Command on macOS, Control elsewhere
"Ctrl+Alt+K"         // Control + Alt + K
"Cmd+Option+Space"   // Command + Option + Space (macOS)
"Super+D"            // Super / Windows / Logo key + D
"Ctrl+Shift+F5"      // Function keys are supported

CmdOrCtrl é resolvido como Command no macOS e Control no Windows e no Linux, o que facilita a criação de atalhos multiplataforma.

Como gerenciar atalhos

// Check whether a shortcut is registered (modifier order does not matter).
registered := app.GlobalShortcut.IsRegistered("Ctrl+Shift+G")

// List every shortcut this application has registered.
for _, accelerator := range app.GlobalShortcut.GetAll() {
    app.Logger.Info("global shortcut", "accelerator", accelerator)
}

// Release a single shortcut.
app.GlobalShortcut.Unregister("Ctrl+Shift+G")

// Release everything (also done automatically on shutdown).
app.GlobalShortcut.UnregisterAll()

Todos os atalhos registrados são liberados automaticamente quando o aplicativo é encerrado, portanto não é necessário removê-los manualmente.

O que acontece quando o mesmo atalho é registrado duas vezes

Há dois casos distintos, e o Wails trata cada um de forma diferente.

O mesmo aplicativo registra um atalho duas vezes

Esse caso é resolvido pelo próprio Wails e apresenta o mesmo comportamento em todas as plataformas. A segunda chamada a Register retorna um erro, e a associação original é mantida (“erro e preservação”). Isso mantém o comportamento previsível e revela o engano, em vez de substituir silenciosamente um atalho funcional.

app.GlobalShortcut.Register("Ctrl+Shift+G", showWindow)        // ok
err := app.GlobalShortcut.Register("Shift+Ctrl+G", doSomething) // err: already registered
// showWindow is still the active callback for this shortcut.

Se quiser alterar o callback de um atalho, primeiro chame Unregister para removê-lo e depois chame Register para registrá-lo novamente.

Outro aplicativo já é o proprietário do atalho

Esse caso é decidido pelo sistema operacional, portanto o resultado varia conforme a plataforma:

Devido a essas diferenças, sempre verifique o erro retornado por Register e forneça um atalho alternativo ou uma mensagem ao usuário quando não for possível obter a combinação.

Considerações específicas de cada plataforma

Exemplo completo

package main

import (
    "log"

    "github.com/wailsapp/wails/v3/pkg/application"
)

func main() {
    app := application.New(application.Options{
        Name: "Global Shortcuts Demo",
    })

    window := app.Window.New()

    // Bring the window to the front from anywhere.
    if err := app.GlobalShortcut.Register("CmdOrCtrl+Shift+G", func() {
        window.Show()
        window.Focus()
    }); err != nil {
        log.Printf("could not register show shortcut: %v", err)
    }

    // Hide the window from anywhere.
    if err := app.GlobalShortcut.Register("CmdOrCtrl+Shift+H", func() {
        window.Hide()
    }); err != nil {
        log.Printf("could not register hide shortcut: %v", err)
    }

    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}