Skip to content
Wails Blog

Events

Wails provides a flexible event system that enables communication between different parts of your application. This includes both application-level and window-level events.

Application Events

Application events are triggered by application-level state changes such as application startup, theme changes, and power events. You can listen for these events using the OnApplicationEvent method:

app.OnApplicationEvent(events.Mac.ApplicationDidBecomeActive, func(event *application.ApplicationEvent) {
    app.Logger.Info("Application started!")
})


app.OnApplicationEvent(events.Windows.SystemThemeChanged, func(event *application.ApplicationEvent) {
    app.Logger.Info("System theme changed!")
    if event.Context().IsDarkMode() {
      app.Logger.Info("System is now using dark mode!")
    } else {
      app.Logger.Info("System is now using light mode!")
    }
  })

Common Application Events

Common application events are aliases for platform-specific application events. These events are triggered by application-level state changes such as application startup, theme changes, and power events.

Here is the same example as above, but using common application events to make it work across all platforms:

app.OnApplicationEvent(events.Common.ApplicationStarted, func(event *application.ApplicationEvent) {
    app.Logger.Info("Application started!")
})


app.OnApplicationEvent(events.Common.ThemeChanged, func(event *application.ApplicationEvent) {
    if event.Context().IsDarkMode() {
        app.Logger.Info("System is now using dark mode!")
    } else {
        app.Logger.Info("System is now using light mode!")
    }
})

Common Application Event List

Event NameDescription
ApplicationOpenedWithFileApplication opened with a file. See File Associations for more information.
ApplicationStartedApplication has started
ThemeChangedSystem theme changed

Platform-Specific Application Events

Below is a list of all platform-specific application events.

Event NameCommon EventDescription
ApplicationDidBecomeActive-Application became active
ApplicationDidChangeBackingProperties-Application backing properties changed
ApplicationDidChangeEffectiveAppearanceThemeChangedApplication appearance changed
ApplicationDidChangeIcon-Application icon changed
ApplicationDidChangeOcclusionState-Application occlusion state changed
ApplicationDidChangeScreenParameters-Screen parameters changed
ApplicationDidChangeStatusBarFrame-Status bar frame changed
ApplicationDidChangeStatusBarOrientation-Status bar orientation changed
ApplicationDidChangeThemeThemeChangedSystem theme changed
ApplicationDidFinishLaunchingApplicationStartedApplication finished launching
ApplicationDidHide-Application hidden
ApplicationDidResignActiveNotification-Application resigned active state
ApplicationDidUnhide-Application unhidden
ApplicationDidUpdate-Application updated
ApplicationShouldHandleReopen-Application should handle reopen
ApplicationWillBecomeActive-Application will become active
ApplicationWillFinishLaunching-Application will finish launching
ApplicationWillHide-Application will hide
ApplicationWillResignActiveNotification-Application will resign active state
ApplicationWillTerminate-Application will terminate
ApplicationWillUnhide-Application will unhide
ApplicationWillUpdate-Application will update

Window Events

Window events are triggered by window-specific actions such as resizing, moving, or changing focus state. You can listen for these events using the OnWindowEvent method:

window.OnWindowEvent(events.Common.WindowClosing, func(e *application.WindowEvent) {
    app.Logger.Info("Window is closing!")
})


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

Hooks vs Standard Listeners

Wails provides two ways to handle window events: standard listeners (OnWindowEvent) and hooks (RegisterHook). The key differences are:

  1. Execution Order: Hooks are executed first and in the order they are registered, while standard listeners execute after Hooks and have no guaranteed order.
  2. Blocking: Hooks are blocking and must complete before the next hook is executed. Standard listeners are non-blocking.
  3. Event Cancellation: When cancelling an event in a Hook, it prevents it from propagating further. This is useful to prevent default behaviour, such as closing a window. Cancelling an event in a standard listener will only prevent it from being emitted from that point in time.

In this example, the window will only close after the close button has been clicked three times, demonstrating how hooks can be used to control event flow.

// Hook - runs synchronously. The window will not close until the countdown reaches zero.
var countdown = 3
window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    countdown--
    if countdown == 0 {
        app.Logger.Info("Window closing - countdown reached zero!")
        return
    }
    app.Logger.Info("Preventing window from closing - countdown:", countdown)
    e.Cancel()
})

