Wails

https://v3.wails.io/
Admin
Wails is a framework for building cross-platform desktop applications using Go and modern web...
Tokens:578,345
Snippets:5,219
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Resize and center example

Source: https://v3.wails.io/reference/frontend-runtime

Example showing how to resize and center the window, and get the current size.

```javascript
import { Window } from '@wailsio/runtime'

// Resize and center
await Window.SetSize(800, 600)
await Window.Center()

// Get current size
const { width, height } = await Window.Size()
```

--------------------------------

### Install Wails CLI and run setup wizard

Source: https://v3.wails.io/getting-started/setup

Installs the Wails v3 CLI using go install and runs the setup wizard, which opens in the browser for dependency checks and project defaults.

```bash
# 1. Install the Wails CLI
go install github.com/wailsapp/wails/v3/cmd/wails3@latest

# 2. Run the setup wizard
wails3 setup

```

--------------------------------

### Quick Install Wails CLI

Source: https://v3.wails.io/quick-start/installation

Install the Wails v3 CLI and run the setup wizard.

```bash
# Install Go 1.25+, then:
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
wails3 setup   # Interactive setup wizard (experimental)
```

--------------------------------

### Quick Start: Create and Show a Window

Source: https://v3.wails.io/features/windows/basics

Creates a Wails application, creates a window, sets its title and size, centers it, shows it, and runs the application. This is the minimal setup for a cross-platform window.

```go
package main

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

func main() {
    app := application.New(application.Options{
        Name: "My App",
    })

    // Create a window
    window := app.Window.New()
    
    // Configure it
    window.SetTitle("Hello Wails")
    window.SetSize(800, 600)
    window.Center()
    
    // Show it
    window.Show()

    app.Run()
}
```

--------------------------------

### UseApplicationMenu example with application menu setup

Source: https://v3.wails.io/features/windows/options

Shows setting the application menu once and creating two windows with UseApplicationMenu enabled so they both display the same menu.

```go
// Set the application menu once
menu := app.NewMenu()
menu.AddRole(application.FileMenu)
menu.AddRole(application.EditMenu)
app.Menu.Set(menu)

// All windows with UseApplicationMenu will display this menu
app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:              "Main Window",
    UseApplicationMenu: true,
})

app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:              "Second Window",
    UseApplicationMenu: true,  // Also gets the app menu
})
```

--------------------------------

### Initialize updater with GitHub provider and check for updates

Source: https://v3.wails.io/guides/updater

Sets up the updater with a GitHub provider, initializes it with the current version, and checks for and installs updates. The example opens the framework's update window, checks GitHub, downloads the platform asset, verifies it, swaps the binary, and waits for the user to restart.

```go
package main

import (
    "context"
    "log"

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

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

    gh, _ := github.New(github.Config{Repository: "myorg/myapp"})
    if err := app.Updater.Init(updater.Config{
        CurrentVersion: "1.0.0",
        Providers:      []updater.Provider{gh},
    }); err != nil {
        log.Fatal(err)
    }

    if err := app.Updater.CheckAndInstall(context.Background()); err != nil {
        log.Printf("update: %v", err)
    }

    _ = app.Run()
}
```

--------------------------------

### Center method signature and example

Source: https://v3.wails.io/reference/window

Centers the window on the screen. The example creates a new window, centers it, and shows it. Note: centres on the primary monitor; for multi-monitor setups, see the screen APIs.

```go
func (w *WebviewWindow) Center()
```

```go
window := app.Window.New()
window.Center()
window.Show()
```

--------------------------------

### v2 Application Initialization with wails.Run

Source: https://v3.wails.io/migration/v2-to-v3

Shows the v2 monolithic application setup, combining window configuration and service binding in a single wails.Run() call. Use this as the starting point when migrating to v3.

```go
err := wails.Run(&options.App{
    Title:  "My App",
    Width:  1024,
    Height: 768,
    Bind: []interface{}{
        &GreetService{},
    },
})
```

--------------------------------

### Create an installer or package with wails3 package

Source: https://v3.wails.io/faq

Run `wails3 package` to produce the platform-native installer format. The Installers guide covers NSIS on Windows, `.app` bundles and DMGs on macOS, and Linux packages.

```bash
wails3 package

```

--------------------------------

### Complete lifecycle example for DatabaseService

Source: https://v3.wails.io/features/bindings/services

A complete example showing both ServiceStartup and ServiceShutdown methods for a database service, including opening a database, testing the connection, starting a background cleanup task, and properly shutting down. It demonstrates the full lifecycle pattern.

