Window API

Overview

The Window API provides methods to control window appearance, behaviour, and lifecycle. Access through window instances or the Window manager.

Common operations:

• Create and show windows
• Control size, position, and state
• Handle window events
• Manage window content
• Configure appearance and behaviour

Visibility

Show()

Shows the window. If the window was hidden, it becomes visible.

func (w *Window) Show()

Example:

window := app.Window.New()
window.Show()

Hide()

Hides the window without closing it. The window remains in memory and can be shown again.

func (w *Window) Hide()

Example:

// Hide window temporarily
window.Hide()

// Show it again later
window.Show()

Use cases:

• System tray applications that hide to tray
• Wizard flows where windows are reused
• Temporary hiding during operations

Close()

Closes the window. This triggers the WindowClosing event.

func (w *Window) Close()

Example:

window.Close()

Note: If a registered hook calls event.Cancel(), the close will be prevented.

Window Properties

SetTitle()

Sets the window title bar text.

func (w *Window) SetTitle(title string)

Parameters:

• title - The new window title

Example:

window.SetTitle("My Application - Document.txt")

Name()

Returns the window’s unique name identifier.

func (w *Window) Name() string

Example:

name := window.Name()
fmt.Println("Window name:", name)

// Retrieve window by name later
window := app.GetWindowByName(name)

Size and Position

SetSize()

Sets the window dimensions in pixels.

func (w *Window) SetSize(width, height int)

Parameters:

• width - Window width in pixels
• height - Window height in pixels

Example:

window.SetSize(1024, 768)

Size()

Returns the current window dimensions.

func (w *Window) Size() (width, height int)

Example:

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

SetMinSize() / SetMaxSize()

Sets minimum and maximum window dimensions.

func (w *Window) SetMinSize(width, height int)
func (w *Window) SetMaxSize(width, height int)

Example:

// Prevent window from being too small
window.SetMinSize(800, 600)

// Prevent window from being too large
window.SetMaxSize(1920, 1080)

SetPosition()

Sets the window position relative to the top-left corner of the screen.

func (w *Window) SetPosition(x, y int)

Parameters:

• x - Horizontal position in pixels
• y - Vertical position in pixels

Example:

// Position window at top-left
window.SetPosition(0, 0)

// Position window 100px from top-left
window.SetPosition(100, 100)

Position()

Returns the current window position.

func (w *Window) Position() (x, y int)

Example:

x, y := window.Position()
fmt.Printf("Window is at (%d, %d)\n", x, y)

Centre()

Centers the window on the screen.

func (w *Window) Centre()

Example:

window := app.Window.New()
window.Centre()
window.Show()

Note: Centre on the primary monitor. For multi-monitor setups, see screen APIs.

SetFocus()

Brings the window to the front and gives it keyboard focus.

func (w *Window) SetFocus()

Example:

// Bring window to front
window.SetFocus()

Window State

Minimise() / UnMinimise()

Minimizes the window to the taskbar/dock or restores it.

func (w *Window) Minimise()
func (w *Window) UnMinimise()

Example:

// Minimize window
window.Minimise()

// Restore from minimized state
window.UnMinimise()

Maximise() / UnMaximise()

Maximizes the window to fill the screen or restores it to its previous size.

func (w *Window) Maximise()
func (w *Window) UnMaximise()

Example:

// Maximize window
window.Maximise()

// Restore to previous size
window.UnMaximise()

Fullscreen() / UnFullscreen()

Enters or exits fullscreen mode.

func (w *Window) Fullscreen()
func (w *Window) UnFullscreen()

Example:

// Enter fullscreen
window.Fullscreen()

// Exit fullscreen
window.UnFullscreen()

IsMinimised() / IsMaximised() / IsFullscreen()

Checks the current window state.

func (w *Window) IsMinimised() bool
func (w *Window) IsMaximised() bool
func (w *Window) IsFullscreen() bool

Example:

if window.IsMinimised() {
    window.UnMinimise()
}

if window.IsMaximised() {
    fmt.Println("Window is maximized")
}

if window.IsFullscreen() {
    window.UnFullscreen()
}

Window Content

SetURL()

Navigates to a specific URL within the window.

func (w *Window) SetURL(url string)

Parameters:

• url - URL to navigate to (can be http://wails.localhost/ for embedded assets)

Example:

// Navigate to embedded page
window.SetURL("http://wails.localhost/settings.html")

// Navigate to external URL (if allowed)
window.SetURL("https://wails.io")

SetHTML()

Sets the window content directly from an HTML string.

func (w *Window) SetHTML(html string)

Parameters:

• html - HTML content to display

Example:

html := `
<!DOCTYPE html>
<html>
<head><title>Dynamic Content</title></head>
<body>
    <h1>Hello from Go!</h1>
    <p>This content was generated dynamically.</p>
</body>
</html>
`
window.SetHTML(html)

Use cases:

• Dynamic content generation
• Simple windows without frontend build process
• Error pages or splash screens

Reload()

Reloads the current window content.

func (w *Window) Reload()

Example:

// Reload current page
window.Reload()

Note: Useful during development or when content needs refreshing.

Window Events

Wails provides two methods for handling window events:

• OnWindowEvent() - Listen to window events (cannot prevent them)
• RegisterHook() - Hook into window events (can prevent them by calling event.Cancel())

OnWindowEvent()

Registers a callback for window events.

func (w *Window) OnWindowEvent(
    eventType events.WindowEventType,
    callback func(event *WindowEvent),
) func()

Returns: Cleanup function to remove the event listener

Example:

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")
})