This next example demonstrates the execution order of hooks vs standard listeners.

window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("I always run after hooks!")
})


// Multiple hooks are executed in order
window.RegisterHook(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("First focus hook - will always run first!")
})
window.RegisterHook(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Second focus hook - will always run second!")
})

This produces the following output:

INF First focus hook - will always run first!
INF Second focus hook - will always run second!
INF I always run after hooks!

Common Window Events

Event NameDescription
WindowClosingWindow is closing
WindowDidMoveWindow moved
WindowDidResizeWindow resized
WindowDPIChangedWindow DPI changed
WindowFilesDroppedFiles dropped on window
WindowFocusWindow gained focus
WindowFullscreenWindow entered fullscreen
WindowHideWindow hidden
WindowLostFocusWindow lost focus
WindowMaximiseWindow maximised
WindowMinimiseWindow minimised
WindowRestoreWindow restored
WindowRuntimeReadyWindow runtime is ready
WindowShowWindow shown
WindowUnFullscreenWindow exited fullscreen
WindowUnMaximiseWindow unmaximised
WindowUnMinimiseWindow unminimised
WindowZoomWindow zoomed
WindowZoomInWindow zoomed in
WindowZoomOutWindow zoomed out
WindowZoomResetWindow zoom reset

Platform-Specific Window Events

Event NameCommon EventDescription
WindowDidBecomeKeyWindowFocusWindow became key window
WindowDidBecomeMain-Window became main window
WindowDidBeginSheet-Sheet began
WindowDidChangeAlpha-Window alpha changed
WindowDidChangeBackingLocation-Window backing location changed
WindowDidChangeBackingProperties-Window backing properties changed
WindowDidChangeCollectionBehavior-Window collection behaviour changed
WindowDidChangeEffectiveAppearance-Window appearance changed
WindowDidChangeOcclusionState-Window occlusion state changed
WindowDidChangeOrderingMode-Window ordering mode changed
WindowDidChangeScreen-Window screen changed
WindowDidChangeScreenParameters-Window screen parameters changed
WindowDidChangeScreenProfile-Window screen profile changed
WindowDidChangeScreenSpace-Window screen space changed
WindowDidChangeScreenSpaceProperties-Window screen space properties changed
WindowDidChangeSharingType-Window sharing type changed
WindowDidChangeSpace-Window space changed
WindowDidChangeSpaceOrderingMode-Window space ordering mode changed
WindowDidChangeTitle-Window title changed
WindowDidChangeToolbar-Window toolbar changed
WindowDidDeminiaturizeWindowUnMinimiseWindow unminimised
WindowDidEndSheet-Sheet ended
WindowDidEnterFullScreenWindowFullscreenWindow entered fullscreen
WindowDidEnterVersionBrowser-Window entered version browser
WindowDidExitFullScreenWindowUnFullscreenWindow exited fullscreen
WindowDidExitVersionBrowser-Window exited version browser
WindowDidExpose-Window exposed
WindowDidFocusWindowFocusWindow gained focus
WindowDidMiniaturizeWindowMinimiseWindow minimised
WindowDidMoveWindowDidMoveWindow moved
WindowDidOrderOffScreen-Window ordered off screen
WindowDidOrderOnScreen-Window ordered on screen
WindowDidResignKey-Window resigned key window
WindowDidResignMain-Window resigned main window
WindowDidResizeWindowDidResizeWindow resized
WindowDidUpdate-Window updated
WindowDidUpdateAlpha-Window alpha updated
WindowDidUpdateCollectionBehavior-Window collection behaviour updated
WindowDidUpdateCollectionProperties-Window collection properties updated
WindowDidUpdateShadow-Window shadow updated
WindowDidUpdateTitle-Window title updated
WindowDidUpdateToolbar-Window toolbar updated
WindowDidZoomWindowZoomWindow zoomed
WindowFileDraggingEntered-File dragging entered window
WindowFileDraggingExited-File dragging exited window
WindowFileDraggingPerformed-File dragging performed
WindowHideWindowHideWindow hidden
WindowMaximiseWindowMaximiseWindow maximised
WindowShouldCloseWindowClosingWindow should close
WindowShowWindowShowWindow shown
WindowUnMaximizeWindowUnMaximiseWindow unmaximised
WindowZoomInWindowZoomInWindow zoomed in
WindowZoomOutWindowZoomOutWindow zoomed out
WindowZoomResetWindowZoomResetWindow zoom reset
---------------------------------------