```go
type DatabaseService struct {
    db     *sql.DB
    logger *slog.Logger
    cancel context.CancelFunc
}

func NewDatabaseService(logger *slog.Logger) *DatabaseService {
    return &DatabaseService{logger: logger}
}

func (d *DatabaseService) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
    d.logger.Info("Starting database service")
    
    // Open database
    db, err := sql.Open("sqlite3", "app.db")
    if err != nil {
        return fmt.Errorf("failed to open database: %w", err)
    }
    d.db = db
    
    // Test connection
    if err := db.Ping(); err != nil {
        return fmt.Errorf("database not available: %w", err)
    }
    
    // Start background cleanup
    ctx, cancel := context.WithCancel(ctx)
    d.cancel = cancel
    go d.periodicCleanup(ctx)
    
    return nil
}

func (d *DatabaseService) ServiceShutdown() error {
    d.logger.Info("Shutting down database service")
    
    // Cancel background tasks
    if d.cancel != nil {
        d.cancel()
    }
    
    // Close database
    if d.db != nil {
        if err := d.db.Close(); err != nil {
            return fmt.Errorf("failed to close database: %w", err)
        }
    }
    
    return nil
}

func (d *DatabaseService) periodicCleanup(ctx context.Context) {
    ticker := time.NewTicker(1 * time.Hour)
    defer ticker.Stop()
    
    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            d.cleanup()
        }
    }
}
```

--------------------------------

### Run Wails v3 setup wizard

Source: https://v3.wails.io/blog/wails-v3-beta

Runs the guided setup wizard that checks the local development environment and helps configure dependencies required by Wails.

```sh
wails3 setup

```

--------------------------------

### Quick Start: Create a custom dialog window

Source: https://v3.wails.io/features/dialogs/custom

Creates a frameless, always-on-top, hidden WebviewWindow, loads a custom UI via SetURL, and shows it as a modal. Use this as the minimal setup for a custom dialog.

```go
// Create custom dialog window
dialog := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:       "Custom dialog",
    Width:       400,
    Height:      300,
    AlwaysOnTop: true,
    Frameless:   true,
    Hidden:      true,
})

// Load custom UI
dialog.SetURL("http://wails.localhost/dialog.html")

// Show as modal
dialog.Show()
dialog.Focus()
```

--------------------------------

### Install Go tools (goimports, golangci-lint)

Source: https://v3.wails.io/contributing/setup

Install useful Go development tools using 'go install'.

```bash
go install golang.org/x/tools/cmd/goimports@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

```

--------------------------------

### SetResizable usage example

Source: https://v3.wails.io/reference/window

Example showing how to make the window fixed size.

```go
// Make window fixed size
window.SetResizable(false)
```

--------------------------------

### Complete example: configure Windows options and create a window

Source: https://v3.wails.io/features/windows/options

A full runnable example that sets EnabledFeatures and AdditionalBrowserArgs, then creates a window. All windows will use the configured browser flags.

```go
package main

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

func main() {
    app := application.New(application.Options{
        Name: "My App",
        Windows: application.WindowsOptions{
            // Enable draggable regions feature
            EnabledFeatures: []string{
                "msWebView2EnableDraggableRegions",
            },
            // Enable remote debugging
            AdditionalBrowserArgs: []string{
                "--remote-debugging-port=9222",
            },
        },
    })

    // All windows will use the browser flags configured above
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:  "Main Window",
        Width:  1024,
        Height: 768,
    })

    window.Show()
    app.Run()
}
```

--------------------------------

### Check dependencies with wails3 doctor

Source: https://v3.wails.io/getting-started/installation

Run this command to check if you have the correct dependencies installed and get advice on what is missing. Useful for manual dependency installation or when the setup wizard doesn't work.

```shell
wails3 doctor
```

--------------------------------

### Complete Example

Source: https://v3.wails.io/reference/window

A complete Go example demonstrating how to create a window with options, configure window behavior, register a confirm-before-close hook, listen for window events, and show the window.

```APIDOC
## Complete Example

### Description
A complete example of using the Window API in a Wails v3 application.

### Code
```go
package main

import (
    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/events"
)

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

    // Create window with options
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:            "My Application",
        Width:            1024,
        Height:           768,
        MinWidth:         800,
        MinHeight:        600,
        BackgroundColour: application.NewRGB(255, 255, 255),
        URL:              "http://wails.localhost/",
    })

    // Configure window behaviour
    window.SetResizable(true)
    window.SetMinSize(800, 600)
    window.SetMaxSize(1920, 1080)

    // Confirm-before-close hook
    window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        dlg := app.Dialog.Question().
            SetTitle("Confirm Close").
            SetMessage("Are you sure you want to close this window?")

        yes := dlg.AddButton("Yes")
        no := dlg.AddButton("No")
        dlg.SetDefaultButton(yes)
        dlg.SetCancelButton(no)
        no.OnClick(func() { e.Cancel() })

        dlg.Show()
    })

    // Listen for window events
    window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application (Active)")
        app.Logger.Info("Window gained focus")
    })

    window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application")
        app.Logger.Info("Window lost focus")
    })

    // Position and show window
    window.Center()
    window.Show()

    app.Run()
}
```
```

--------------------------------

### Complete Window API Example