Common Window Events:

• events.Common.WindowClosing - Window is about to close
• events.Common.WindowFocus - Window gained focus
• events.Common.WindowLostFocus - Window lost focus
• events.Common.WindowDidMove - Window moved
• events.Common.WindowDidResize - Window resized
• events.Common.WindowMinimise - Window minimized
• events.Common.WindowMaximise - Window maximized
• events.Common.WindowFullscreen - Window entered fullscreen

RegisterHook()

Registers a hook for window events. Hooks run before listeners and can prevent the event by calling event.Cancel().

func (w *Window) RegisterHook(
    eventType events.WindowEventType,
    callback func(event *WindowEvent),
) func()

Returns: Cleanup function to remove the hook

Example - Prevent window close:

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

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    result, _ := app.Dialog.Question().
        SetTitle("Confirm Close").
        SetMessage("Are you sure you want to close this window?").
        SetButtons("Yes", "No").
        Show()

    if result == "No" {
        e.Cancel()  // Prevent window from closing
    }
})

Example - Save before closing:

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    if hasUnsavedChanges {
        result, _ := app.Dialog.Question().
            SetMessage("Save changes before closing?").
            SetButtons("Save", "Don't Save", "Cancel").
            Show()

        switch result {
        case "Save":
            saveData()
            // Allow close
        case "Don't Save":
            // Allow close
        case "Cancel":
            e.Cancel()  // Prevent close
        }
    }
})

EmitEvent()

Emits a custom event to the window’s frontend.

func (w *Window) EmitEvent(name string, data ...interface{})

Parameters:

• name - Event name
• data - Optional data to send with the event

Example:

// Send data to specific window
window.EmitEvent("data-updated", map[string]interface{}{
    "count": 42,
    "status": "success",
})

Frontend (JavaScript):

import { Events } from '@wailsio/runtime'

Events.On('data-updated', (data) => {
    console.log('Count:', data.count)
    console.log('Status:', data.status)
})

Other Methods

SetEnabled()

Enables or disables user interaction with the window.

func (w *Window) SetEnabled(enabled bool)

Example:

// Disable window during long operation
window.SetEnabled(false)

// Perform operation
performLongOperation()

// Re-enable window
window.SetEnabled(true)

SetBackgroundColour()

Sets the window background color (shown before content loads).

func (w *Window) SetBackgroundColour(r, g, b, a uint8)

Parameters:

• r - Red (0-255)
• g - Green (0-255)
• b - Blue (0-255)
• a - Alpha/opacity (0-255)

Example:

// Set white background
window.SetBackgroundColour(255, 255, 255, 255)

// Set dark background
window.SetBackgroundColour(30, 30, 30, 255)

SetResizable()

Controls whether the window can be resized by the user.

func (w *Window) SetResizable(resizable bool)

Example:

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

SetAlwaysOnTop()

Sets whether the window stays above other windows.

func (w *Window) SetAlwaysOnTop(alwaysOnTop bool)

Example:

// Keep window on top
window.SetAlwaysOnTop(true)

Print()

Opens the native print dialog for the window content.

func (w *Window) Print() error

Returns: Error if printing fails

Example:

err := window.Print()
if err != nil {
    log.Println("Print failed:", err)
}

AttachModal()

Attaches a second Window as a sheet modal.

func (w *Window) AttachModal(modalWindow Window)

Parameters:

• modalWindow - The window to attach as a modal

Platform support:

• macOS: Full support (presents as a sheet)
• Windows: No support
• Linux: No support

Example:

modalWindow := app.Window.New()
window.AttachModal(modalWindow)

Platform-Specific Options

Linux

Linux windows support the following platform-specific options via LinuxWindow:

MenuStyle

Controls how the application menu is displayed. This option is only available on GTK4 builds and is ignored on GTK3.

Value	Description
LinuxMenuStyleMenuBar	Traditional menu bar below the title bar (default)
LinuxMenuStylePrimaryMenu	Primary menu button in the header bar (GNOME style)

Example:

window := app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
    Title: "My Application",
    Linux: application.LinuxWindow{
        MenuStyle: application.LinuxMenuStylePrimaryMenu,
    },
})
window.SetMenu(menu)

Note: The primary menu style displays a hamburger button (☰) in the header bar, following GNOME Human Interface Guidelines. This is the recommended style for modern GNOME applications.

Complete Example

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 behavior
    window.SetResizable(true)
    window.SetMinSize(800, 600)
    window.SetMaxSize(1920, 1080)

    // Set up event hooks
    window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        // Confirm before closing
        result, _ := app.Dialog.Question().
            SetTitle("Confirm Close").
            SetMessage("Are you sure you want to close this window?").
            SetButtons("Yes", "No").
            Show()

        if result == "No" {
            e.Cancel()
        }
    })

    // 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.Centre()
    window.Show()

    app.Run()
}