Menu events are triggered by menu-specific actions such as opening, closing, and interacting with menu items. These events are useful for creating dynamic menus and responding to menu interactions.

// Listen for menu events
app.OnApplicationEvent(events.Mac.MenuDidOpen, func(event *application.ApplicationEvent) {
    app.Logger.Info("Menu opened!")
})


app.OnApplicationEvent(events.Mac.MenuWillSendAction, func(event *application.ApplicationEvent) {
    app.Logger.Info("Menu about to send action!")
})

For more information about menus, see the Application Menu and Context Menu documentation.

Platform-Specific Menu Events

Event NameDescription
MenuDidAddItemMenu item added
MenuDidBeginTrackingMenu began tracking
MenuDidCloseMenu closed
MenuDidDisplayItemMenu item displayed
MenuDidEndTrackingMenu ended tracking
MenuDidHighlightItemMenu item highlighted
MenuDidOpenMenu opened
MenuDidPopUpMenu popped up
MenuDidRemoveItemMenu item removed
MenuDidSendActionMenu sent action
MenuDidSendActionToItemMenu sent action to item
MenuDidUpdateMenu updated
MenuWillAddItemMenu will add item
MenuWillBeginTrackingMenu will begin tracking
MenuWillDisplayItemMenu will display item
MenuWillEndTrackingMenu will end tracking
MenuWillHighlightItemMenu will highlight item
MenuWillOpenMenu will open
MenuWillPopUpMenu will pop up
MenuWillRemoveItemMenu will remove item
MenuWillSendActionMenu will send action
MenuWillSendActionToItemMenu will send action to item
MenuWillUpdateMenu will update

WebView Events

WebView events are triggered by navigation and loading state changes in the WebView component. These events are useful for tracking page loads and navigation state.

// Listen for WebView navigation events
app.OnApplicationEvent(events.Mac.WebViewDidStartProvisionalNavigation, func(event *application.ApplicationEvent) {
    app.Logger.Info("WebView started loading a page!")
})


app.OnApplicationEvent(events.Mac.WebViewDidFinishNavigation, func(event *application.ApplicationEvent) {
    app.Logger.Info("WebView finished loading the page!")
})


// On Windows
app.OnApplicationEvent(events.Windows.WebViewNavigationCompleted, func(event *application.ApplicationEvent) {
    app.Logger.Info("WebView navigation completed!")
})

Platform-Specific WebView Events

Event NameDescription
WebViewDidCommitNavigationNavigation committed
WebViewDidFinishNavigationNavigation finished
WebViewDidReceiveServerRedirectForProvisionalNavigationServer redirect received
WebViewDidStartProvisionalNavigationProvisional navigation started

Custom Events

You can emit and listen for custom events to enable communication between different parts of your application.

Emitting Events

You can emit custom events from anywhere in your application:

// Emit an event with data from the application
app.EmitEvent("myevent", "hello")


// Emit from a specific window
window.EmitEvent("windowevent", "window specific data")

Handling Custom Events

Listen for custom events using the OnEvent method:

app.OnEvent("myevent", func(e *application.CustomEvent) {
    // Access event information
    name := e.Name        // Event name
    data := e.Data        // Event data
    sender := e.Sender    // Name of the window sending the event, or "" if sent from application
    cancelled := e.IsCancelled()  // Event cancellation status
})

Event Cancellation

Events can be cancelled to prevent their default behaviour or stop propagation to other listeners. This is particularly useful for hooks that need to control window closing, menu actions, or other system events.

Cancelling Events

To cancel an event, call the Cancel() method on the event object:

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    // Prevent the window from closing
    e.Cancel()
})

Checking Event Cancellation

You can check if an event has been cancelled using the IsCancelled() method:

window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    if e.IsCancelled() {
        app.Logger.Info("Window closing was cancelled by another hook")
        return
    }
    // Process event
})


// For custom events
app.OnEvent("myevent", func(e *application.CustomEvent) {
    if e.IsCancelled() {
        app.Logger.Info("Event was cancelled")
        return
    }
    // Process event
})