Source: https://v3.wails.io/reference/window

A complete example of creating a window with options, configuring its behavior, adding a confirm-before-close hook, listening for focus events, and showing the window. Demonstrates the use of `application.WebviewWindowOptions`, `RegisterHook`, `OnWindowEvent`, and dialog creation.

```go
package main

import (
    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/events"
)

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

    // Create window with options
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:            "My Application",
        Width:            1024,
        Height:           768,
        MinWidth:         800,
        MinHeight:        600,
        BackgroundColour: application.NewRGB(255, 255, 255),
        URL:              "http://wails.localhost/",
    })

    // Configure window behaviour
    window.SetResizable(true)
    window.SetMinSize(800, 600)
    window.SetMaxSize(1920, 1080)

    // Confirm-before-close hook
    window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        dlg := app.Dialog.Question().
            SetTitle("Confirm Close").
            SetMessage("Are you sure you want to close this window?")

        yes := dlg.AddButton("Yes")
        no := dlg.AddButton("No")
        dlg.SetDefaultButton(yes)
        dlg.SetCancelButton(no)
        no.OnClick(func() { e.Cancel() })

        dlg.Show()
    })

    // Listen for window events
    window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application (Active)")
        app.Logger.Info("Window gained focus")
    })

    window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
        window.SetTitle("My Application")
        app.Logger.Info("Window lost focus")
    })

    // Position and show window
    window.Center()
    window.Show()

    app.Run()
}
```

--------------------------------

### Clipboard.Text() JavaScript example

Source: https://v3.wails.io/reference/frontend-runtime

Example of getting clipboard text and logging it to the console.

```javascript
import { Clipboard } from '@wailsio/runtime'

const clipboardText = await Clipboard.Text()
console.log('Clipboard:', clipboardText)
```

--------------------------------

### Run the server example

Source: https://v3.wails.io/guides/server-build

Commands to run the server example from v3/examples/server. Use 'task dev' or 'go run -tags server .' and open http://localhost:8080.

```bash
cd v3/examples/server

# Using Taskfile
task dev

# Or run directly
go run -tags server .

# Open http://localhost:8080 in browser
```

--------------------------------

### Verify Setup Commands

Source: https://v3.wails.io/contributing/setup

Checks Go version, builds Wails, runs tests, and creates a test app to confirm the environment is ready.

```bash
# Go version check
go version

# Build Wails
cd v3
go build ./cmd/wails3

# Run tests
go test ./pkg/...

# Create a test app
cd ..
./wails3 init -n mytest -t vanilla
cd mytest
../wails3 dev

```

--------------------------------

### Install npm via NodeSource

Source: https://v3.wails.io/quick-start/installation

Use the NodeSource setup script to install Node.js on Debian-based systems.

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs  # Ubuntu/Debian
```

--------------------------------

### Multi-Window Application Setup

Source: https://v3.wails.io/blog/the-road-to-wails-v3

Shows how the proposed v3 API supports creating and managing multiple windows within a single application instance.

```go
func main() {
    app := wails.NewApplication(options.App{})
    myWindow := app.NewWindow(options.Window{})
    myWindow.SetTitle("My Window")
    myWindow.On(events.Window.Close, func() {
        app.Quit()
    })
    myWindow2 := app.NewWindow(options.Window{})
    myWindow2.SetTitle("My Window 2")
    myWindow2.On(events.Window.Close, func() {
        app.Quit()
    })
    app.Run()
}
```

--------------------------------

### Verify Node.js and npm installation

Source: https://v3.wails.io/contributing/setup

Check Node.js version (20+) and npm installation for frontend integration examples.

```bash
# Install Node.js 20+ and npm
node --version  # Should be 20+
npm --version

```

--------------------------------

### Screens.GetAll() and GetPrimary() JavaScript example

Source: https://v3.wails.io/reference/frontend-runtime

Example of listing all screens and getting the primary screen using the Screens API.

```javascript
import { Screens } from '@wailsio/runtime'

// List all screens
const screens = await Screens.GetAll()
screens.forEach(screen => {
    console.log(`${screen.Name}: ${screen.Size.Width}x${screen.Size.Height}`)
})

// Get primary screen
const primary = await Screens.GetPrimary()
console.log('Primary screen:', primary.Name)
```

--------------------------------

### pkg/application bootstrap example

Source: https://v3.wails.io/contributing/codebase-layout

Shows how to bootstrap a Wails program using the application package. It creates an application with options, creates a window, sets its title and size, and runs the app.

```go
func main() {
    app := application.New(application.Options{
        Name: "MyApp",
        Assets: application.AssetOptions{
            Handler: application.AssetFileServerFS(assetsFS),
        },
    })
    window := app.Window.New()
    window.SetTitle("Hello").SetSize(1024, 768)
    _ = app.Run()
}
```

--------------------------------

### Example valid installer-named assets

Source: https://v3.wails.io/guides/updater-github-release-assets

Shows examples of filenames that remain valid because they do not match the specific installer exclusion patterns.

```text
myinstaller.exe
installer-tool-windows-amd64.exe
myinstaller-windows-amd64.zip
```

--------------------------------

### Handling application events and shutdown

Source: https://v3.wails.io/reference/events

Example showing how to handle application startup and theme changes using event listeners, and how to configure shutdown cleanup.

```go
import "github.com/wailsapp/wails/v3/pkg/events"

