The application API assists in creating an application using the Wails +framework.
+API: New(appOptions Options) *App
New(appOptions Options) creates a new application using the given application
+options . It applies default values for unspecified options, merges them with
+the provided ones, initializes and returns an instance of the application.
In case of an error during initialization, the application is stopped with the +error message provided.
+It should be noted that if a global application instance already exists, that +instance will be returned instead of creating a new one.
+package main
+
+import "github.com/wailsapp/wails/v3/pkg/application"
+
+func main() {
+ app := application.New(application.Options{
+ Name: "WebviewWindow Demo",
+ // Other options
+ })
+
+ // Rest of application
+}
+Get() returns the global application instance. It's useful when you need to
+access the application from different parts of your code.
API: Capabilities() capabilities.Capabilities
Capabilities() retrieves a map of capabilities that the application currently
+has. Capabilities can be about different features the operating system provides,
+like webview features.
// Get the application capabilities
+ capabilities := app.Capabilities()
+ if capabilities.HasNativeDrag {
+ // Do something
+ }
+API: GetPID() int
GetPID() returns the Process ID of the application.
API: Run() error
Run() starts the execution of the application and its components.
app := application.New(application.Options{
+ //options
+ })
+ // Run the application
+ err := application.Run()
+ if err != nil {
+ // Handle error
+ }
+API: Quit()
Quit() quits the application by destroying windows and potentially other
+components.
API: IsDarkMode() bool
IsDarkMode() checks if the application is running in dark mode. It returns a
+boolean indicating whether dark mode is enabled.
API: Hide()
Hide() hides the application window.
API: Show()
Show() shows the application window.
API: Path(selector Path) string
Path(selector Path) returns the full path for the given path type. It provides a cross-platform way to query common application directories.
The Path type is an enum with the following values:
+- PathHome: Returns the user's home directory
+- PathDataHome: Returns the path to the user's data directory
+- PathConfigHome: Returns the path to the user's configuration directory
+- PathStateHome: Returns the path to the user's state directory
+- PathCacheHome: Returns the path to the user's cache directory
+- PathRuntimeDir: Returns the path to the user's runtime directory
+- PathDesktop: Returns the path to the user's desktop directory
+- PathDownload: Returns the path to the user's download directory
+- PathDocuments: Returns the path to the user's documents directory
+- PathMusic: Returns the path to the user's music directory
+- PathPictures: Returns the path to the user's pictures directory
+- PathVideos: Returns the path to the user's videos directory
+- PathTemplates: Returns the path to the user's templates directory
+- PathPublicShare: Returns the path to the user's public share directory
// Get the data home directory path
+ dataHomePath := app.Path(application.PathDataHome)
+ fmt.Println("DataHome path:", dataHomePath)
+
+ // Output: DataHome path: /home/username/.local/share // Linux
+ // Output: DataHome path: /Users/username/Library/Application Support // macOS
+ // Output: DataHome path: C:\Users\Username\AppData\Roaming // Windows
+
+ // Get the CacheHome directory path
+ cacheHomePath := app.Path(application.CacheHome)
+ fmt.Println("CacheHome path:", cacheHomePath)
+
+ // Output: CacheHome path: /home/username/.cache // Linux
+ // Output: CacheHome path: /Users/username/Library/Caches // macOS
+ // Output: CacheHome path: C:\Users\Username\AppData\Local\Temp // Windows
+API: Paths(selector Paths) []string
+Paths(selector Path) returns a list of paths for the given path type. It provides a cross-platform way to query common directory paths.
The Paths type is an enum with the following values:
+- PathsDataDirs: Returns the list of data directories
+- PathsConfigDirs: Returns the list of configuration directories
+- PathsCacheDirs: Returns the list of cache directories
+- PathsRuntimeDirs: Returns the list of runtime directories
API: NewWebviewWindow() *WebviewWindow
NewWebviewWindow() creates a new Webview window with default options, and
+returns it.
API:
+NewWebviewWindowWithOptions(windowOptions WebviewWindowOptions) *WebviewWindow
NewWebviewWindowWithOptions() creates a new webview window with custom
+options. The newly created window is added to a map of windows managed by the
+application.
// Create a new webview window with custom options
+ window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
+ Name: "Main",
+ Title: "My Window",
+ Width: 800,
+ Height: 600,
+ })
+API: OnWindowCreation(callback func(window *WebviewWindow))
OnWindowCreation() registers a callback function to be called when a window is
+created.
// Register a callback to be called when a window is created
+ app.OnWindowCreation(func(window *WebviewWindow) {
+ // Do something
+ })
+API: GetWindowByName(name string) *WebviewWindow
GetWindowByName() fetches and returns a window with a specific name.
API: CurrentWindow() *WebviewWindow
CurrentWindow() fetches and returns a pointer to the currently active window
+in the application. If there is no window, it returns nil.
API: RegisterContextMenu(name string, menu *Menu)
RegisterContextMenu() registers a context menu with a given name. This menu
+can be used later in the application.
// Create a new menu
+ ctxmenu := app.NewMenu()
+
+ // Register the menu as a context menu
+ app.RegisterContextMenu("MyContextMenu", ctxmenu)
+API: SetMenu(menu *Menu)
SetMenu() sets the menu for the application. On Mac, this will be the global
+menu. For Windows and Linux, this will be the default menu for any new window
+created.
// Create a new menu
+ menu := app.NewMenu()
+
+ // Set the menu for the application
+ app.SetMenu(menu)
+MacOS Dialogs and Application Lifecycle
+If you show dialogs during application startup or file open events, you should set ApplicationShouldTerminateAfterLastWindowClosed to false to prevent the application from terminating when those dialogs close. Otherwise, the application may quit before your main window appears.
app := application.New(application.Options{
+ Mac: application.MacOptions{
+ ApplicationShouldTerminateAfterLastWindowClosed: false,
+ },
+ // ... rest of options
+})
+Alternatively, you can show startup dialogs after the main window has been displayed:
+var filename string
+app.OnApplicationEvent(events.Common.ApplicationOpenedWithFile, func(event *application.ApplicationEvent) {
+ filename = event.Context().Filename()
+})
+
+window.OnWindowEvent(events.Common.WindowShow, func(event *application.WindowEvent) {
+ application.InfoDialog().
+ SetTitle("File Opened").
+ SetMessage("Application opened with file: " + filename).
+ Show()
+})
+API: ShowAboutDialog()
ShowAboutDialog() shows an "About" dialog box. It can show the application's
+name, description and icon.
API: InfoDialog()
InfoDialog() creates and returns a new instance of MessageDialog with an
+InfoDialogType. This dialog is typically used to display informational
+messages to the user.
API: QuestionDialog()
QuestionDialog() creates and returns a new instance of MessageDialog with a
+QuestionDialogType. This dialog is often used to ask a question to the user
+and expect a response.
API: WarningDialog()
WarningDialog() creates and returns a new instance of MessageDialog with a
+WarningDialogType. As the name suggests, this dialog is primarily used to
+display warning messages to the user.
API: ErrorDialog()
ErrorDialog() creates and returns a new instance of MessageDialog with an
+ErrorDialogType. This dialog is designed to be used when you need to display
+an error message to the user.
API: OpenFileDialog()
OpenFileDialog() creates and returns a new OpenFileDialogStruct. This dialog
+prompts the user to select one or more files from their file system.
API: SaveFileDialog()
SaveFileDialog() creates and returns a new SaveFileDialogStruct. This dialog
+prompts the user to choose a location on their file system where a file should
+be saved.
API: OpenDirectoryDialog()
OpenDirectoryDialog() creates and returns a new instance of MessageDialog
+with an OpenDirectoryDialogType. This dialog enables the user to choose a
+directory from their file system.
API:
+OnEvent(name string, callback func(event *CustomEvent)) func()
OnEvent() registers an event listener for specific application events. The callback
+function provided will be triggered when the corresponding event occurs.
API:
+OffEvent(name string)
OffEvent() removes an event listener for a specific named event specified.
API:
+OnMultipleEvent(name string, callback func(event *CustomEvent), counter int) func()
OnMultipleEvent() registers an event listener for X number of Events. The callback
+function provided will be triggered counter times when the corresponding event occurs.
API:
+ResetEvents()
ResetEvents() removes all event listeners for all application events.
API:
+OnApplicationEvent(eventType events.ApplicationEventType, callback func(event *ApplicationEvent)) func()
OnApplicationEvent() registers an event listener for specific application events.
+The eventType is based on events.ApplicationEventType. See ApplicationEventType
API:
+RegisterApplicationEventHook(eventType events.ApplicationEventType, callback func(event *ApplicationEvent)) func()
RegisterApplicationEventHook() registers a callback to be triggered based on specific application events.
API:
+RegisterHook(eventType events.ApplicationEventType, callback func(event *Event)) func()
RegisterHook() registers a callback to be run as a hook during specific
+events. These hooks are run before listeners attached with On(). The function
+returns a function that can be called to remove the hook.
API: GetPrimaryScreen() (*Screen, error)
GetPrimaryScreen() returns the primary screen of the system.
API: GetScreens() ([]*Screen, error)
GetScreens() returns information about all screens attached to the system.
This is a brief summary of the exported methods in the provided App struct. Do
+note that for more detailed functionality or considerations, refer to the actual
+Go code or further internal documentation.
package application
+
+import (
+ "io/fs"
+ "log/slog"
+ "net/http"
+
+ "github.com/wailsapp/wails/v3/internal/assetserver"
+)
+
+// Service wraps a bound type instance.
+// The zero value of Service is invalid.
+// Valid values may only be obtained by calling [NewService].
+type Service struct {
+ instance any
+ options ServiceOptions
+}
+
+type ServiceOptions struct {
+ // Name can be set to override the name of the service
+ // This is useful for logging and debugging purposes
+ Name string
+ // Route is the path to the assets
+ Route string
+}
+
+var DefaultServiceOptions = ServiceOptions{
+ Route: "",
+}
+
+// NewService returns a Service value wrapping the given pointer.
+// If T is not a named type, the returned value is invalid.
+// The prefix is used if Service implements a http.Handler only one allowed
+func NewService[T any](instance *T, options ...ServiceOptions) Service {
+ if len(options) == 1 {
+ return Service{instance, options[0]}
+ }
+ return Service{instance, DefaultServiceOptions}
+}
+
+func (s Service) Instance() any {
+ return s.instance
+}
+
+// Options contains the options for the application
+type Options struct {
+ // Name is the name of the application (used in the default about box)
+ Name string
+
+ // Description is the description of the application (used in the default about box)
+ Description string
+
+ // Icon is the icon of the application (used in the default about box)
+ Icon []byte
+
+ // Mac is the Mac specific configuration for Mac builds
+ Mac MacOptions
+
+ // Windows is the Windows specific configuration for Windows builds
+ Windows WindowsOptions
+
+ // Linux is the Linux specific configuration for Linux builds
+ Linux LinuxOptions
+
+ // Services allows you to bind Go methods to the frontend.
+ Services []Service
+
+ // BindAliases allows you to specify alias IDs for your bound methods.
+ // Example: `BindAliases: map[uint32]uint32{1: 1411160069}` states that alias ID 1 maps to the Go method with ID 1411160069.
+ BindAliases map[uint32]uint32
+
+ // Logger i a slog.Logger instance used for logging Wails system messages (not application messages).
+ // If not defined, a default logger is used.
+ Logger *slog.Logger
+
+ // LogLevel defines the log level of the Wails system logger.
+ LogLevel slog.Level
+
+ // Assets are the application assets to be used.
+ Assets AssetOptions
+
+ // Flags are key value pairs that are available to the frontend.
+ // This is also used by Wails to provide information to the frontend.
+ Flags map[string]any
+
+ // PanicHandler is called when a panic occurs
+ PanicHandler func(any)
+
+ // DisableDefaultSignalHandler disables the default signal handler
+ DisableDefaultSignalHandler bool
+
+ // KeyBindings is a map of key bindings to functions
+ KeyBindings map[string]func(window *WebviewWindow)
+
+ // OnShutdown is called when the application is about to terminate.
+ // This is useful for cleanup tasks.
+ // The shutdown process blocks until this function returns
+ OnShutdown func()
+
+ // ShouldQuit is a function that is called when the user tries to quit the application.
+ // If the function returns true, the application will quit.
+ // If the function returns false, the application will not quit.
+ ShouldQuit func() bool
+
+ // RawMessageHandler is called when the frontend sends a raw message.
+ // This is useful for implementing custom frontend-to-backend communication.
+ RawMessageHandler func(window Window, message string)
+
+ // WarningHandler is called when a warning occurs
+ WarningHandler func(string)
+
+ // ErrorHandler is called when an error occurs
+ ErrorHandler func(err error)
+
+ // File extensions associated with the application
+ // Example: [".txt", ".md"]
+ // The '.' is required
+ FileAssociations []string
+
+ // This blank field ensures types from other packages
+ // are never convertible to Options.
+ // This property, in turn, improves the accuracy of the binding generator.
+ _ struct{}
+}
+
+// AssetOptions defines the configuration of the AssetServer.
+type AssetOptions struct {
+ // Handler which serves all the content to the WebView.
+ Handler http.Handler
+
+ // Middleware is a HTTP Middleware which allows to hook into the AssetServer request chain. It allows to skip the default
+ // request handler dynamically, e.g. implement specialized Routing etc.
+ // The Middleware is called to build a new `http.Handler` used by the AssetSever and it also receives the default
+ // handler used by the AssetServer as an argument.
+ //
+ // This middleware injects itself before any of Wails internal middlewares.
+ //
+ // If not defined, the default AssetServer request chain is executed.
+ //
+ // Multiple Middlewares can be chained together with:
+ // ChainMiddleware(middleware ...Middleware) Middleware
+ Middleware Middleware
+
+ // DisableLogging disables logging of the AssetServer. By default, the AssetServer logs every request.
+ DisableLogging bool
+}
+
+// Middleware defines HTTP middleware that can be applied to the AssetServer.
+// The handler passed as next is the next handler in the chain. One can decide to call the next handler
+// or implement a specialized handling.
+type Middleware func(next http.Handler) http.Handler
+
+// ChainMiddleware allows chaining multiple middlewares to one middleware.
+func ChainMiddleware(middleware ...Middleware) Middleware {
+ return func(h http.Handler) http.Handler {
+ for i := len(middleware) - 1; i >= 0; i-- {
+ h = middleware[i](h)
+ }
+ return h
+ }
+}
+
+// AssetFileServerFS returns a http handler which serves the assets from the fs.FS.
+// If an external devserver has been provided 'FRONTEND_DEVSERVER_URL' the files are being served
+// from the external server, ignoring the `assets`.
+func AssetFileServerFS(assets fs.FS) http.Handler {
+ return assetserver.NewAssetFileServer(assets)
+}
+
+// BundledAssetFileServer returns a http handler which serves the assets from the fs.FS.
+// If an external devserver has been provided 'FRONTEND_DEVSERVER_URL' the files are being served
+// from the external server, ignoring the `assets`.
+// It also serves the compiled runtime.js file at `/wails/runtime.js`.
+// It will provide the production runtime.js file from the embedded assets if the `production` tag is used.
+func BundledAssetFileServer(assets fs.FS) http.Handler {
+ return assetserver.NewBundledAssetFileServer(assets)
+}
+
+/******** Mac Options ********/
+
+// ActivationPolicy is the activation policy for the application.
+type ActivationPolicy int
+
+const (
+ // ActivationPolicyRegular is used for applications that have a user interface,
+ ActivationPolicyRegular ActivationPolicy = iota
+ // ActivationPolicyAccessory is used for applications that do not have a main window,
+ // such as system tray applications or background applications.
+ ActivationPolicyAccessory
+ ActivationPolicyProhibited
+)
+
+// MacOptions contains options for macOS applications.
+type MacOptions struct {
+ // ActivationPolicy is the activation policy for the application. Defaults to
+ // applicationActivationPolicyRegular.
+ ActivationPolicy ActivationPolicy
+ // If set to true, the application will terminate when the last window is closed.
+ ApplicationShouldTerminateAfterLastWindowClosed bool
+}
+
+/****** Windows Options *******/
+
+// WindowsOptions contains options for Windows applications.
+type WindowsOptions struct {
+
+ // Window class name
+ // Default: WailsWebviewWindow
+ WndClass string
+
+ // WndProcInterceptor is a function that will be called for every message sent in the application.
+ // Use this to hook into the main message loop. This is useful for handling custom window messages.
+ // If `shouldReturn` is `true` then `returnCode` will be returned by the main message loop.
+ // If `shouldReturn` is `false` then returnCode will be ignored and the message will be processed by the main message loop.
+ WndProcInterceptor func(hwnd uintptr, msg uint32, wParam, lParam uintptr) (returnCode uintptr, shouldReturn bool)
+
+ // DisableQuitOnLastWindowClosed disables the auto quit of the application if the last window has been closed.
+ DisableQuitOnLastWindowClosed bool
+
+ // Path where the WebView2 stores the user data. If empty %APPDATA%\[BinaryName.exe] will be used.
+ // If the path is not valid, a messagebox will be displayed with the error and the app will exit with error code.
+ WebviewUserDataPath string
+
+ // Path to the directory with WebView2 executables. If empty WebView2 installed in the system will be used.
+ WebviewBrowserPath string
+}
+
+/********* Linux Options *********/
+
+// LinuxOptions contains options for Linux applications.
+type LinuxOptions struct {
+ // DisableQuitOnLastWindowClosed disables the auto quit of the application if the last window has been closed.
+ DisableQuitOnLastWindowClosed bool
+
+ // ProgramName is used to set the program's name for the window manager via GTK's g_set_prgname().
+ //This name should not be localized. [see the docs]
+ //
+ //When a .desktop file is created this value helps with window grouping and desktop icons when the .desktop file's Name
+ //property differs form the executable's filename.
+ //
+ //[see the docs]: https://docs.gtk.org/glib/func.set_prgname.html
+ ProgramName string
+}
+MacOS Dialogs and Application Lifecycle
+If you show dialogs during application startup or file open events, you should set ApplicationShouldTerminateAfterLastWindowClosed to false to prevent the application from terminating when those dialogs close. Otherwise, the application may quit before your main window appears.
app := application.New(application.Options{
+ Mac: application.MacOptions{
+ ApplicationShouldTerminateAfterLastWindowClosed: false,
+ },
+ // ... rest of options
+})
+Alternatively, you can show startup dialogs after the main window has been displayed:
+var filename string
+app.OnApplicationEvent(events.Common.ApplicationOpenedWithFile, func(event *application.ApplicationEvent) {
+ filename = event.Context().Filename()
+})
+
+window.OnWindowEvent(events.Common.WindowShow, func(event *application.WindowEvent) {
+ application.InfoDialog().
+ SetTitle("File Opened").
+ SetMessage("Application opened with file: " + filename).
+ Show()
+})
+API: ShowAboutDialog()
ShowAboutDialog() shows an "About" dialog box. It can show the application's
+name, description and icon.
API: InfoDialog()
InfoDialog() creates and returns a new instance of MessageDialog with an
+InfoDialogType. This dialog is typically used to display informational
+messages to the user.
API: QuestionDialog()
QuestionDialog() creates and returns a new instance of MessageDialog with a
+QuestionDialogType. This dialog is often used to ask a question to the user
+and expect a response.
API: WarningDialog()
WarningDialog() creates and returns a new instance of MessageDialog with a
+WarningDialogType. As the name suggests, this dialog is primarily used to
+display warning messages to the user.
API: ErrorDialog()
ErrorDialog() creates and returns a new instance of MessageDialog with an
+ErrorDialogType. This dialog is designed to be used when you need to display
+an error message to the user.
API: OpenFileDialog()
OpenFileDialog() creates and returns a new OpenFileDialogStruct. This dialog
+prompts the user to select one or more files from their file system.
API: SaveFileDialog()
SaveFileDialog() creates and returns a new SaveFileDialogStruct. This dialog
+prompts the user to choose a location on their file system where a file should
+be saved.
API: OpenDirectoryDialog()
OpenDirectoryDialog() creates and returns a new instance of MessageDialog
+with an OpenDirectoryDialogType. This dialog enables the user to choose a
+directory from their file system.
API:
+OnEvent(name string, callback func(event *CustomEvent)) func()
OnEvent() registers an event listener for specific application events. The callback
+function provided will be triggered when the corresponding event occurs.
API:
+OffEvent(name string)
OffEvent() removes an event listener for a specific named event specified.
API:
+OnMultipleEvent(name string, callback func(event *CustomEvent), counter int) func()
OnMultipleEvent() registers an event listener for X number of Events. The callback
+function provided will be triggered counter times when the corresponding event occurs.
API:
+ResetEvents()
ResetEvents() removes all event listeners for all application events.
API:
+OnApplicationEvent(eventType events.ApplicationEventType, callback func(event *ApplicationEvent)) func()
OnApplicationEvent() registers an event listener for specific application events.
+The eventType is based on events.ApplicationEventType. See ApplicationEventType
API:
+RegisterApplicationEventHook(eventType events.ApplicationEventType, callback func(event *ApplicationEvent)) func()
RegisterApplicationEventHook() registers a callback to be triggered based on specific application events.
API:
+RegisterHook(eventType events.ApplicationEventType, callback func(event *Event)) func()
RegisterHook() registers a callback to be run as a hook during specific
+events. These hooks are run before listeners attached with On(). The function
+returns a function that can be called to remove the hook.
API: RegisterContextMenu(name string, menu *Menu)
RegisterContextMenu() registers a context menu with a given name. This menu
+can be used later in the application.
// Create a new menu
+ ctxmenu := app.NewMenu()
+
+ // Register the menu as a context menu
+ app.RegisterContextMenu("MyContextMenu", ctxmenu)
+API: SetMenu(menu *Menu)
SetMenu() sets the menu for the application. On Mac, this will be the global
+menu. For Windows and Linux, this will be the default menu for any new window
+created.
API: GetPrimaryScreen() (*Screen, error)
GetPrimaryScreen() returns the primary screen of the system.
API: GetScreens() ([]*Screen, error)
GetScreens() returns information about all screens attached to the system.
This is a brief summary of the exported methods in the provided App struct. Do
+note that for more detailed functionality or considerations, refer to the actual
+Go code or further internal documentation.
API: NewWebviewWindow() *WebviewWindow
NewWebviewWindow() creates a new Webview window with default options, and
+returns it.
API:
+NewWebviewWindowWithOptions(windowOptions WebviewWindowOptions) *WebviewWindow
NewWebviewWindowWithOptions() creates a new webview window with custom
+options. The newly created window is added to a map of windows managed by the
+application.
// Create a new webview window with custom options
+ window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
+ Name: "Main",
+ Title: "My Window",
+ Width: 800,
+ Height: 600,
+ })
+API: OnWindowCreation(callback func(window *WebviewWindow))
OnWindowCreation() registers a callback function to be called when a window is
+created.
// Register a callback to be called when a window is created
+ app.OnWindowCreation(func(window *WebviewWindow) {
+ // Do something
+ })
+API: GetWindowByName(name string) *WebviewWindow
GetWindowByName() fetches and returns a window with a specific name.
API: CurrentWindow() *WebviewWindow
CurrentWindow() fetches and returns a pointer to the currently active window
+in the application. If there is no window, it returns nil.
wails3 provides an event system that allows for hooking into application and window events
+// Notification of application start
+application.RegisterApplicationEventHook(events.Common.ApplicationStarted, func(event *application.ApplicationEvent) {
+ app.Logger.Info("Application started!")
+})
+// Notification of system theme change
+application.OnApplicationEvent(events.Common.ThemeChanged, 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!")
+ }
+})
+// Disable window closing by canceling the event
+window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
+ app.Logger.Info("Window 1 Closing? Nope! Not closing!")
+ e.Cancel()
+})
+// Notification of window focus
+window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
+ app.Logger.Info("[ApplicationEvent] Window focus!")
+})
+Application events are hookable events that can be registered with application.RegisterApplicationEventHook()
+and application.OnApplicationEvent(). These events are based on events.ApplicationEventType.
events.Common.ApplicationStartedevents.Common.ThemeChangedevents.Common.WindowMaximisedevents.Common.WindowUnmaximisedevents.Common.WindowMinimisedevents.Common.WindowUnminimisedevents.Common.WindowFullscreenevents.Common.WindowUnfullscreenevents.Common.WindowRestoredevents.Common.WindowClosingevents.Common.WindowZoomevents.Common.WindowZoomOutevents.Common.WindowZoomInevents.Common.WindowZoomResetevents.Common.WindowFocusevents.Common.WindowLostFocusevents.Common.WindowShowevents.Common.WindowHideevents.Common.WindowDPIChangedevents.Common.WindowFilesDroppedevents.Common.WindowRuntimeReadyevents.Common.WindowDidMoveevents.Common.WindowDidResizeevents.Linux.ApplicationStartupevents.Linux.SystemThemeChangedevents.Linux.WindowLoadChangedevents.Linux.WindowDeleteEventevents.Linux.WindowDidMoveevents.Linux.WindowDidResizeevents.Linux.WindowFocusInevents.Linux.WindowFocusOutevents.Windows.ApplicationStartedevents.Windows.SystemThemeChangedevents.Windows.APMPowerStatusChangeevents.Windows.APMSuspendevents.Windows.APMResumeAutomaticevents.Windows.APMResumeSuspendevents.Windows.WebviewNavigationCompletedevents.Windows.WindowInactiveevents.Windows.WindowActiveevents.Windows.ClickActiveevents.Windows.MaximiseActiveevents.Windows.UnMaximiseevents.Windows.Fullscreenevents.Windows.UnFullscreenevents.Windows.WindowRestoreevents.Windows.WindowMinimiseevents.Windows.WindowUnminimiseevents.Windows.WindowCloseevents.Windows.WindowSetFocusevents.Windows.WindowKillFocusevents.Windows.WindowDragDropevents.Windows.WindowDragEnterevents.Windows.WindowDragLeaveevents.Windows.WindowDragOverevents.Windows.WindowDidMoveevents.Mac.ApplicationDidBecomeActiveevents.Mac.ApplicationDidChangeBackingPropertiesevents.Mac.ApplicationDidChangeEffectiveAppearanceevents.Mac.ApplicationDidChangeIconevents.Mac.ApplicationDidChangeOcclusionStateevents.Mac.ApplicationDidChangeScreenParametersevents.Mac.ApplicationDidChangeStatusBarFrameevents.Mac.ApplicationDidChangeStatusBarOrientationevents.Mac.ApplicationDidFinishLaunchingevents.Mac.ApplicationDidResignActiveNotificationevents.Mac.ApplicationDidHideevents.Mac.ApplicationDidUpdateevents.Mac.ApplicationWillBecomeActiveevents.Mac.ApplicationWillFinishLaunchingevents.Mac.ApplicationWillHideevents.Mac.ApplicationWillResignActiveevents.Mac.ApplicationWillTerminateevents.Mac.ApplicationWillUnhideevents.Mac.ApplicationWillUpdateevents.Mac.ApplicationDidChangeThemeevents.Mac.MenuWillOpenevents.Mac.MenuDidOpenevents.Mac.MenuDidCloseevents.Mac.MenuWillSendActionevents.Mac.MenuDidSendActionevents.Mac.MenuWillHighlightItemevents.Mac.MenuDidHighlightItemevents.Mac.MenuWillDisplayItemevents.Mac.MenuDidDisplayItemevents.Mac.MenuWillAddItemevents.Mac.MenuDidAddItemevents.Mac.MenuWillRemoveItemevents.Mac.MenuDidRemoveItemevents.Mac.MenuWillBeginTrackingevents.Mac.MenuDidBeginTrackingevents.Mac.MenuWillEndTrackingevents.Mac.MenuDidEndTrackingevents.Mac.MenuWillUpdateevents.Mac.MenuDidUpdateevents.Mac.MenuWillPopUpevents.Mac.MenuDidPopUpevents.Mac.MenuWillSendActionToItemevents.Mac.MenuDidSendActionToItemevents.Mac.WindowDidBecomeKeyevents.Mac.WindowDidBecomeMainevents.Mac.WindowDidBeginSheetevents.Mac.WindowDidChangeAlphaevents.Mac.WindowDidChangeBackingLocationevents.Mac.WindowDidChangeBackingPropertiesevents.Mac.WindowDidChangeCollectionBehaviorevents.Mac.WindowDidChangeEffectiveAppearanceevents.Mac.WindowDidChangeOcclusionStateevents.Mac.WindowDidChangeOrderingModeevents.Mac.WindowDidChangeScreenevents.Mac.WindowDidChangeScreenParametersevents.Mac.WindowDidChangeScreenProfileevents.Mac.WindowDidChangeScreenSpaceevents.Mac.WindowDidChangeScreenSpacePropertiesevents.Mac.WindowDidChangeSharingTypeevents.Mac.WindowDidChangeSpaceevents.Mac.WindowDidChangeSpaceOrderingModeevents.Mac.WindowDidChangeTitleevents.Mac.WindowDidChangeToolbarevents.Mac.WindowDidChangeVisibilityevents.Mac.WindowDidDeminiaturizeevents.Mac.WindowDidEndSheetevents.Mac.WindowDidEnterFullScreenevents.Mac.WindowDidEnterVersionBrowserevents.Mac.WindowDidExitFullScreenevents.Mac.WindowDidExitVersionBrowserevents.Mac.WindowDidExposeevents.Mac.WindowDidFocusevents.Mac.WindowDidMiniaturizeevents.Mac.WindowDidMoveevents.Mac.WindowDidOrderOffScreenevents.Mac.WindowDidOrderOnScreenevents.Mac.WindowDidResignKeyevents.Mac.WindowDidResignMainevents.Mac.WindowDidResizeevents.Mac.WindowDidUpdateevents.Mac.WindowDidUpdateAlphaevents.Mac.WindowDidUpdateCollectionBehaviorevents.Mac.WindowDidUpdateCollectionPropertiesevents.Mac.WindowDidUpdateShadowevents.Mac.WindowDidUpdateTitleevents.Mac.WindowDidUpdateToolbarevents.Mac.WindowDidUpdateVisibilityevents.Mac.WindowShouldCloseevents.Mac.WindowWillBecomeKeyevents.Mac.WindowWillBecomeMainevents.Mac.WindowWillBeginSheetevents.Mac.WindowWillChangeOrderingModeevents.Mac.WindowWillCloseevents.Mac.WindowWillDeminiaturizeevents.Mac.WindowWillEnterFullScreenevents.Mac.WindowWillEnterVersionBrowserevents.Mac.WindowWillExitFullScreenevents.Mac.WindowWillExitVersionBrowserevents.Mac.WindowWillFocusevents.Mac.WindowWillMiniaturizeevents.Mac.WindowWillMoveevents.Mac.WindowWillOrderOffScreenevents.Mac.WindowWillOrderOnScreenevents.Mac.WindowWillResignMainevents.Mac.WindowWillResizeevents.Mac.WindowWillUnfocusevents.Mac.WindowWillUpdateevents.Mac.WindowWillUpdateAlphaevents.Mac.WindowWillUpdateCollectionBehaviorevents.Mac.WindowWillUpdateCollectionPropertiesevents.Mac.WindowWillUpdateShadowevents.Mac.WindowWillUpdateTitleevents.Mac.WindowWillUpdateToolbarevents.Mac.WindowWillUpdateVisibilityevents.Mac.WindowWillUseStandardFrameevents.Mac.WebviewDidStartProvisionalNavigationevents.Mac.WebviewDidReceiveServerRedirectForProvisionalNavigationevents.Mac.WebviewDidFinishNavigationevents.Mac.WebviewDidCommitNavigationevents.Mac.WindowFileDraggingEnteredevents.Mac.WindowFileDraggingPerformedevents.Mac.WindowFileDraggingExitedwails3 provides an event system that allows for hooking into application and window events
+// Notification of application start
+application.RegisterApplicationEventHook(events.Common.ApplicationStarted, func(event *application.ApplicationEvent) {
+ app.Logger.Info("Application started!")
+})
+// Notification of system theme change
+application.OnApplicationEvent(events.Common.ThemeChanged, 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!")
+ }
+})
+// Disable window closing by canceling the event
+window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
+ app.Logger.Info("Window 1 Closing? Nope! Not closing!")
+ e.Cancel()
+})
+// Notification of window focus
+window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
+ app.Logger.Info("[ApplicationEvent] Window focus!")
+})
+Application events are hookable events that can be registered with application.RegisterApplicationEventHook()
+and application.OnApplicationEvent(). These events are based on events.ApplicationEventType.
events.Common.ApplicationStartedevents.Common.ThemeChangedevents.Common.WindowMaximisedevents.Common.WindowUnmaximisedevents.Common.WindowMinimisedevents.Common.WindowUnminimisedevents.Common.WindowFullscreenevents.Common.WindowUnfullscreenevents.Common.WindowRestoredevents.Common.WindowClosingevents.Common.WindowZoomevents.Common.WindowZoomOutevents.Common.WindowZoomInevents.Common.WindowZoomResetevents.Common.WindowFocusevents.Common.WindowLostFocusevents.Common.WindowShowevents.Common.WindowHideevents.Common.WindowDPIChangedevents.Common.WindowFilesDroppedevents.Common.WindowRuntimeReadyevents.Common.WindowDidMoveevents.Common.WindowDidResizeevents.Linux.ApplicationStartupevents.Linux.SystemThemeChangedevents.Linux.WindowLoadChangedevents.Linux.WindowDeleteEventevents.Linux.WindowDidMoveevents.Linux.WindowDidResizeevents.Linux.WindowFocusInevents.Linux.WindowFocusOutevents.Windows.ApplicationStartedevents.Windows.SystemThemeChangedevents.Windows.APMPowerStatusChangeevents.Windows.APMSuspendevents.Windows.APMResumeAutomaticevents.Windows.APMResumeSuspendevents.Windows.WebviewNavigationCompletedevents.Windows.WindowInactiveevents.Windows.WindowActiveevents.Windows.ClickActiveevents.Windows.MaximiseActiveevents.Windows.UnMaximiseevents.Windows.Fullscreenevents.Windows.UnFullscreenevents.Windows.WindowRestoreevents.Windows.WindowMinimiseevents.Windows.WindowUnminimiseevents.Windows.WindowCloseevents.Windows.WindowSetFocusevents.Windows.WindowKillFocusevents.Windows.WindowDragDropevents.Windows.WindowDragEnterevents.Windows.WindowDragLeaveevents.Windows.WindowDragOverevents.Windows.WindowDidMoveevents.Mac.ApplicationDidBecomeActiveevents.Mac.ApplicationDidChangeBackingPropertiesevents.Mac.ApplicationDidChangeEffectiveAppearanceevents.Mac.ApplicationDidChangeIconevents.Mac.ApplicationDidChangeOcclusionStateevents.Mac.ApplicationDidChangeScreenParametersevents.Mac.ApplicationDidChangeStatusBarFrameevents.Mac.ApplicationDidChangeStatusBarOrientationevents.Mac.ApplicationDidFinishLaunchingevents.Mac.ApplicationDidResignActiveNotificationevents.Mac.ApplicationDidHideevents.Mac.ApplicationDidUpdateevents.Mac.ApplicationWillBecomeActiveevents.Mac.ApplicationWillFinishLaunchingevents.Mac.ApplicationWillHideevents.Mac.ApplicationWillResignActiveevents.Mac.ApplicationWillTerminateevents.Mac.ApplicationWillUnhideevents.Mac.ApplicationWillUpdateevents.Mac.ApplicationDidChangeThemeevents.Mac.MenuWillOpenevents.Mac.MenuDidOpenevents.Mac.MenuDidCloseevents.Mac.MenuWillSendActionevents.Mac.MenuDidSendActionevents.Mac.MenuWillHighlightItemevents.Mac.MenuDidHighlightItemevents.Mac.MenuWillDisplayItemevents.Mac.MenuDidDisplayItemevents.Mac.MenuWillAddItemevents.Mac.MenuDidAddItemevents.Mac.MenuWillRemoveItemevents.Mac.MenuDidRemoveItemevents.Mac.MenuWillBeginTrackingevents.Mac.MenuDidBeginTrackingevents.Mac.MenuWillEndTrackingevents.Mac.MenuDidEndTrackingevents.Mac.MenuWillUpdateevents.Mac.MenuDidUpdateevents.Mac.MenuWillPopUpevents.Mac.MenuDidPopUpevents.Mac.MenuWillSendActionToItemevents.Mac.MenuDidSendActionToItemevents.Mac.WindowDidBecomeKeyevents.Mac.WindowDidBecomeMainevents.Mac.WindowDidBeginSheetevents.Mac.WindowDidChangeAlphaevents.Mac.WindowDidChangeBackingLocationevents.Mac.WindowDidChangeBackingPropertiesevents.Mac.WindowDidChangeCollectionBehaviorevents.Mac.WindowDidChangeEffectiveAppearanceevents.Mac.WindowDidChangeOcclusionStateevents.Mac.WindowDidChangeOrderingModeevents.Mac.WindowDidChangeScreenevents.Mac.WindowDidChangeScreenParametersevents.Mac.WindowDidChangeScreenProfileevents.Mac.WindowDidChangeScreenSpaceevents.Mac.WindowDidChangeScreenSpacePropertiesevents.Mac.WindowDidChangeSharingTypeevents.Mac.WindowDidChangeSpaceevents.Mac.WindowDidChangeSpaceOrderingModeevents.Mac.WindowDidChangeTitleevents.Mac.WindowDidChangeToolbarevents.Mac.WindowDidChangeVisibilityevents.Mac.WindowDidDeminiaturizeevents.Mac.WindowDidEndSheetevents.Mac.WindowDidEnterFullScreenevents.Mac.WindowDidEnterVersionBrowserevents.Mac.WindowDidExitFullScreenevents.Mac.WindowDidExitVersionBrowserevents.Mac.WindowDidExposeevents.Mac.WindowDidFocusevents.Mac.WindowDidMiniaturizeevents.Mac.WindowDidMoveevents.Mac.WindowDidOrderOffScreenevents.Mac.WindowDidOrderOnScreenevents.Mac.WindowDidResignKeyevents.Mac.WindowDidResignMainevents.Mac.WindowDidResizeevents.Mac.WindowDidUpdateevents.Mac.WindowDidUpdateAlphaevents.Mac.WindowDidUpdateCollectionBehaviorevents.Mac.WindowDidUpdateCollectionPropertiesevents.Mac.WindowDidUpdateShadowevents.Mac.WindowDidUpdateTitleevents.Mac.WindowDidUpdateToolbarevents.Mac.WindowDidUpdateVisibilityevents.Mac.WindowShouldCloseevents.Mac.WindowWillBecomeKeyevents.Mac.WindowWillBecomeMainevents.Mac.WindowWillBeginSheetevents.Mac.WindowWillChangeOrderingModeevents.Mac.WindowWillCloseevents.Mac.WindowWillDeminiaturizeevents.Mac.WindowWillEnterFullScreenevents.Mac.WindowWillEnterVersionBrowserevents.Mac.WindowWillExitFullScreenevents.Mac.WindowWillExitVersionBrowserevents.Mac.WindowWillFocusevents.Mac.WindowWillMiniaturizeevents.Mac.WindowWillMoveevents.Mac.WindowWillOrderOffScreenevents.Mac.WindowWillOrderOnScreenevents.Mac.WindowWillResignMainevents.Mac.WindowWillResizeevents.Mac.WindowWillUnfocusevents.Mac.WindowWillUpdateevents.Mac.WindowWillUpdateAlphaevents.Mac.WindowWillUpdateCollectionBehaviorevents.Mac.WindowWillUpdateCollectionPropertiesevents.Mac.WindowWillUpdateShadowevents.Mac.WindowWillUpdateTitleevents.Mac.WindowWillUpdateToolbarevents.Mac.WindowWillUpdateVisibilityevents.Mac.WindowWillUseStandardFrameevents.Mac.WebviewDidStartProvisionalNavigationevents.Mac.WebviewDidReceiveServerRedirectForProvisionalNavigationevents.Mac.WebviewDidFinishNavigationevents.Mac.WebviewDidCommitNavigationevents.Mac.WindowFileDraggingEnteredevents.Mac.WindowFileDraggingPerformedevents.Mac.WindowFileDraggingExitedYou can create your own custom events that can be emitted and received on both the frontend and backend. +Events are able to emitted at both the application and the window level. The receiver of the event gets data of where the +event was emitted from along with the data that was sent with the event. Events can be cancelled by the receiver.
+app.OnEvent("event1", func(e *application.CustomEvent) {
+ app.Logger.Info("[Go] CustomEvent received", "name", e.Name, "data", e.Data, "sender", e.Sender, "cancelled", e.Cancelled)
+ app.Logger.Info("[Go]", e.Data[0].(string)) // Logs "Hello from JS" to the terminal
+})
+
+window.EmitEvent("event2", "Hello from Go")
+application.EmitEvent(name string, data ...any)window.EmitEvent(name string, data ...any)wails.Events.Emit(event:wails.Events.EventData)name and data properties or the typescript type WailsEvent Events can be received on the application instance and the frontend with a couple options of how +you chose to receive them. You can register a single event listener that will trigger every time the event is emitted +or you can register an event listener that will only trigger a specific number of times.
+Golang
+application.OnEvent(name string, handler func(data ...any))application.OnMultipleEvent(name string, handler func(data ...any), count int)Frontend
+wails.Events.On(name: string, callback: ()=>void),wails.Events.Once(name: string, callback: ()=>void),wails.Events.OnMultiple(name: string, callback: ()=>void, count: number),count times, this function returns a function that can be called to remove the event listenerThere are a few ways to remove events that are registered. All of the registration functions return a function that can be called to remove the event listeneer +in the frontend. There are additional functions provided to help remove events as well.
+Golang
+application.OffEvent(name string, ...additionalNames string)application.ResetEvents()Frontend
+wails.Events.OffAll()wails.Events.Off(name: string)Returned when an application hook event is triggered. The event can be cancelled by calling the Cancel() method on the event.
+
type ApplicationEvent struct {
+ Id uint
+ ctx *ApplicationEventContext
+ Cancelled bool
+}
+
+// Cancel the event
+func (a *ApplicationEvent) Cancel() {}
+Returned when a window hook event is triggered. The event can be cancelled by calling the Cancel() method on the event.
+
type WindowEvent struct {
+ ctx *WindowEventContext
+ Cancelled bool
+}
+
+// Cancel the event
+func (w *WindowEvent) Cancel() {}
+CustomEvent is returned when an event is being recieved it includes the name of the event, the data that was sent with the event,
+the sender of the event, application or a specific window. The event can be cancelled by calling the Cancel() method on the event.
+
events.Linux.ApplicationStartupevents.Linux.SystemThemeChangedevents.Linux.WindowLoadChangedevents.Linux.WindowDeleteEventevents.Linux.WindowDidMoveevents.Linux.WindowDidResizeevents.Linux.WindowFocusInevents.Linux.WindowFocusOutevents.Mac.ApplicationDidBecomeActiveevents.Mac.ApplicationDidChangeBackingPropertiesevents.Mac.ApplicationDidChangeEffectiveAppearanceevents.Mac.ApplicationDidChangeIconevents.Mac.ApplicationDidChangeOcclusionStateevents.Mac.ApplicationDidChangeScreenParametersevents.Mac.ApplicationDidChangeStatusBarFrameevents.Mac.ApplicationDidChangeStatusBarOrientationevents.Mac.ApplicationDidFinishLaunchingevents.Mac.ApplicationDidResignActiveNotificationevents.Mac.ApplicationDidHideevents.Mac.ApplicationDidUpdateevents.Mac.ApplicationWillBecomeActiveevents.Mac.ApplicationWillFinishLaunchingevents.Mac.ApplicationWillHideevents.Mac.ApplicationWillResignActiveevents.Mac.ApplicationWillTerminateevents.Mac.ApplicationWillUnhideevents.Mac.ApplicationWillUpdateevents.Mac.ApplicationDidChangeThemeevents.Mac.MenuWillOpenevents.Mac.MenuDidOpenevents.Mac.MenuDidCloseevents.Mac.MenuWillSendActionevents.Mac.MenuDidSendActionevents.Mac.MenuWillHighlightItemevents.Mac.MenuDidHighlightItemevents.Mac.MenuWillDisplayItemevents.Mac.MenuDidDisplayItemevents.Mac.MenuWillAddItemevents.Mac.MenuDidAddItemevents.Mac.MenuWillRemoveItemevents.Mac.MenuDidRemoveItemevents.Mac.MenuWillBeginTrackingevents.Mac.MenuDidBeginTrackingevents.Mac.MenuWillEndTrackingevents.Mac.MenuDidEndTrackingevents.Mac.MenuWillUpdateevents.Mac.MenuDidUpdateevents.Mac.MenuWillPopUpevents.Mac.MenuDidPopUpevents.Mac.MenuWillSendActionToItemevents.Mac.MenuDidSendActionToItemevents.Mac.WindowDidBecomeKeyevents.Mac.WindowDidBecomeMainevents.Mac.WindowDidBeginSheetevents.Mac.WindowDidChangeAlphaevents.Mac.WindowDidChangeBackingLocationevents.Mac.WindowDidChangeBackingPropertiesevents.Mac.WindowDidChangeCollectionBehaviorevents.Mac.WindowDidChangeEffectiveAppearanceevents.Mac.WindowDidChangeOcclusionStateevents.Mac.WindowDidChangeOrderingModeevents.Mac.WindowDidChangeScreenevents.Mac.WindowDidChangeScreenParametersevents.Mac.WindowDidChangeScreenProfileevents.Mac.WindowDidChangeScreenSpaceevents.Mac.WindowDidChangeScreenSpacePropertiesevents.Mac.WindowDidChangeSharingTypeevents.Mac.WindowDidChangeSpaceevents.Mac.WindowDidChangeSpaceOrderingModeevents.Mac.WindowDidChangeTitleevents.Mac.WindowDidChangeToolbarevents.Mac.WindowDidChangeVisibilityevents.Mac.WindowDidDeminiaturizeevents.Mac.WindowDidEndSheetevents.Mac.WindowDidEnterFullScreenevents.Mac.WindowDidEnterVersionBrowserevents.Mac.WindowDidExitFullScreenevents.Mac.WindowDidExitVersionBrowserevents.Mac.WindowDidExposeevents.Mac.WindowDidFocusevents.Mac.WindowDidMiniaturizeevents.Mac.WindowDidMoveevents.Mac.WindowDidOrderOffScreenevents.Mac.WindowDidOrderOnScreenevents.Mac.WindowDidResignKeyevents.Mac.WindowDidResignMainevents.Mac.WindowDidResizeevents.Mac.WindowDidUpdateevents.Mac.WindowDidUpdateAlphaevents.Mac.WindowDidUpdateCollectionBehaviorevents.Mac.WindowDidUpdateCollectionPropertiesevents.Mac.WindowDidUpdateShadowevents.Mac.WindowDidUpdateTitleevents.Mac.WindowDidUpdateToolbarevents.Mac.WindowDidUpdateVisibilityevents.Mac.WindowShouldCloseevents.Mac.WindowWillBecomeKeyevents.Mac.WindowWillBecomeMainevents.Mac.WindowWillBeginSheetevents.Mac.WindowWillChangeOrderingModeevents.Mac.WindowWillCloseevents.Mac.WindowWillDeminiaturizeevents.Mac.WindowWillEnterFullScreenevents.Mac.WindowWillEnterVersionBrowserevents.Mac.WindowWillExitFullScreenevents.Mac.WindowWillExitVersionBrowserevents.Mac.WindowWillFocusevents.Mac.WindowWillMiniaturizeevents.Mac.WindowWillMoveevents.Mac.WindowWillOrderOffScreenevents.Mac.WindowWillOrderOnScreenevents.Mac.WindowWillResignMainevents.Mac.WindowWillResizeevents.Mac.WindowWillUnfocusevents.Mac.WindowWillUpdateevents.Mac.WindowWillUpdateAlphaevents.Mac.WindowWillUpdateCollectionBehaviorevents.Mac.WindowWillUpdateCollectionPropertiesevents.Mac.WindowWillUpdateShadowevents.Mac.WindowWillUpdateTitleevents.Mac.WindowWillUpdateToolbarevents.Mac.WindowWillUpdateVisibilityevents.Mac.WindowWillUseStandardFrameevents.Mac.WebviewDidStartProvisionalNavigationevents.Mac.WebviewDidReceiveServerRedirectForProvisionalNavigationevents.Mac.WebviewDidFinishNavigationevents.Mac.WebviewDidCommitNavigationevents.Mac.WindowFileDraggingEnteredevents.Mac.WindowFileDraggingPerformedevents.Mac.WindowFileDraggingExitedevents.Windows.ApplicationStartedevents.Windows.SystemThemeChangedevents.Windows.APMPowerStatusChangeevents.Windows.APMSuspendevents.Windows.APMResumeAutomaticevents.Windows.APMResumeSuspendevents.Windows.WebviewNavigationCompletedevents.Windows.WindowInactiveevents.Windows.WindowActiveevents.Windows.ClickActiveevents.Windows.MaximiseActiveevents.Windows.UnMaximiseevents.Windows.Fullscreenevents.Windows.UnFullscreenevents.Windows.WindowRestoreevents.Windows.WindowMinimiseevents.Windows.WindowUnminimiseevents.Windows.WindowCloseevents.Windows.WindowSetFocusevents.Windows.WindowKillFocusevents.Windows.WindowDragDropevents.Windows.WindowDragEnterevents.Windows.WindowDragLeaveevents.Windows.WindowDragOverevents.Windows.WindowDidMoveThese methods are utility functions to run code on the main thread. This is +required when you want to run custom code on the UI thread.
+API: InvokeSync(fn func())
This function runs the passed function (fn) synchronously. It uses a WaitGroup
+(wg) to ensure that the main thread waits for the fn function to finish
+before it continues. If a panic occurs inside fn, it will be passed to the
+handler function PanicHandler, defined in the application options.
API: InvokeSyncWithResult[T any](fn func() T) (res T)
This function works similarly to InvokeSync(fn func()), however, it yields a
+result. Use this for calling any function with a single return.
API: InvokeSyncWithError(fn func() error) (err error)
This function runs fn synchronously and returns any error that fn produces.
+Note that this function will recover from a panic if one occurs during fn's
+execution.
API:
+InvokeSyncWithResultAndError[T any](fn func() (T, error)) (res T, err error)
This function runs fn synchronously and returns both a result of type T and
+an error.
API: InvokeAsync(fn func())
This function runs fn asynchronously. It runs the given function on the main
+thread. If a panic occurs inside fn, it will be passed to the handler function
+PanicHandler, defined in the application options.
Note: These functions will block execution until fn has finished. It's
+critical to ensure that fn doesn't block. If you need to run a function that
+blocks, use InvokeAsync instead.
Menus can be created and added to the application. They can be used to create +context menus, system tray menus and application menus.
+To create a new menu, call:
+ +The following operations are then available on the Menu type:
API: Add(label string) *MenuItem
This method takes a label of type string as an input and adds a new
+MenuItem with the given label to the menu. It returns the MenuItem added.
API: AddSeparator()
This method adds a new separator MenuItem to the menu.
API: AddCheckbox(label string, enabled bool) *MenuItem
This method takes a label of type string and enabled of type bool as
+inputs and adds a new checkbox MenuItem with the given label and enabled state
+to the menu. It returns the MenuItem added.
API: AddRadio(label string, enabled bool) *MenuItem
This method takes a label of type string and enabled of type bool as
+inputs and adds a new radio MenuItem with the given label and enabled state to
+the menu. It returns the MenuItem added.
API: Update()
This method processes any radio groups and updates the menu if a menu +implementation is not initialized.
+API: AddSubmenu(s string) *Menu
This method takes a s of type string as input and adds a new submenu
+MenuItem with the given label to the menu. It returns the submenu added.
API: AddRole(role Role) *Menu
This method takes role of type Role as input, adds it to the menu if it is
+not nil and returns the Menu.
API: SetLabel(label string)
This method sets the label of the Menu.
The system tray houses notification area on a desktop environment, which can +contain both icons of currently-running applications and specific system +notifications.
+You create a system tray by calling app.NewSystemTray():
The following methods are available on the SystemTray type:
API: SetLabel(label string)
The SetLabel method sets the tray's label.
API: Label() string
The Label method retrieves the tray's label.
API: PositionWindow(*WebviewWindow, offset int) error
The PositionWindow method calls both AttachWindow and WindowOffset
+methods.
API: SetIcon(icon []byte) *SystemTray
The SetIcon method sets the system tray's icon.
API: SetDarkModeIcon(icon []byte) *SystemTray
The SetDarkModeIcon method sets the system tray's icon when in dark mode.
API: SetMenu(menu *Menu) *SystemTray
The SetMenu method sets the system tray's menu.
API: Destroy()
The Destroy method destroys the system tray instance.
API: OnClick(handler func()) *SystemTray
The OnClick method sets the function to execute when the tray icon is clicked.
API: OnRightClick(handler func()) *SystemTray
The OnRightClick method sets the function to execute when right-clicking the
+tray icon.
API: OnDoubleClick(handler func()) *SystemTray
The OnDoubleClick method sets the function to execute when double-clicking the
+tray icon.
API: OnRightDoubleClick(handler func()) *SystemTray
The OnRightDoubleClick method sets the function to execute when right
+double-clicking the tray icon.
API: AttachWindow(window *WebviewWindow) *SystemTray
The AttachWindow method attaches a window to the system tray. The window will
+be shown when the system tray icon is clicked.
API: WindowOffset(offset int) *SystemTray
The WindowOffset method sets the gap in pixels between the system tray and the
+window.
API: WindowDebounce(debounce time.Duration) *SystemTray
The WindowDebounce method sets a debounce time. In the context of Windows,
+this is used to specify how long to wait before responding to a mouse up event
+on the notification icon.
API: OpenMenu()
The OpenMenu method opens the menu associated with the system tray.
To create a window, use +Application.NewWebviewWindow or +Application.NewWebviewWindowWithOptions. +The former creates a window with default options, while the latter allows you to +specify custom options.
+These methods are callable on the returned WebviewWindow object:
+API: SetTitle(title string) *WebviewWindow
This method updates the window title to the provided string. It returns the +WebviewWindow object, allowing for method chaining.
+API: Name() string
This function returns the name of the WebviewWindow.
+API: SetSize(width, height int) *WebviewWindow
This method sets the size of the WebviewWindow to the provided width and height +parameters. If the dimensions provided exceed the constraints, they are adjusted +appropriately.
+API: SetAlwaysOnTop(b bool) *WebviewWindow
This function sets the window to stay on top based on the boolean flag provided.
+API: Show() *WebviewWindow
Show method is used to make the window visible. If the window is not running,
+it first invokes the run method to start the window and then makes it visible.
API: Hide() *WebviewWindow
Hide method is used to hide the window. It sets the hidden status of the
+window to true and emits the window hide event.
API: SetURL(s string) *WebviewWindow
SetURL method is used to set the URL of the window to the given URL string.
API: SetZoom(magnification float64) *WebviewWindow
SetZoom method sets the zoom level of the window content to the provided
+magnification level.
API: GetZoom() float64
GetZoom function returns the current zoom level of the window content.
API: GetScreen() (*Screen, error)
GetScreen method returns the screen on which the window is displayed.
API: SetFrameless(frameless bool) *WebviewWindow
This function is used to remove the window frame and title bar. It toggles the +framelessness of the window according to the boolean value provided (true for +frameless, false for framed).
+API: RegisterContextMenu(name string, menu *Menu)
This function is used to register a context menu and assigns it the given name.
+API: NativeWindowHandle() (uintptr, error)
This function is used to fetch the platform native window handle for the window.
+API: Focus()
This function is used to focus the window.
+API: SetEnabled(enabled bool)
This function is used to enable/disable the window based on the provided boolean +value.
+API: SetPosition(x int, y int)
This function sets the absolute position of the window in the screen.
+ + + + + + + + + + + + + +windowDidBecomeKey callback is running on main thread by @leaanthonygo install by @leaanthonygo install by @leaanthonywails3 update build-assets command by leaanthonywails3 generate runtime command by leaanthonyInitialPosition option to specify if the window should be centered or positioned at the given X/Y location by leaanthony in #3885Path & Paths methods to application package by ansxuman and leaanthony in #3823GeneralAutofillEnabled and PasswordAutosaveEnabled Windows options by leaanthony in #3766EnabledFeatures and DisabledFeatures options for Webview2 by leaanthony.service.OnStartup now shutdowns the application on error and runs service.OnShutdownfor any prior services that started by @atterpac in #3920all:frontend/dist to support frameworks that generate subfolders by @atterpac in #3887go-webview2 v1.0.16 by leaanthonyScreen type to include ID not Id by etesam913 in #3778go.mod.tmpl wails version to support application.ServiceOptions by northes in #3836config.yml by leaanthonyWebviewGpuIsDisabled and EnableFraudulentWebsiteWarnings (superseded by EnabledFeatures and DisabledFeatures options) by leaanthonyOnClick and OnRightClick implementation by @atterpac in #3886AlwaysOnTop not working on Mac by leaanthony in #3841application.NewEditMenu including a duplicate PasteAndMatchStyle role in the edit menu on Darwin by johnmccabe in #3839On/Emit -> user events, OnApplicationEvent -> Application Events OnWindowEvent -> Window Events, by leaanthonyv3/ or v3- by stendler in #3747Failed to unregister class Chrome_WidgetWin_0 warning. By leaanthonyrun:linux by @marcus-crane in #3146SetIcon method by @almas1992 in PROnShutdown by @almas1992 in PRToggleMaximise method in Window interface by @fbbdev in #3281Environment(). By @leaanthony in aba82cc based on PR by @Mai-LapystWebviewWindow.IsFocused method on the Window interface by @fbbdev in #3295setIcon on linux by @abichinger in #3354-port to dev command and support environment variable WAILS_VITE_PORT by @abichinger in #3429SetIgnoreMouseEvents for already created window by @bruxaodev in #3667go.mod to use relative paths. Fixes Windows paths with spaces - @leaanthony.WebviewWindow.Restore method by @fbbdev in #3279startURL across multiple GetStartURL invocations when FRONTEND_DEVSERVER_URL is present. #3299Screen struct to match its Go counterpart by @fbbdev in #3295WML.Reload method to ensure proper cleanup of registered event listeners by @fbbdev in #3295wails3 task dev by @hfoxy in #3417setFrameless Function on Windows by @bruxaodev in #3691.AbsolutePosition() to Position() by mmghv in #3611type="module" attribute. By @fbbdev in #3295@wailsio/runtime package does not publish its API on the window.wails object, and does not start the WML system. This has been done to improve encapsulation. The WML system can be started manually if desired by calling the new WML.Enable method. The bundled JS runtime script still performs both operations automatically. By @fbbdev in #3295@wailsio/runtime/src/window now exposes the containing window object as a default export. It is not possible anymore to import individual methods through ESM named or namespace import syntax.WebviewWindow API. Some methods have changed name or prototype, specifically: Screen becomes GetScreen; GetZoomLevel/SetZoomLevel become GetZoom/SetZoom; GetZoom, Width and Height now return values directly instead of wrapping them within objects. By @fbbdev in #3295-id CLI option has been removed. Use the -names CLI option to switch back to calls by name. By @fbbdev in #3468application.Options.Bind has been renamed to application.Options.Services. By @fbbdev in #3468application.NewService. By @fbbdev in #3468Note
+This is currently an unsorted brain dump of changes. It will be organised into a more readable format soon.
+In v3, there are 3 types of events:
+Application events are events that are emitted by the application. These events
+include native events such as ApplicationDidFinishLaunching on macOS.
Window events are events that are emitted by a window. These events include
+native events such as WindowDidBecomeMain on macOS. Common events are also
+defined, so they work cross-platform, e.g. WindowClosing.
Events that the user defines are called WailsEvents. This is to differentiate
+them from the Event object that is used to communicate with the browser.
+WailsEvents are now objects that encapsulate all the details of an event. This
+includes the event name, the data, and the source of the event.
The data associated with a WailsEvent is now a single value. If multiple values +are required, then a struct can be used.
+Emit function signature#The signatures events callbacks (as used by On, Once & OnMultiple) have
+changed. In v2, the callback function received optional data. In v3, the
+callback function receives a WailsEvent object that contains all data related
+to the event.
Similarly, the Emit function has changed. Instead of taking a name and
+optional data, it now takes a single WailsEvent object that it will emit.
Off and OffAll#In v2, Off and OffAll calls would remove events in both JS and Go. Due to
+the multi-window nature of v3, this has been changed so that these methods only
+apply to the context they are called in. For example, if you call Off in a
+window, it will only remove events for that window. If you use Off in Go, it
+will only remove events for Go.
Event Hooks are a new feature in v3. They allow you to hook into the event
+system and perform actions when certain events are emitted. For example, you can
+hook into the WindowClosing event and perform some cleanup before the window
+closes. Hooks can be registered at the application level or at the window level
+using RegisterHook. Application level are for application events. Window level
+hooks will only be called for the window they are registered with.
When emitting an event in Go, it will dispatch the event to local Go listeners +and also each window in the application. When emitting an event in JS, it now +sends the event to the application. This will be processed as if it was emitted +in Go, however the sender ID will be that of the window.
+The Window API has largely remained the same, however the methods are now on an +instance of a window rather than the runtime. Some notable differences are:
+SetFrameless and ToggleDevTools.In v2, this was a pointer to an RGBA struct. In v3, this is an RGBA struct
+value.
This flag has been removed. Now there is a BackgroundType flag that can be
+used to set the type of background the window should have. This flag can be set
+to any of the following values:
BackgroundTypeSolid - The window will have a solid backgroundBackgroundTypeTransparent - The window will have a transparent backgroundBackgroundTypeTranslucent - The window will have a translucent backgroundOn Windows, if the BackgroundType is set to BackgroundTypeTranslucent, the
+type of translucency can be set using the BackdropType flag in the
+WindowsWindow options. This can be set to any of the following values:
Auto - The window will use an effect determined by the systemNone - The window will have no backgroundMica - The window will use the Mica effectAcrylic - The window will use the acrylic effectTabbed - The window will use the tabbed effectWails 3 comes with a built-in systray. This is a fully featured systray that has +been designed to be as simple as possible to use. It is possible to set the +icon, tooltip and menu of the systray. It is possible to also "attach" a window +to the systray. Doing this will provide the following functionality:
+On macOS, if there is no attached window, the systray will use the default +method of displaying the menu (any button). If there is an attached window but +no menu, the systray will toggle the window regardless of the button pressed.
+Bindings work in a similar way to v2, by providing a means to bind struct
+methods to the frontend. These can be called in the frontend using the binding
+wrappers generated by the wails3 generate bindings command:
// @ts-check
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+import { main } from "./models";
+
+window.go = window.go || {};
+window.go.main = {
+ GreetService: {
+ /**
+ * GreetService.Greet
+ * Greet greets a person
+ * @param name {string}
+ * @returns {Promise<string>}
+ **/
+ Greet: function (name) {
+ wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
+ },
+
+ /**
+ * GreetService.GreetPerson
+ * GreetPerson greets a person
+ * @param person {main.Person}
+ * @returns {Promise<string>}
+ **/
+ GreetPerson: function (person) {
+ wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
+ },
+ },
+};
+Bound methods are obfuscated by default, and are identified using uint32 IDs,
+calculated using the
+FNV hashing algorithm.
+This is to prevent the method name from being exposed in production builds. In
+debug mode, the method IDs are logged along with the calculated ID of the method
+to aid in debugging. If you wish to add an extra layer of obfuscation, you can
+use the BindAliases option. This allows you to specify a map of alias IDs to
+method IDs. When the frontend calls a method using an ID, the method ID will be
+looked up in the alias map first for a match. If it does not find it, it assumes
+it's a standard method ID and tries to find the method in the usual way.
Example:
+ app := application.New(application.Options{
+ Bind: []any{
+ &GreetService{},
+ },
+ BindAliases: map[uint32]uint32{
+ 1: 1411160069,
+ 2: 4021313248,
+ },
+ Assets: application.AssetOptions{
+ Handler: application.AssetFileServerFS(assets),
+ },
+ Mac: application.MacOptions{
+ ApplicationShouldTerminateAfterLastWindowClosed: true,
+ },
+ })
+We can now call using this alias in the frontend: wails.Call(1, "world!").
If you don't mind your calls being available in plain text in your binary and
+have no intention of using garble, then
+you can use the insecure wails.CallByName() method. This method takes the
+fully qualified name of the method to call and the arguments to pass to it.
+Example:
```go
+wails.CallByName("main.GreetService.Greet", "world!")
+```
+Danger
+This is only provided as a convenience method for development. It is not recommended to use this in production.
+Native drag and drop can be enabled per-window. Simply set the
+EnableDragAndDrop window config option to true and the window will allow
+files to be dragged onto it. When this happens, the events.FilesDropped event
+will be emitted. The filenames can then be retrieved from the
+WindowEvent.Context() using the DroppedFiles() method. This returns a slice
+of strings containing the filenames.
Context menus are contextual menus that are shown when the user right-clicks on
+an element. Creating a context menu is the same as creating a standard menu , by
+using app.NewMenu(). To make the context menu available to a window, call
+window.RegisterContextMenu(name, menu). The name will be the id of the context
+menu and used by the frontend.
To indicate that an element has a context menu, add the data-contextmenu
+attribute to the element. The value of this attribute should be the name of a
+context menu previously registered with the window.
It is possible to register a context menu at the application level, making it
+available to all windows. This can be done using
+app.RegisterContextMenu(name, menu). If a context menu cannot be found at the
+window level, the application context menus will be checked. A demo of this can
+be found in v3/examples/contextmenus.
Dialogs are now available in JavaScript!
+Dialog buttons in Windows are not configurable and are constant depending on the
+type of dialog. To trigger a callback when a button is pressed, create a button
+with the same name as the button you wish to have the callback attached to.
+Example: Create a button with the label Ok and use OnClick() to set the
+callback method:
dialog := app.QuestionDialog().
+ SetTitle("Update").
+ SetMessage("The cancel button is selected when pressing escape")
+ ok := dialog.AddButton("Ok")
+ ok.OnClick(func() {
+ // Do something
+ })
+ no := dialog.AddButton("Cancel")
+ dialog.SetDefaultButton(ok)
+ dialog.SetCancelButton(no)
+ dialog.Show()
+The clipboard API has been simplified. There is now a single Clipboard object
+that can be used to read and write to the clipboard. The Clipboard object is
+available in both Go and JS. SetText() to set the text and Text() to get the
+text.
The Wails Markup Language is a simple markup language that allows you to add +functionality to standard HTML elements without the use of Javascript.
+The following tags are currently supported:
+data-wml-event#This specifies that a Wails event will be emitted when the element is clicked. +The value of the attribute should be the name of the event to emit.
+Example:
+ +Sometimes you need the user to confirm an action. This can be done by adding the
+data-wml-confirm attribute to the element. The value of this attribute will be
+the message to display to the user.
Example:
+<button data-wml-event="delete-all-items" data-wml-confirm="Are you sure?">
+ Delete All Items
+</button>
+data-wml-window#Any wails.window method can be called by adding the data-wml-window
+attribute to an element. The value of the attribute should be the name of the
+method to call. The method name should be in the same case as the method.
data-wml-trigger#This attribute specifies which javascript event should trigger the action. The
+default is click.
Plugins are a way to extend the functionality of your Wails application.
+Plugins are standard Go structure that adhere to the following interface:
+type Plugin interface {
+ Name() string
+ Init(*application.App) error
+ Shutdown()
+ CallableByJS() []string
+ InjectJS() string
+}
+The Name() method returns the name of the plugin. This is used for logging
+purposes.
The Init(*application.App) error method is called when the plugin is loaded.
+The *application.App parameter is the application that the plugin is being
+loaded into. Any errors will prevent the application from starting.
The Shutdown() method is called when the application is shutting down.
The CallableByJS() method returns a list of exported functions that can be
+called from the frontend. These method names must exactly match the names of the
+methods exported by the plugin.
The InjectJS() method returns JavaScript that should be injected into all
+windows as they are created. This is useful for adding custom JavaScript
+functions that complement the plugin.
In Go, enums are often defined as a type and a set of constants. For example:
+ +Due to incompatibility between Go and JavaScript, custom types cannot be used in +this way. The best strategy is to use a type alias for float64:
+ +In Javascript, you can then use the following:
+ +float64? Can't we use int?int. Everything is a
+ number, which translates to float64 in Go. There are also restrictions
+ on casting types in Go's reflection package, which means using int doesn't
+ work.Logging in v2 was confusing as both application logs and system (internal) logs +were using the same logger. We have simplified this as follows:
+slog logger. This is
+ configured using the logger option in the application options. By default,
+ this uses the tint logger.log plugin which
+ utilises slog under the hood. This plugin provides a simple API for logging
+ to the console. It is available in both Go and JS.If this is set, the WndProc will be intercepted and the function will be called. +This allows you to handle Windows messages directly. The function should have +the following signature:
+ +The shouldReturn value should be set to true if the returnValue should be
+returned by the main wndProc method. If it is set to false, the return value
+will be ignored and the message will continue to be processed by the main
+wndProc method.
In v2, there was the HideWindowOnClose flag to hide the window when it closed.
+There was a logical overlap between this flag and the OnBeforeClose callback.
+In v3, the HideWindowOnClose flag has been removed and the OnBeforeClose
+callback has been renamed to ShouldClose. The ShouldClose callback is called
+when the user attempts to close a window. If the callback returns true, the
+window will close. If it returns false, the window will not close. This can be
+used to hide the window instead of closing it.
In v2, the --wails-drag attribute was used to indicate that an element could
+be used to drag the window. In v3, this has been replaced with
+--webkit-app-region to be more in line with the way other frameworks handle
+this. The --webkit-app-region attribute can be set to any of the following
+values:
drag - The element can be used to drag the windowno-drag - The element cannot be used to drag the windowWe would have ideally liked to use app-region, however this is not supported
+by the getComputedStyle call on webkit on macOS.
Bindings work in a similar way to v2, by providing a means to bind struct
+methods to the frontend. These can be called in the frontend using the binding
+wrappers generated by the wails3 generate bindings command:
// @ts-check
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+import { main } from "./models";
+
+window.go = window.go || {};
+window.go.main = {
+ GreetService: {
+ /**
+ * GreetService.Greet
+ * Greet greets a person
+ * @param name {string}
+ * @returns {Promise<string>}
+ **/
+ Greet: function (name) {
+ wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
+ },
+
+ /**
+ * GreetService.GreetPerson
+ * GreetPerson greets a person
+ * @param person {main.Person}
+ * @returns {Promise<string>}
+ **/
+ GreetPerson: function (person) {
+ wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
+ },
+ },
+};
+Bound methods are obfuscated by default, and are identified using uint32 IDs,
+calculated using the
+FNV hashing algorithm.
+This is to prevent the method name from being exposed in production builds. In
+debug mode, the method IDs are logged along with the calculated ID of the method
+to aid in debugging. If you wish to add an extra layer of obfuscation, you can
+use the BindAliases option. This allows you to specify a map of alias IDs to
+method IDs. When the frontend calls a method using an ID, the method ID will be
+looked up in the alias map first for a match. If it does not find it, it assumes
+it's a standard method ID and tries to find the method in the usual way.
Example:
+ app := application.New(application.Options{
+ Bind: []any{
+ &GreetService{},
+ },
+ BindAliases: map[uint32]uint32{
+ 1: 1411160069,
+ 2: 4021313248,
+ },
+ Assets: application.AssetOptions{
+ Handler: application.AssetFileServerFS(assets),
+ },
+ Mac: application.MacOptions{
+ ApplicationShouldTerminateAfterLastWindowClosed: true,
+ },
+ })
+We can now call using this alias in the frontend: wails.Call(1, "world!").
If you don't mind your calls being available in plain text in your binary and
+have no intention of using garble, then
+you can use the insecure wails.CallByName() method. This method takes the
+fully qualified name of the method to call and the arguments to pass to it.
+Example:
```go
+wails.CallByName("main.GreetService.Greet", "world!")
+```
+Danger
+This is only provided as a convenience method for development. It is not recommended to use this in production.
+The clipboard API has been simplified. There is now a single Clipboard object
+that can be used to read and write to the clipboard. The Clipboard object is
+available in both Go and JS. SetText() to set the text and Text() to get the
+text.
Context menus are contextual menus that are shown when the user right-clicks on
+an element. Creating a context menu is the same as creating a standard menu , by
+using app.NewMenu(). To make the context menu available to a window, call
+window.RegisterContextMenu(name, menu). The name will be the id of the context
+menu and used by the frontend.
To indicate that an element has a context menu, add the data-contextmenu
+attribute to the element. The value of this attribute should be the name of a
+context menu previously registered with the window.
It is possible to register a context menu at the application level, making it
+available to all windows. This can be done using
+app.RegisterContextMenu(name, menu). If a context menu cannot be found at the
+window level, the application context menus will be checked. A demo of this can
+be found in v3/examples/contextmenus.
Dialogs are now available in JavaScript!
+Dialog buttons in Windows are not configurable and are constant depending on the
+type of dialog. To trigger a callback when a button is pressed, create a button
+with the same name as the button you wish to have the callback attached to.
+Example: Create a button with the label Ok and use OnClick() to set the
+callback method:
dialog := app.QuestionDialog().
+ SetTitle("Update").
+ SetMessage("The cancel button is selected when pressing escape")
+ ok := dialog.AddButton("Ok")
+ ok.OnClick(func() {
+ // Do something
+ })
+ no := dialog.AddButton("Cancel")
+ dialog.SetDefaultButton(ok)
+ dialog.SetCancelButton(no)
+ dialog.Show()
+Native drag and drop can be enabled per-window. Simply set the
+EnableDragAndDrop window config option to true and the window will allow
+files to be dragged onto it. When this happens, the events.FilesDropped event
+will be emitted. The filenames can then be retrieved from the
+WindowEvent.Context() using the DroppedFiles() method. This returns a slice
+of strings containing the filenames.
In Go, enums are often defined as a type and a set of constants. For example:
+ +Due to incompatibility between Go and JavaScript, custom types cannot be used in +this way. The best strategy is to use a type alias for float64:
+ +In Javascript, you can then use the following:
+ +float64? Can't we use int?int. Everything is a
+ number, which translates to float64 in Go. There are also restrictions
+ on casting types in Go's reflection package, which means using int doesn't
+ work.In v3, there are 3 types of events:
+Application events are events that are emitted by the application. These events
+include native events such as ApplicationDidFinishLaunching on macOS.
Window events are events that are emitted by a window. These events include
+native events such as WindowDidBecomeMain on macOS. Common events are also
+defined, so they work cross-platform, e.g. WindowClosing.
Events that the user defines are called WailsEvents. This is to differentiate
+them from the Event object that is used to communicate with the browser.
+WailsEvents are now objects that encapsulate all the details of an event. This
+includes the event name, the data, and the source of the event.
The data associated with a WailsEvent is now a single value. If multiple values +are required, then a struct can be used.
+Emit function signature#The signatures events callbacks (as used by On, Once & OnMultiple) have
+changed. In v2, the callback function received optional data. In v3, the
+callback function receives a WailsEvent object that contains all data related
+to the event.
Similarly, the Emit function has changed. Instead of taking a name and
+optional data, it now takes a single WailsEvent object that it will emit.
Off and OffAll#In v2, Off and OffAll calls would remove events in both JS and Go. Due to
+the multi-window nature of v3, this has been changed so that these methods only
+apply to the context they are called in. For example, if you call Off in a
+window, it will only remove events for that window. If you use Off in Go, it
+will only remove events for Go.
Event Hooks are a new feature in v3. They allow you to hook into the event
+system and perform actions when certain events are emitted. For example, you can
+hook into the WindowClosing event and perform some cleanup before the window
+closes. Hooks can be registered at the application level or at the window level
+using RegisterHook. Application level are for application events. Window level
+hooks will only be called for the window they are registered with.
When emitting an event in Go, it will dispatch the event to local Go listeners +and also each window in the application. When emitting an event in JS, it now +sends the event to the application. This will be processed as if it was emitted +in Go, however the sender ID will be that of the window.
+ + + + + + + + + + + + + +Logging in v2 was confusing as both application logs and system (internal) logs +were using the same logger. We have simplified this as follows:
+slog logger. This is
+ configured using the logger option in the application options. By default,
+ this uses the tint logger.log plugin which
+ utilises slog under the hood. This plugin provides a simple API for logging
+ to the console. It is available in both Go and JS.If this is set, the WndProc will be intercepted and the function will be called. +This allows you to handle Windows messages directly. The function should have +the following signature:
+ +The shouldReturn value should be set to true if the returnValue should be
+returned by the main wndProc method. If it is set to false, the return value
+will be ignored and the message will continue to be processed by the main
+wndProc method.
In v2, there was the HideWindowOnClose flag to hide the window when it closed.
+There was a logical overlap between this flag and the OnBeforeClose callback.
+In v3, the HideWindowOnClose flag has been removed and the OnBeforeClose
+callback has been renamed to ShouldClose. The ShouldClose callback is called
+when the user attempts to close a window. If the callback returns true, the
+window will close. If it returns false, the window will not close. This can be
+used to hide the window instead of closing it.
In v2, the --wails-drag attribute was used to indicate that an element could
+be used to drag the window. In v3, this has been replaced with
+--webkit-app-region to be more in line with the way other frameworks handle
+this. The --webkit-app-region attribute can be set to any of the following
+values:
drag - The element can be used to drag the windowno-drag - The element cannot be used to drag the windowWe would have ideally liked to use app-region, however this is not supported
+by the getComputedStyle call on webkit on macOS.
Plugins are a way to extend the functionality of your Wails application.
+Plugins are standard Go structure that adhere to the following interface:
+type Plugin interface {
+ Name() string
+ Init(*application.App) error
+ Shutdown()
+ CallableByJS() []string
+ InjectJS() string
+}
+The Name() method returns the name of the plugin. This is used for logging
+purposes.
The Init(*application.App) error method is called when the plugin is loaded.
+The *application.App parameter is the application that the plugin is being
+loaded into. Any errors will prevent the application from starting.
The Shutdown() method is called when the application is shutting down.
The CallableByJS() method returns a list of exported functions that can be
+called from the frontend. These method names must exactly match the names of the
+methods exported by the plugin.
The InjectJS() method returns JavaScript that should be injected into all
+windows as they are created. This is useful for adding custom JavaScript
+functions that complement the plugin.
Wails 3 comes with a built-in systray. This is a fully featured systray that has +been designed to be as simple as possible to use. It is possible to set the +icon, tooltip and menu of the systray. It is possible to also "attach" a window +to the systray. Doing this will provide the following functionality:
+On macOS, if there is no attached window, the systray will use the default +method of displaying the menu (any button). If there is an attached window but +no menu, the systray will toggle the window regardless of the button pressed.
+ + + + + + + + + + + + + +The Window API has largely remained the same, however the methods are now on an +instance of a window rather than the runtime. Some notable differences are:
+SetFrameless and ToggleDevTools.In v2, this was a pointer to an RGBA struct. In v3, this is an RGBA struct
+value.
This flag has been removed. Now there is a BackgroundType flag that can be
+used to set the type of background the window should have. This flag can be set
+to any of the following values:
BackgroundTypeSolid - The window will have a solid backgroundBackgroundTypeTransparent - The window will have a transparent backgroundBackgroundTypeTranslucent - The window will have a translucent backgroundOn Windows, if the BackgroundType is set to BackgroundTypeTranslucent, the
+type of translucency can be set using the BackdropType flag in the
+WindowsWindow options. This can be set to any of the following values:
Auto - The window will use an effect determined by the systemNone - The window will have no backgroundMica - The window will use the Mica effectAcrylic - The window will use the acrylic effectTabbed - The window will use the tabbed effectThe Wails Markup Language is a simple markup language that allows you to add +functionality to standard HTML elements without the use of Javascript.
+The following tags are currently supported:
+data-wml-event#This specifies that a Wails event will be emitted when the element is clicked. +The value of the attribute should be the name of the event to emit.
+Example:
+ +Sometimes you need the user to confirm an action. This can be done by adding the
+data-wml-confirm attribute to the element. The value of this attribute will be
+the message to display to the user.
Example:
+<button data-wml-event="delete-all-items" data-wml-confirm="Are you sure?">
+ Delete All Items
+</button>
+data-wml-window#Any wails.window method can be called by adding the data-wml-window
+attribute to an element. The value of the attribute should be the name of the
+method to call. The method name should be in the same case as the method.
data-wml-trigger#This attribute specifies which javascript event should trigger the action. The
+default is click.
Note
+This guide is a work in progress.
+Thanks for wanting to help out with development of Wails! This guide will help +you get started.
+v3-alpha branch.Install the CLI: cd v3/cmd/wails3 && go install
Optional: If you are wanting to use the build system to build frontend code, + you will need to install npm.
+For simple programs, you can use the standard go build command. It's also
+possible to use go run.
Wails also comes with a build system that can be used to build more complex
+projects. It utilises the awesome Task build system. For
+more information, check out the task homepage or run wails task --help.
The project has the following structure:
+```
+v3
+├── cmd/wails3 // CLI
+├── examples // Examples of Wails apps
+├── internal // Internal packages
+| ├── runtime // The Wails JS runtime
+| └── templates // The supported project templates
+├── pkg
+| ├── application // The core Wails library
+| └── events // The event definitions
+| └── mac // macOS specific code used by plugins
+| └── w32 // Windows specific code
+├── plugins // Supported plugins
+├── tasks // General tasks
+└── Taskfile.yaml // Development tasks configuration
+```
+We are currently tracking known issues and tasks in the +Alpha Todo List. If you want to +help out, please check this list and follow the instructions in the +Feedback page.
+The preferred way to add window functionality is to add a new function to the
+pkg/application/webview_window.go file. This should implement all the
+functionality required for all platforms. Any platform specific code should be
+called via a webviewWindowImpl interface method. This interface is implemented
+by each of the target platforms to provide the platform specific functionality.
+In some cases, this may do nothing. Once you've added the interface method,
+ensure each platform implements it. A good example of this is the SetMinSize
+method.
webview_window_darwin.gowebview_window_windows.gowebview_window_linux.goMost, if not all, of the platform specific code should be run on the main
+thread. To simplify this, there are a number of invokeSync methods defined in
+application.go.
The runtime is located in v3/internal/runtime. When the runtime is updated,
+the following steps need to be taken:
Events are defined in v3/pkg/events. When adding a new event, the following
+steps need to be taken:
events.txt filewails3 task events:generateThere are a number of types of events: platform specific application and window +events + common events. The common events are useful for cross-platform event +handling, but you aren't limited to the "lowest common denominator". You can use +the platform specific events if you need to.
+When adding a common event, ensure that the platform specific events are mapped.
+An example of this is in window_webview_darwin.go:
// Translate ShouldClose to common WindowClosing event
+ w.parent.On(events.Mac.WindowShouldClose, func(_ *WindowEventContext) {
+ w.parent.emit(events.Common.WindowClosing)
+ })
+NOTE: We may try to automate this in the future by adding the mapping to the +event definition.
+Plugins are a way to extend the functionality of your Wails application.
+Plugins are standard Go structure that adhere to the following interface:
+type Plugin interface {
+ Name() string
+ Init(*application.App) error
+ Shutdown()
+ CallableByJS() []string
+ InjectJS() string
+}
+The Name() method returns the name of the plugin. This is used for logging
+purposes.
The Init(*application.App) error method is called when the plugin is loaded.
+The *application.App parameter is the application that the plugin is being
+loaded into. Any errors will prevent the application from starting.
The Shutdown() method is called when the application is shutting down.
The CallableByJS() method returns a list of exported functions that can be
+called from the frontend. These method names must exactly match the names of the
+methods exported by the plugin.
The InjectJS() method returns JavaScript that should be injected into all
+windows as they are created. This is useful for adding custom JavaScript
+functions that complement the plugin.
The built-in plugins can be found in the v3/plugins directory. Check them out
+for inspiration.
The Wails CLI uses the Task build system. It is imported
+as a library and used to run the tasks defined in Taskfile.yaml. The main
+interfacing with Task happens in v3/internal/commands/task.go.
To check if there's an upgrade for Taskfile, run wails3 task -version and
+check against the Task website.
To upgrade the version of Taskfile used, run:
+ +If there are incompatibilities then they should appear in the
+v3/internal/commands/task.go file.
Usually the best way to fix incompatibilities is to clone the task repo at
+https://github.com/go-task/task and look at the git history to determine what
+has changed and why.
To check all changes have worked correctly, re-install the CLI and check the +version again:
+ +Make sure that all PRs have a ticket associated with them providing context to
+the change. If there is no ticket, please create one first. Ensure that all PRs
+have updated the CHANGELOG.md file with the changes made. The CHANGELOG.md file
+is located in the mkdocs-website/docs directory.
The Wails CLI uses the Task build system. It is imported
+as a library and used to run the tasks defined in Taskfile.yaml. The main
+interfacing with Task happens in v3/internal/commands/task.go.
To check if there's an upgrade for Taskfile, run wails3 task -version and
+check against the Task website.
To upgrade the version of Taskfile used, run:
+ +If there are incompatibilities then they should appear in the
+v3/internal/commands/task.go file.
Usually the best way to fix incompatibilities is to clone the task repo at
+https://github.com/go-task/task and look at the git history to determine what
+has changed and why.
To check all changes have worked correctly, re-install the CLI and check the +version again:
+ + + + + + + + + + + + + + +Status of features in v3.
+Note
+This list is a mixture of public and internal API support.<br/>
+It is not complete and probably not up to date.
+Application interface methods
+| Method | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| run() error | +Y | +Y | +Y | ++ |
| destroy() | ++ | Y | +Y | ++ |
| setApplicationMenu(menu *Menu) | +Y | +Y | +Y | ++ |
| name() string | ++ | Y | +Y | ++ |
| getCurrentWindowID() uint | +Y | +Y | +Y | ++ |
| showAboutDialog(name string, description string, icon []byte) | ++ | Y | +Y | ++ |
| setIcon(icon []byte) | +- | +Y | +Y | ++ |
| on(id uint) | ++ | + | Y | ++ |
| dispatchOnMainThread(fn func()) | +Y | +Y | +Y | ++ |
| hide() | +Y | +Y | +Y | ++ |
| show() | +Y | +Y | +Y | ++ |
| getPrimaryScreen() (*Screen, error) | ++ | Y | +Y | ++ |
| getScreens() ([]*Screen, error) | ++ | Y | +Y | ++ |
Webview Window Interface Methods
+| Method | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| center() | +Y | +Y | +Y | ++ |
| close() | +y | +Y | +Y | ++ |
| destroy() | ++ | Y | +Y | ++ |
| execJS(js string) | +y | +Y | +Y | ++ |
| focus() | +Y | +Y | ++ | + |
| forceReload() | ++ | Y | +Y | ++ |
| fullscreen() | +Y | +Y | +Y | ++ |
| getScreen() (*Screen, error) | +y | +Y | +Y | ++ |
| getZoom() float64 | ++ | Y | +Y | ++ |
| height() int | +Y | +Y | +Y | ++ |
| hide() | +Y | +Y | +Y | ++ |
| isFullscreen() bool | +Y | +Y | +Y | ++ |
| isMaximised() bool | +Y | +Y | +Y | ++ |
| isMinimised() bool | +Y | +Y | +Y | ++ |
| maximise() | +Y | +Y | +Y | ++ |
| minimise() | +Y | +Y | +Y | ++ |
| nativeWindowHandle() (uintptr, error) | +Y | +Y | +Y | ++ |
| on(eventID uint) | +y | ++ | Y | ++ |
| openContextMenu(menu Menu, data ContextMenuData) | +y | +Y | +Y | ++ |
| relativePosition() (int, int) | +Y | +Y | +Y | ++ |
| reload() | +y | +Y | +Y | ++ |
| run() | +Y | +Y | +Y | ++ |
| setAlwaysOnTop(alwaysOnTop bool) | +Y | +Y | +Y | ++ |
| setBackgroundColour(color RGBA) | +Y | +Y | +Y | ++ |
| setEnabled(bool) | ++ | Y | +Y | ++ |
| setFrameless(bool) | ++ | Y | +Y | ++ |
| setFullscreenButtonEnabled(enabled bool) | +- | +Y | +Y | +There is no fullscreen button in Windows | +
| setHTML(html string) | +Y | +Y | +Y | ++ |
| setMaxSize(width, height int) | +Y | +Y | +Y | ++ |
| setMinSize(width, height int) | +Y | +Y | +Y | ++ |
| setRelativePosition(x int, y int) | +Y | +Y | +Y | ++ |
| setResizable(resizable bool) | +Y | +Y | +Y | ++ |
| setSize(width, height int) | +Y | +Y | +Y | ++ |
| setTitle(title string) | +Y | +Y | +Y | ++ |
| setURL(url string) | +Y | +Y | +Y | ++ |
| setZoom(zoom float64) | +Y | +Y | +Y | ++ |
| show() | +Y | +Y | +Y | ++ |
| size() (int, int) | +Y | +Y | +Y | ++ |
| toggleDevTools() | +Y | +Y | +Y | ++ |
| unfullscreen() | +Y | +Y | +Y | ++ |
| unmaximise() | +Y | +Y | +Y | ++ |
| unminimise() | +Y | +Y | +Y | ++ |
| width() int | +Y | +Y | +Y | ++ |
| zoom() | ++ | Y | +Y | ++ |
| zoomIn() | +Y | +Y | +Y | ++ |
| zoomOut() | +Y | +Y | +Y | ++ |
| zoomReset() | +Y | +Y | +Y | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Quit | +Y | +Y | +Y | ++ |
| Hide | +Y | +Y | +Y | ++ |
| Show | +Y | ++ | Y | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Info | +Y | +Y | +Y | ++ |
| Warning | +Y | +Y | +Y | ++ |
| Error | +Y | +Y | +Y | ++ |
| Question | +Y | +Y | +Y | ++ |
| OpenFile | +Y | +Y | +Y | ++ |
| SaveFile | +Y | +Y | +Y | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| SetText | +Y | +Y | +Y | ++ |
| Text | +Y | +Y | +Y | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| OpenContextMenu | +Y | +Y | +Y | ++ |
| On By Default | ++ | + | + | + |
| Control via HTML | +Y | ++ | + | + |
The default context menu is enabled by default for all elements that are
+contentEditable: true, <input> or <textarea> tags or have the
+--default-contextmenu: true style set. The --default-contextmenu: show style
+will always show the context menu The --default-contextmenu: hide style will
+always hide the context menu
Anything nested under a tag with --default-contextmenu: hide style will not
+show the context menu unless it is explicitly set with
+--default-contextmenu: show.
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| GetAll | +Y | +Y | +Y | ++ |
| GetPrimary | +Y | +Y | +Y | ++ |
| GetCurrent | +Y | +Y | +Y | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| IsDarkMode | ++ | + | Y | ++ |
Y = Supported U = Untested
+| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Center | +Y | +Y | +Y | ++ |
| Focus | +Y | +Y | ++ | + |
| FullScreen | +Y | +Y | +Y | ++ |
| GetZoom | +Y | +Y | +Y | +Get current view scale | +
| Height | +Y | +Y | +Y | ++ |
| Hide | +Y | +Y | +Y | ++ |
| Maximise | +Y | +Y | +Y | ++ |
| Minimise | +Y | +Y | +Y | ++ |
| RelativePosition | +Y | +Y | +Y | ++ |
| Screen | +Y | +Y | +Y | +Get screen for window | +
| SetAlwaysOnTop | +Y | +Y | +Y | ++ |
| SetBackgroundColour | +Y | +Y | +Y | +https://github.com/MicrosoftEdge/WebView2Feedback/issues/1621#issuecomment-938234294 | +
| SetEnabled | +Y | +U | +- | +Set the window to be enabled/disabled | +
| SetMaxSize | +Y | +Y | +Y | ++ |
| SetMinSize | +Y | +Y | +Y | ++ |
| SetRelativePosition | +Y | +Y | +Y | ++ |
| SetResizable | +Y | +Y | +Y | ++ |
| SetSize | +Y | +Y | +Y | ++ |
| SetTitle | +Y | +Y | +Y | ++ |
| SetZoom | +Y | +Y | +Y | +Set view scale | +
| Show | +Y | +Y | +Y | ++ |
| Size | +Y | +Y | +Y | ++ |
| UnFullscreen | +Y | +Y | +Y | ++ |
| UnMaximise | +Y | +Y | +Y | ++ |
| UnMinimise | +Y | +Y | +Y | ++ |
| Width | +Y | +Y | +Y | ++ |
| ZoomIn | +Y | +Y | +Y | +Increase view scale | +
| ZoomOut | +Y | +Y | +Y | +Decrease view scale | +
| ZoomReset | +Y | +Y | +Y | +Reset view scale | +
A 'Y' in the table below indicates that the option has been tested and is +applied when the window is created. An 'X' indicates that the option is not +supported by the platform.
+| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| AlwaysOnTop | +Y | +Y | ++ | + |
| BackgroundColour | +Y | +Y | ++ | + |
| BackgroundType | ++ | + | + | Acrylic seems to work but the others don't | +
| CSS | +Y | +Y | ++ | + |
| DevToolsEnabled | +Y | +Y | +Y | ++ |
| DisableResize | +Y | +Y | ++ | + |
| EnableDragAndDrop | ++ | Y | ++ | + |
| EnableFraudulentWebsiteWarnings | ++ | + | + | + |
| Focused | +Y | +Y | ++ | + |
| Frameless | +Y | +Y | ++ | + |
| FullscreenButtonEnabled | +Y | ++ | + | + |
| Height | +Y | +Y | ++ | + |
| Hidden | +Y | +Y | ++ | + |
| HTML | +Y | +Y | ++ | + |
| JS | +Y | +Y | ++ | + |
| Mac | +- | +- | ++ | + |
| MaxHeight | +Y | +Y | ++ | + |
| MaxWidth | +Y | +Y | ++ | + |
| MinHeight | +Y | +Y | ++ | + |
| MinWidth | +Y | +Y | ++ | + |
| Name | +Y | +Y | ++ | + |
| OpenInspectorOnStartup | ++ | + | + | + |
| StartState | +Y | ++ | + | + |
| Title | +Y | +Y | ++ | + |
| URL | +Y | +Y | ++ | + |
| Width | +Y | +Y | ++ | + |
| Windows | +Y | +- | +- | ++ |
| X | +Y | +Y | ++ | + |
| Y | +Y | +Y | ++ | + |
| Zoom | ++ | + | + | + |
| ZoomControlEnabled | ++ | + | + | + |
To log or not to log? System logger vs custom logger.
+| Event | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Default Application Menu | +Y | +Y | +Y | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Icon | +Y | +Y | +Y | +Windows has default icons for light/dark mode & supports PNG or ICO. | +
| Label | +- | +Y | +Y | ++ |
| Label (ANSI Codes) | +- | ++ | + | + |
| Menu | +Y | +Y | +Y | ++ |
| Method | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| setLabel(label string) | +- | +Y | +Y | ++ |
| run() | +Y | +Y | +Y | ++ |
| setIcon(icon []byte) | +Y | +Y | +Y | ++ |
| setMenu(menu *Menu) | +Y | +Y | +Y | ++ |
| setIconPosition(position int) | +- | +Y | +Y | ++ |
| setTemplateIcon(icon []byte) | +- | +Y | +Y | ++ |
| destroy() | +Y | +Y | +Y | ++ |
| setDarkModeIcon(icon []byte) | +Y | +Y | +Y | +Darkmode isn't handled yet (linux) | +
Mapping native events to cross-platform events.
+| Event | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| WindowWillClose | ++ | + | WindowWillClose | ++ |
| WindowDidClose | ++ | + | + | + |
| WindowDidResize | ++ | + | + | + |
| WindowDidHide | ++ | + | + | + |
| ApplicationWillTerminate | ++ | + | + | + |
... Add more
+Working well.
+Working well.
+Contains a lot needed for development.
+| Mode | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Dark | +Y | ++ | + | + |
| Light | +Y | ++ | + | + |
| System | +Y | ++ | + | + |
TBD
+All templates are working.
+Built-in plugin support:
+| Plugin | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Browser | +Y | ++ | Y | ++ |
| KV Store | +Y | +Y | +Y | ++ |
| Log | +Y | +Y | +Y | ++ |
| Single Instance | +Y | ++ | Y | ++ |
| SQLite | +Y | +Y | +Y | ++ |
| Start at login | +Y | ++ | Y | ++ |
| Server | ++ | + | + | + |
TODO:
+| + | Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Icon Generation | +Y | ++ | Y | ++ |
| Icon Embedding | +Y | ++ | Y | ++ |
| Info.plist | +- | ++ | Y | ++ |
| NSIS Installer | ++ | + | - | ++ |
| Mac bundle | +- | ++ | Y | ++ |
| Windows exe | +Y | ++ | - | ++ |
| Feature | +Windows | +Linux | +Mac | +Notes | +
|---|---|---|---|---|
| Resize | +Y | ++ | Y | ++ |
| Drag | +Y | +Y | +Y | +Linux - can always drag with Meta+left mouse |
+
| Feature | +Default | +Notes | +
|---|---|---|
| Backdrop | +MacBackdropNormal | +Standard solid window | +
| DisableShadow | +false | ++ |
| TitleBar | ++ | Standard window decorations by default | +
| Appearance | +DefaultAppearance | ++ |
| InvisibleTitleBarHeight | +0 | +Creates an invisible title bar for frameless windows | +
| DisableShadow | +false | +Disables the window drop shadow | +
| Feature | +Default | +Notes | +
|---|---|---|
| BackdropType | +Solid | ++ |
| DisableIcon | +false | ++ |
| Theme | +SystemDefault | ++ |
| CustomTheme | +nil | ++ |
| DisableFramelessWindowDecorations | +false | ++ |
| WindowMask | +nil | +Makes the window the contents of the bitmap | +
Implementation details for the functions utilized by the *_linux.go files are
+located in the following files:
By default CGO is utilized to compile the Linux port. This prevents easy +cross-compilation and so the PureGo implementation is also being simultaneously +developed.
+The examples can be compiled using the following command:
+CGO_ENABLED=0 go build -tags purego
+Note: things are currently not working after the refactor
+ + + + + + + + + + + + + +We welcome (and encourage) your feedback! Please search for existing tickets or +posts before creating new ones. Here are the different ways to provide feedback:
+If you find a bug, please let us know by posting into the v3 Alpha Feedback channel on Discord.
+Bug tag.wails doctor in your post.v3/example directory or create a new example in the v3/examples folder that clearly shows the issue.[v3 alpha test] <description of bug>.Warning
+Remember, unexpected behaviour isn't necessarily a bug - it might just not do what you expect it to do. Use Suggestions for this.
+If you have a fix for a bug or an update for documentation, please do the following:
+[v3 alpha].PR tag.If you have a suggestion, please let us know by posting into the v3 Alpha Feedback channel on Discord:
+Suggestion tag.Please feel free to reach out to us on Discord if you have any questions.
+
emoji. Please apply to any posts that are a priority for you.There is a list of known issues & work in progress can be found +here.
+To install the Wails CLI, first ensure you have the correct dependencies installed:
+Wails has a number of common dependencies that are required before installation:
+Download Go from the Go Downloads Page.
+Ensure that you follow the official Go installation instructions. You will also need to ensure that your PATH environment variable also includes the path to your ~/go/bin directory. Restart your terminal and do the following checks:
go version~/go/bin is in your PATH variableecho $PATH | grep go/bin$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }Although Wails doesn't require npm to be installed, it is needed by most of the bundled templates.
+Download the latest node installer from the Node Downloads Page. It is best to use the latest release as that is what we generally test against.
+Run npm --version to verify.
The Wails CLI embeds a task runner called Task. It is optional, but recommended. If you do not wish to install Task, you can use the wails3 task command instead of task.
+Installing Task will give you the greatest flexibility.
You will also need to install platform specific dependencies:
+Wails requires that the xcode command line tools are installed. This can be +done by running:
+ +Wails requires that the WebView2 Runtime is installed. Some Windows installations will already have this installed. You can check using the wails doctor command.
Linux requires the standard gcc build tools plus gtk3 and webkit2gtk. Run wails doctor after installation to be shown how to install the dependencies. If your distro/package manager is not supported, please let us know on discord.
To install the Wails CLI using Go Modules, run the following commands:
+ +If you would like to install the latest development version, run the following commands:
+git clone https://github.com/wailsapp/wails.git
+cd wails
+git checkout v3-alpha
+cd v3/cmd/wails3
+go install
+When using the development version, all generated projects will use Go's [replace(https://go.dev/ref/mod#go-mod-file-replace) directive +to ensure projects use the development version of Wails.
+Running wails3 doctor will check if you have the correct dependencies
+installed. If not, it will advise on what is missing and help on how to rectify
+any problems.
wails3 command appears to be missing?#If your system is reporting that the wails3 command is missing, check the
+following:
go/bin directory is in the PATH environment variable.PATH variable.Now that you have created your first application, you can start exploring the other features that v3 alpha provides.
+The best place to start is the examples directory in the Wails repository.
+This contains a number of examples that you can run and play with.
To run an example, you can simply use:
+ +in the example directory.
+Note
+Some examples may not work during alpha development.
+Creating your first application with Wails v3 Alpha is an exciting journey into the world of modern desktop app development. This guide will walk you through the process of creating a basic application, showcasing the power and simplicity of Wails.
+Before you begin, ensure you have the following installed:
+Open your terminal and run the following command to create a new Wails project:
+wails3 init -n myfirstapp
This command creates a new directory called myfirstapp with all the necessary files.
Navigate to the myfirstapp directory. You'll find several files and folders:
build: Contains files used by the build process.frontend: Contains your web frontend code.go.mod & go.sum: Go module files.main.go: The entry point for your Wails application.Taskfile.yml: Defines all the tasks used by the build system. Learn more at the Task website.Take a moment to explore these files and familiarize yourself with the structure.
+Note
+Although Wails v3 uses Task as its default build system, there is nothing stopping you from using make or any other alternative build system.
To build your application, execute:
+wails3 build
This command compiles a debug version of your application and saves it in a new bin directory.
+You can run this like you would any normal application:
./bin/myfirstapp
bin\myfirstapp.exe
./bin/myfirstapp
You'll see a simple UI, the starting point for your application. As it is the debug version, you'll also see logs in the console window. This is useful for debugging purposes.
+We can also run the application in development mode. This mode allows you to make changes to your frontend code and see the changes reflected in the running application without having to rebuild the entire application.
+wails3 dev.frontend/main.js.<h1>Hello Wails!</h1> to <h1>Hello World!</h1>.The application will update automatically, and you'll see the changes reflected in the running application.
+Once you're happy with your changes, build your application again:
+wails3 build
You'll notice that the build time was faster this time. That's because the new build system only builds the parts of your application that have changed.
+You should see a new executable in the build directory.
Once your application is ready for distribution, you can create platform-specific packages:
+To create a .app bundle:
+
.app bundle in the bin directory.
+To create an NSIS installer: +
+This will create a production build and package it into an NSIS installer in thebin directory.
+Wails supports multiple package formats for Linux distribution: +
# Create all package types (AppImage, deb, rpm, and Arch Linux)
+wails3 package
+
+# Or create specific package types
+wails3 task linux:create:appimage # AppImage format
+wails3 task linux:create:deb # Debian package
+wails3 task linux:create:rpm # Red Hat package
+wails3 task linux:create:aur # Arch Linux package
+For more detailed information about packaging options and configuration, check out our Packaging Guide.
+Congratulations! You've just created, developed and packaged your first Wails application. This is just the beginning of what you can achieve with Wails v3. Explore the documentation, experiment with different features, and start building amazing applications!
+ + + + + + + + + + + + + +Welcome to the Wails v3 Alpha documentation. This is your starting point for exploring the latest version of Wails, a powerful framework for building desktop applications using Go and modern web technologies.
+Wails v3 Alpha is the latest iteration of the Wails project, bringing new features and improvements to make desktop application development more efficient and enjoyable. This version is still in alpha, so some features might change before the final release.
+Please consult our Status Page for up-to-date status.
+Here are some of the exciting new features and improvements in Wails v3 Alpha:
+More information about these features and other changes can be found in the What's new section.
+To get started with Wails v3 Alpha:
+Please note that this is an alpha version of Wails v3. Features may be added, removed, or changed in future updates. This version is intended for early adopters and those who wish to contribute to the development of Wails.
+Your feedback is vital to making Wails better. If you encounter any issues or have suggestions, please use our Feedback process. Contributions to the project are also welcome!
+Thank you for trying out Wails v3 Alpha!
+ + + + + + + + + + + + + +