// Handle application startup
app.Event.OnApplicationEvent(events.Common.ApplicationStarted, func(e *application.ApplicationEvent) {
    app.Logger.Info("Application started")
})

// React to theme changes
app.Event.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) {
    if e.Context().IsDarkMode() {
        app.Logger.Info("Dark mode enabled")
    }
})

// Shutdown cleanup is configured on the application, not as an event:
app.OnShutdown(func() {
    database.Close()
    saveSettings()
})
```

--------------------------------

### wails3 setup signing

Source: https://v3.wails.io/guides/build/signing

Interactive wizard to configure signing for your project. It guides through platform-specific signing setup for macOS, Windows, and Linux.

```APIDOC
## wails3 setup signing

### Description
Interactive wizard to configure signing for your project. Guides through platform-specific signing setup for macOS, Windows, and Linux.

### Method
CLI

### Endpoint
wails3 setup signing

### Parameters
#### Flags
- `--platform` (string) - Optional - Platform to configure (darwin, windows, linux). Repeatable. If omitted, auto-detects which platforms to configure from the build directory.

### Usage
```bash
wails3 setup signing [flags]
```

### Details
The wizard guides you through:
- **macOS**: Selecting a Developer ID certificate, configuring notarization credentials (calls `xcrun notarytool store-credentials`).
- **Windows**: Choosing between certificate file or thumbprint, setting password and timestamp server.
- **Linux**: Using an existing PGP key or generating a new one (calls `gpg`), configuring signing role.
```

--------------------------------

### v3 Application Initialisation with application.New and app.Window

Source: https://v3.wails.io/migration/v2-to-v3

v3 separates application creation, window creation, and execution into distinct phases. Create the application with application.New, then create a window with app.Window.New, and finally run with app.Run().

```go
app := application.New(application.Options{
    Name: "My App",
    Services: []application.Service{
        application.NewService(&GreetService{}),
    },
})

window := app.Window.New()

err := app.Run()
```

--------------------------------

### Get screen containing a window

Source: https://v3.wails.io/features/screens/info

Shows how to get the screen that contains a specific window using window.GetScreen(). The example prints the screen name and handles errors.

```go
screen, err := window.GetScreen()
if err != nil {
    // handle error
}
fmt.Printf("Window is on: %s\n", screen.Name)
```

--------------------------------

### Complete Browser Integration Example

Source: https://v3.wails.io/features/browser/integration

A complete example showing various browser integration patterns: setting up menus, opening URLs with confirmation, generating an HTML report, and opening it in the browser.

```go
package main

import (
    "fmt"
    "os"
    "path/filepath"
    "github.com/wailsapp/wails/v3/pkg/application"
)

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

    // Setup menu with browser actions
    setupMenu(app)

    // Create main window
    window := app.Window.New()
    window.SetTitle("Browser Integration")

    err := app.Run()
    if err != nil {
        panic(err)
    }
}

func setupMenu(app *application.App) {
    menu := app.Menu.New()
    
    // File menu
    fileMenu := menu.AddSubmenu("File")
    fileMenu.Add("Generate Report").OnClick(func(ctx *application.Context) {
        generateHTMLReport(app)
    })
    
    // Help menu
    helpMenu := menu.AddSubmenu("Help")
    helpMenu.Add("Documentation").OnClick(func(ctx *application.Context) {
        openWithConfirmation(app, "https://docs.example.com")
    })
    helpMenu.Add("Support").OnClick(func(ctx *application.Context) {
        openWithConfirmation(app, "https://support.example.com")
    })
    
    app.Menu.Set(menu)
}

func openWithConfirmation(app *application.App, url string) {
    dialog := app.Dialog.Question()
    dialog.SetTitle("Open External Link")
    dialog.SetMessage(fmt.Sprintf("Open %s in your browser?", url))
    
    dialog.AddButton("Open").OnClick(func() {
        if err := app.Browser.OpenURL(url); err != nil {
            showError(app, "Failed to open URL", err)
        }
    })
    
    dialog.AddButton("Cancel")
    dialog.Show()
}

func generateHTMLReport(app *application.App) {
    // Create temporary HTML file
    tmpDir := os.TempDir()
    reportPath := filepath.Join(tmpDir, "demo_report.html")
    
    html := `
<!DOCTYPE html>
<html>
<head>
    <title>Demo Report</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .header { color: #333; border-bottom: 1px solid #ccc; }
    </style>
</head>
<body>
    <div class="header">
        <h1>Application Report</h1>
        <p>This is a sample report generated by the application.</p>
    </div>
    <div class="content">
        <h2>Report Details</h2>
        <p>This report was generated to demonstrate browser integration.</p>
    </div>
</body>
</html>`
    
    err := os.WriteFile(reportPath, []byte(html), 0644)
    if err != nil {
        showError(app, "Failed to create report", err)
        return
    }
    
    // Open in browser
    err = app.Browser.OpenFile(reportPath)
    if err != nil {
        showError(app, "Failed to open report", err)
    }
}

func showError(app *application.App, message string, err error) {
    app.Dialog.Error().
        SetTitle("Error").
        SetMessage(fmt.Sprintf("%s: %v", message, err)).
        Show()
}
```

--------------------------------

### Add Gin dependency

Source: https://v3.wails.io/guides/gin-services

Install the Gin framework using go get.

```bash
go get github.com/gin-gonic/gin

```

--------------------------------

### Setup Help Menu with Online Documentation, GitHub, and Issue Links

Source: https://v3.wails.io/features/browser/integration

Creates a 'Help' submenu with items for online documentation, GitHub repository, and reporting issues. Each item opens a URL in the browser, with error handling for the documentation link.

```go
// Create help menu
func setupHelpMenu(app *application.App) {
    menu := app.Menu.New()
    helpMenu := menu.AddSubmenu("Help")
    
    helpMenu.Add("Online Documentation").OnClick(func(ctx *application.Context) {
        err := app.Browser.OpenURL("https://docs.yourapp.com")
        if err != nil {
            app.Dialog.Error().
                SetTitle("Error").
                SetMessage("Could not open documentation").
                Show()
        }
    })
    
    helpMenu.Add("GitHub Repository").OnClick(func(ctx *application.Context) {
        app.Browser.OpenURL("https://github.com/youruser/yourapp")
    })
    
    helpMenu.Add("Report Issue").OnClick(func(ctx *application.Context) {
        app.Browser.OpenURL("https://github.com/youruser/yourapp/issues/new")
    })
}
```

--------------------------------

### Install WebKit dependencies per distribution

Source: https://v3.wails.io/guides/build/linux

Install the required WebKitGTK dependency for Debian/Ubuntu, Fedora, or Arch Linux if the app fails to start due to missing dependencies.

```bash
# Debian/Ubuntu
sudo apt install libwebkit2gtk-4.1-0

# Fedora
sudo dnf install webkit2gtk4.1

# Arch
sudo pacman -S webkit2gtk-4.1
```

--------------------------------

### Enable Autostart Method

Source: https://v3.wails.io/features/autostart/basics

Registers the application to launch at login with default options. This method is safe to call repeatedly.

```go
func (m *AutostartManager) Enable() error
```

--------------------------------

### Install C compiler for CGO

Source: https://v3.wails.io/guides/build/linux

Install GCC or Clang via the distribution's package manager. Alternatively, run 'wails3 task setup:docker' to use Docker automatically.

```bash
# Debian/Ubuntu
sudo apt install build-essential

# Fedora
sudo dnf install gcc

# Arch
sudo pacman -S base-devel
```

--------------------------------

### Focus method signature and example

Source: https://v3.wails.io/reference/window

Brings the window to the front and gives it keyboard focus. The example brings the window to front.

```go
func (w *WebviewWindow) Focus()
```

```go
// Bring window to front
window.Focus()
```

--------------------------------

### Screen Manager Usage

Source: https://v3.wails.io/concepts/manager-api

Gets screen information and performs coordinate transformations for multi-monitor setups.

```go
// Get screen information
screens := app.Screen.GetAll()
primary := app.Screen.GetPrimary()

// Coordinate transformations
physicalPoint := app.Screen.DipToPhysicalPoint(logicalPoint)
logicalPoint := app.Screen.PhysicalToDipPoint(physicalPoint)

// Screen detection
screen := app.Screen.ScreenNearestDipPoint(point)
screen = app.Screen.ScreenNearestDipRect(rect)
```

--------------------------------

### Example Windows asset filtering

Source: https://v3.wails.io/guides/updater-github-release-assets

Demonstrates how DefaultAssetMatcher selects the application binary while ignoring the installer executable.

```text
myapp-windows-amd64.exe
myapp-windows-amd64-installer.exe
```

--------------------------------

### Size method signature and example

Source: https://v3.wails.io/reference/window

Returns the current window dimensions. The example prints the width and height.

```go
func (w *WebviewWindow) Size() (width, height int)
```

```go
width, height := window.Size()
fmt.Printf("Window is %dx%d\n", width, height)
```

--------------------------------

### ServeAssets Example Implementation

Source: https://v3.wails.io/guides/custom-transport

Example implementation of ServeAssets for a custom transport. It mounts an IPC endpoint and the Wails asset server on an HTTP mux, then starts the HTTP server. The assetHandler provides static assets and /wails/runtime.js.

```go
func (t *MyTransport) ServeAssets(assetHandler http.Handler) error {
    mux := http.NewServeMux()

    // Mount your IPC endpoint
    mux.HandleFunc("/my/ipc/endpoint", t.handleIPC)

    // Mount Wails asset server for everything else
    mux.Handle("/", assetHandler)

    // Start HTTP server
    t.httpServer.Handler = mux
    go t.httpServer.ListenAndServe()

    return nil
}
```

--------------------------------

### Manage Documentation with M-Press

Source: https://v3.wails.io/contributing/setup

Commands to install M-Press, start a development server, build the site, and validate documentation.

```bash
go install github.com/leaanthony/mpress/cmd/mpress@v1.0.17
mpress dev
mpress build --strict --no-purge-css
mpress check
# Use `python` on Windows if `python3` is unavailable.
python3 docs/mpress/scripts/check_site.py docs/mpress/site
```

--------------------------------

### Window Manager Usage

Source: https://v3.wails.io/concepts/manager-api

Demonstrates creating, retrieving, and managing windows, including lifecycle callbacks.

```go
// Create windows
window := app.Window.New()
window := app.Window.NewWithOptions(options)
current := app.Window.Current()

// Find windows
window, exists := app.Window.GetByName("main")
windows := app.Window.GetAll()

// Window callbacks
app.Window.OnCreate(func(window Window) {
    // Handle window creation
})
```

--------------------------------

### Frontend Integration Example (HTML + JavaScript)

Source: https://v3.wails.io/guides/gin-services

Complete example showing how to set up a frontend that interacts with Gin API endpoints and handles events. Includes buttons for API calls and a form for creating users.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Gin Service Example</title>
    <!-- Styles omitted for brevity -->
</head>
<body>
    <h1>Gin Service Example</h1>
    
    <div class="card">
        <h2>API Endpoints</h2>
        <p>Try the Gin API endpoints mounted at /api:</p>
        
        <button id="getInfo">Get Service Info</button>
        <button id="getUsers">Get All Users</button>
        <button id="getUser">Get User by ID</button>
        <button id="createUser">Create User</button>
        <button id="deleteUser">Delete User</button>

        <div id="apiResult">
            <pre id="apiResponse">Results will appear here...</pre>
        </div>
    </div>
    
    <div class="card">
        <h2>Event Communication</h2>
        <p>Trigger an event to communicate with the Gin service:</p>
        
        <button id="triggerEvent">Trigger Event</button>
        
        <div id="eventResult">
            <pre id="eventResponse">Event responses will appear here...</pre>
        </div>
    </div>
    
    <div class="card" id="createUserForm" style="display: none; border: 2px solid #0078d7;">
        <h2>Create New User</h2>

        <div>
            <label for="userName">Name:</label>
            <input type="text" id="userName" placeholder="Enter name">
        </div>

        <div>
            <label for="userEmail">Email:</label>
            <input type="email" id="userEmail" placeholder="Enter email">
        </div>

        <button id="submitUser">Submit</button>
        <button id="cancelCreate">Cancel</button>
    </div>

    <script type="module">
        // Import the Wails runtime
        // Note: In production, use '@wailsio/runtime' instead
        import * as wails from "/wails/runtime.js";
        
        // Helper function to fetch API endpoints
        async function fetchAPI(endpoint, options = {}) {
            try {
                const response = await fetch(`/api${endpoint}`, options);
                const data = await response.json();
                
                document.getElementById('apiResponse').textContent = JSON.stringify(data, null, 2);
                return data;
            } catch (error) {
                document.getElementById('apiResponse').textContent = `Error: ${error.message}`;
                console.error('API Error:', error);
            }
        }
        
        // Event listeners for API buttons
        document.getElementById('getInfo').addEventListener('click', () => {
            fetchAPI('/info');
        });
        
        document.getElementById('getUsers').addEventListener('click', () => {
            fetchAPI('/users');
        });

        document.getElementById('getUser').addEventListener('click', async () => {
            const userId = prompt('Enter user ID:');
            if (userId) {
                await fetchAPI(`/users/${userId}`);
            }
        });

        document.getElementById('createUser').addEventListener('click', () => {
            const form = document.getElementById('createUserForm');
            form.style.display = 'block';
            form.scrollIntoView({ behavior: 'smooth' });
        });

        document.getElementById('cancelCreate').addEventListener('click', () => {
            document.getElementById('createUserForm').style.display = 'none';
        });

        document.getElementById('submitUser').addEventListener('click', async () => {
            const name = document.getElementById('userName').value;
            const email = document.getElementById('userEmail').value;

            if (!name || !email) {
                alert('Please enter both name and email');
                return;
            }

            try {
                await fetchAPI('/users', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({ name, email })
                });

                // Additional code omitted for brevity
            } catch (error) {
                console.error('Error creating user:', error);
            }
        });

        // Event listener for triggering events
        document.getElementById('triggerEvent').addEventListener('click', () => {
            wails.Events.Emit('gin-api-event', { message: 'Hello from frontend!' });
        });
    </script>
</body>
</html>

```

--------------------------------

### Get all windows

Source: https://v3.wails.io/features/windows/basics

Use app.Window.GetAll to retrieve all windows. The example prints the total count and iterates over each window to print its name and ID.

```go
windows := app.Window.GetAll()
fmt.Printf("Total windows: %d\n", len(windows))

for _, w := range windows {
    fmt.Printf("Window: %s (ID: %d)\n", w.Name(), w.ID())
}
```

--------------------------------

### Fullscreen() / UnFullscreen() / ToggleFullscreen() example

Source: https://v3.wails.io/reference/window

Example usage of Fullscreen(), UnFullscreen(), and ToggleFullscreen() to enter, exit, or toggle fullscreen mode.

```go
// Enter fullscreen
window.Fullscreen()

// Exit fullscreen
window.UnFullscreen()

// Or toggle
window.ToggleFullscreen()
```

--------------------------------

### Get screen by ID

Source: https://v3.wails.io/features/screens/info

Retrieves a screen by its ID using app.Screen.GetByID(). The example checks for nil and prints the screen name if found.

```go
screen := app.Screen.GetByID("screen-id")
if screen != nil {
    fmt.Printf("Found screen: %s\n", screen.Name)
}
```

--------------------------------

### Enable Autostart in main.go

Source: https://v3.wails.io/features/autostart/basics

Demonstrates how to conditionally enable autostart during application initialization using the app.Autostart.Enable() method.

```go
package main

import (
    "errors"

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

func main() {
    app := application.New(application.Options{
        Name: "My App",
    })

    // Restore the user's preference on startup
    if userPrefersAutostart() {
        if err := app.Autostart.Enable(); err != nil {
            if !errors.Is(err, application.ErrAutostartNotSupported) {
                app.Logger.Error("autostart", "error", err)
            }
        }
    }

    app.Run()
}
```

--------------------------------

### Run the Wails setup wizard

Source: https://v3.wails.io/getting-started/installation

After installing the CLI, run this command to configure your development environment. The wizard checks and helps install platform dependencies, configures project defaults, optionally sets up Docker for cross-platform builds, and configures code signing.

```shell
wails3 setup
```

--------------------------------

### OnWindowEvent example - listening to window events

Source: https://v3.wails.io/reference/window

Shows how to listen for window focus, lost focus, and resize events using events.Common constants.

```go
import "github.com/wailsapp/wails/v3/pkg/events"

// Listen for window focus
window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window gained focus")
})

// Listen for window lost focus
window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window lost focus")
})

// Listen for window resize
window.OnWindowEvent(events.Common.WindowDidResize, func(e *application.WindowEvent) {
    app.Logger.Info("Window resized")
})
```

--------------------------------

### Quick Start: Copy and Get Clipboard Text in Go

Source: https://v3.wails.io/features/clipboard/basics

Shows the minimal Wails clipboard usage: SetText writes a string, Text() returns the current clipboard value and a boolean indicating success. Use this as the starting point for cross-platform clipboard access.

```go
// Copy text to clipboard
app.Clipboard.SetText("Hello, World!")

// Get text from clipboard
text, ok := app.Clipboard.Text()
if ok {
    fmt.Println("Clipboard:", text)
}
```

--------------------------------

### Streaming with Events: Polling vs Event-Driven

Source: https://v3.wails.io/features/bindings/best-practices

Compares polling with event-driven streaming. The bad example polls GetProgress every 100ms; the good example emits a 'progress' event from Go and listens in JavaScript using Events.On from @wailsio/runtime. Includes setup comments for the Service struct.

```go
// ❌ Bad: Polling
func (s *Service) GetProgress() int {
    return s.progress
}

// JavaScript polls
setInterval(async () => {
    const progress = await GetProgress()
    updateUI(progress)
}, 100)

// ✅ Good: Events
// Service must hold a reference to *application.App to emit events / log:
//
//   type Service struct {
//       app *application.App
//   }
//
//   func NewService(app *application.App) *Service {
//       return &Service{app: app}
//   }
//
//   app := application.New(application.Options{})
//   app.RegisterService(application.NewService(NewService(app)))

func (s *Service) ProcessLargeFile(path string) error {
    file, err := os.Open(path)
    if err != nil {
        return err
    }
    defer file.Close()
    
    scanner := bufio.NewScanner(file)
    total := 0
    processed := 0
    
    // Count lines
    for scanner.Scan() {
        total++
    }
    
    // Process
    file.Seek(0, 0)
    scanner = bufio.NewScanner(file)
    
    for scanner.Scan() {
        s.processLine(scanner.Text())
        processed++
        
        // Emit progress
        s.app.Event.Emit("progress", map[string]interface{}{
            "processed": processed,
            "total":     total,
            "percent":   int(float64(processed) / float64(total) * 100),
        })
    }
    
    return scanner.Err()
}

// JavaScript listens
import { Events } from '@wailsio/runtime'

Events.On("progress", (event) => {
    updateProgress(event.data.percent)
})
```

--------------------------------

### Run the MCP example application

Source: https://v3.wails.io/guides/mcp-service

Run the example application from the v3/examples/mcp directory with the mcp build tag. Connect an MCP client to http://127.0.0.1:9099/mcp.

```shell
cd v3/examples/mcp
go run -tags mcp .

```

--------------------------------

### Complete example using @wailsio/runtime

Source: https://v3.wails.io/reference/frontend-runtime

A complete JavaScript example demonstrating event listening, window management, clipboard operations, dialogs with confirmation, and screen information using the @wailsio/runtime package.

```javascript
import { Events, Window, Clipboard, Dialogs, Screens } from '@wailsio/runtime'

// Listen for events from Go
Events.On('data-updated', (event) => {
    console.log('Data:', event.data)
    updateUI(event.data)
})

// Window management
document.getElementById('center-btn').addEventListener('click', async () => {
    await Window.Center()
})

document.getElementById('fullscreen-btn').addEventListener('click', async () => {
    const isFullscreen = await Window.IsFullscreen()
    if (isFullscreen) {
        await Window.UnFullscreen()
    } else {
        await Window.Fullscreen()
    }
})

// Clipboard operations
document.getElementById('copy-btn').addEventListener('click', async () => {
    await Clipboard.SetText('Copied from Wails!')
})

// Dialog with confirmation
document.getElementById('delete-btn').addEventListener('click', async () => {
    const result = await Dialogs.Question({
        Title: 'Confirm',
        Message: 'Delete this item?',
        Buttons: [
            { Label: 'Delete' },
            { Label: 'Cancel', IsDefault: true }
        ]
    })

    if (result === 'Delete') {
        await Events.Emit('delete-item', { id: currentItemId })
    }
})

// Screen information
const screens = await Screens.GetAll()
console.log(`Detected ${screens.length} screen(s)`)
screens.forEach(screen => {
    console.log(`- ${screen.Name}: ${screen.Size.Width}x${screen.Size.Height}`)
})
```

--------------------------------

### Find Specific Window

Source: https://v3.wails.io/features/windows/multiple

Shows how to retrieve a window by name or ID, and get the current focused window. The examples use GetByName, GetByID, and Current methods.

```go
// By name
if settings, ok := app.Window.GetByName("settings"); ok {
    settings.Show()
}

// By ID
if window, ok := app.Window.GetByID(123); ok {
    window.Focus()
}

// Current (focused) window
current := app.Window.Current()
```

--------------------------------

### Screen Manager

Source: https://v3.wails.io/concepts/manager-api

Screen management and coordinate transformations for multi-monitor setups. Provides methods to get screens, primary screen, and convert between DIP and physical coordinates.

```APIDOC
## Screen Manager

### Description
Screen management and coordinate transformations for multi-monitor setups.

### Methods
- **GetAll()** - Returns all screens.
- **GetPrimary()** - Returns the primary screen.
- **DipToPhysicalPoint(logicalPoint)** - Converts a DIP point to a physical point.
- **PhysicalToDipPoint(physicalPoint)** - Converts a physical point to a DIP point.
- **ScreenNearestDipPoint(point)** - Returns the screen nearest to the given DIP point.
- **ScreenNearestDipRect(rect)** - Returns the screen nearest to the given DIP rectangle.

### Usage Example
```go
screens := app.Screen.GetAll()
primary := app.Screen.GetPrimary()
physicalPoint := app.Screen.DipToPhysicalPoint(logicalPoint)
logicalPoint := app.Screen.PhysicalToDipPoint(physicalPoint)
screen := app.Screen.ScreenNearestDipPoint(point)
screen = app.Screen.ScreenNearestDipRect(rect)
```
```

--------------------------------

### Set up system tray with app.SystemTray.New()

Source: https://v3.wails.io/faq

Wails v3 supports the system tray, including menus and click handlers. Create a system tray with `app.SystemTray.New()`, then set its icon and menu.

```go
systemTray := app.SystemTray.New()
systemTray.SetIcon(iconBytes)
systemTray.SetMenu(myMenu)

```

--------------------------------

### Logger Usage in Service Method

Source: https://v3.wails.io/reference/application

Example of using the logger within a service method. Logs the start and completion of processing, and logs an error with the error value if processing fails.

```go
func (s *MyService) ProcessData(data string) error {
    s.app.Logger.Info("Processing data", "length", len(data))
    
    if err := process(data); err != nil {
        s.app.Logger.Error("Processing failed", "error", err)
        return err
    }
    
    s.app.Logger.Info("Processing complete")
    return nil
}
```
Tokens:
Raw