Update installation instructions

2026-08-05 13:53:43 -07:00 · 2023-11-02 20:53:59 +11:00
parent c6ecbd56e5
commit f28c9515ad
40 changed files with 2337 additions and 11 deletions
@@ -0,0 +1,358 @@
+# Application
+
+The application API assists in creating an application using the Wails framework.
+
+### New
+
+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.
+
+```go title="main.go" hl_lines="6-9"
+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
+
+`Get()` returns the global application instance. It's useful when you need to
+access the application from different parts of your code.
+
+```go
+    // Get the application instance
+    app := application.Get()
+```
+
+### Capabilities
+
+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.
+
+```go
+    // Get the application capabilities
+    capabilities := app.Capabilities()
+	if capabilities.HasNativeDrag {
+		// Do something
+    }
+```
+
+### GetPID
+
+API: `GetPID() int`
+
+`GetPID()` returns the Process ID of the application.
+
+```go
+    pid := app.GetPID()
+```
+
+### Run
+
+API: `Run() error`
+
+`Run()` starts the execution of the application and its components.
+
+```go
+    app := application.New(application.Options{
+	    //options
+	})
+    // Run the application
+    err := application.Run()
+    if err != nil {
+        // Handle error
+    }
+```
+
+### Quit
+
+API: `Quit()`
+
+`Quit()` quits the application by destroying windows and potentially other
+components.
+
+```go
+    // Quit the application
+    app.Quit()
+```
+
+### IsDarkMode
+
+API: `IsDarkMode() bool`
+
+`IsDarkMode()` checks if the application is running in dark mode. It returns a
+boolean indicating whether dark mode is enabled.
+
+```go
+    // Check if dark mode is enabled
+    if app.IsDarkMode() {
+        // Do something
+    }
+```
+
+### Hide
+
+API: `Hide()`
+
+`Hide()` hides the application window.
+
+```go
+    // Hide the application window
+    app.Hide()
+```
+
+### Show
+
+API: `Show()`
+
+`Show()` shows the application window.
+
+```go
+    // Show the application window
+    app.Show()
+```
+
+### NewWebviewWindow
+
+API: `NewWebviewWindow() *WebviewWindow`
+
+`NewWebviewWindow()` creates a new Webview window with default options, and
+returns it.
+
+```go
+    // Create a new webview window
+    window := app.NewWebviewWindow()
+```
+
+### NewWebviewWindowWithOptions
+
+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.
+
+```go
+    // Create a new webview window with custom options
+    window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
+		Name: "Main",
+        Title: "My Window",
+        Width: 800,
+        Height: 600,
+    })
+```
+
+### OnWindowCreation
+
+API: `OnWindowCreation(callback func(window *WebviewWindow))`
+
+`OnWindowCreation()` registers a callback function to be called when a window is
+created.
+
+```go
+    // Register a callback to be called when a window is created
+    app.OnWindowCreation(func(window *WebviewWindow) {
+        // Do something
+    })
+```
+
+### GetWindowByName
+
+API: `GetWindowByName(name string) *WebviewWindow`
+
+`GetWindowByName()` fetches and returns a window with a specific name.
+
+```go
+    // Get a window by name
+    window := app.GetWindowByName("Main")
+```
+
+### CurrentWindow
+
+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.
+
+```go
+    // Get the current window
+    window := app.CurrentWindow()
+```
+
+### RegisterContextMenu
+
+API: `RegisterContextMenu(name string, menu *Menu)`
+
+`RegisterContextMenu()` registers a context menu with a given name. This menu
+can be used later in the application.
+
+```go
+
+    // Create a new menu
+    ctxmenu := app.NewMenu()
+
+    // Register the menu as a context menu
+    app.RegisterContextMenu("MyContextMenu", ctxmenu)
+```
+
+### SetMenu
+
+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.
+
+```go
+    // Create a new menu
+    menu := app.NewMenu()
+
+    // Set the menu for the application
+    app.SetMenu(menu)
+```
+
+### ShowAboutDialog
+
+API: `ShowAboutDialog()`
+
+`ShowAboutDialog()` shows an "About" dialog box. It can show the application's
+name, description and icon.
+
+```go
+    // Show the about dialog
+    app.ShowAboutDialog()
+```
+
+### Info
+
+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.
+
+### Question
+
+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.
+
+### Warning
+
+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.
+
+### Error
+
+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.
+
+### OpenFile
+
+API: `OpenFileDialog()`
+
+`OpenFileDialog()` creates and returns a new `OpenFileDialogStruct`. This dialog
+prompts the user to select one or more files from their file system.
+
+### SaveFile
+
+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.
+
+### OpenDirectory
+
+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.
+
+### On
+
+API:
+`On(eventType events.ApplicationEventType, callback func(event *Event)) func()`
+
+`On()` registers an event listener for specific application events. The callback
+function provided will be triggered when the corresponding event occurs. The
+function returns a function that can be called to remove the listener.
+
+### RegisterHook
+
+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.
+
+### GetPrimaryScreen
+
+API: `GetPrimaryScreen() (*Screen, error)`
+
+`GetPrimaryScreen()` returns the primary screen of the system.
+
+### GetScreens
+
+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.
+
+## Options
+
+```go title="application_options.go"
+--8<--
+../v3/pkg/application/options_application.go
+--8<--
+```
+
+### Windows Options
+
+```go title="application_options_windows.go"
+--8<--
+../v3/pkg/application/options_application_win.go
+--8<--
+```
+
+### Mac Options
+
+```go title="options_application_mac.go"
+--8<--
+../v3/pkg/application/options_application_mac.go
+--8<--
+```
@@ -0,0 +1,50 @@
+# Main Thread Functions
+
+These 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.
+
+### InvokeSync
+
+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.
+
+### InvokeSyncWithResult
+
+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.
+
+### InvokeSyncWithError
+
+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.
+
+### InvokeSyncWithResultAndError
+
+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.
+
+### InvokeAsync
+
+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.
@@ -0,0 +1,69 @@
+# Menu
+
+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:
+
+```go
+    // Create a new menu
+    menu := app.NewMenu()
+```
+
+The following operations are then available on the `Menu` type:
+
+### Add
+
+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.
+
+### AddSeparator
+
+API: `AddSeparator()`
+
+This method adds a new separator `MenuItem` to the menu.
+
+### AddCheckbox
+
+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.
+
+### AddRadio
+
+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.
+
+### Update
+
+API: `Update()`
+
+This method processes any radio groups and updates the menu if a menu
+implementation is not initialized.
+
+### AddSubmenu
+
+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.
+
+### AddRole
+
+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`.
+
+### SetLabel
+
+API: `SetLabel(label string)`
+
+This method sets the `label` of the `Menu`.
@@ -0,0 +1,112 @@
+# System Tray
+
+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()`:
+
+```go
+    // Create a new system tray
+tray := app.NewSystemTray()
+```
+
+The following methods are available on the `SystemTray` type:
+
+### SetLabel
+
+API: `SetLabel(label string)`
+
+The `SetLabel` method sets the tray's label.
+
+### Label
+
+API: `Label() string`
+
+The `Label` method retrieves the tray's label.
+
+### PositionWindow
+
+API: `PositionWindow(*WebviewWindow, offset int) error`
+
+The `PositionWindow` method calls both `AttachWindow` and `WindowOffset`
+methods.
+
+### SetIcon
+
+API: `SetIcon(icon []byte) *SystemTray`
+
+The `SetIcon` method sets the system tray's icon.
+
+### SetDarkModeIcon
+
+API: `SetDarkModeIcon(icon []byte) *SystemTray`
+
+The `SetDarkModeIcon` method sets the system tray's icon when in dark mode.
+
+### SetMenu
+
+API: `SetMenu(menu *Menu) *SystemTray`
+
+The `SetMenu` method sets the system tray's menu.
+
+### Destroy
+
+API: `Destroy()`
+
+The `Destroy` method destroys the system tray instance.
+
+### OnClick
+
+API: `OnClick(handler func()) *SystemTray`
+
+The `OnClick` method sets the function to execute when the tray icon is clicked.
+
+### OnRightClick
+
+API: `OnRightClick(handler func()) *SystemTray`
+
+The `OnRightClick` method sets the function to execute when right-clicking the
+tray icon.
+
+### OnDoubleClick
+
+API: `OnDoubleClick(handler func()) *SystemTray`
+
+The `OnDoubleClick` method sets the function to execute when double-clicking the
+tray icon.
+
+### OnRightDoubleClick
+
+API: `OnRightDoubleClick(handler func()) *SystemTray`
+
+The `OnRightDoubleClick` method sets the function to execute when right
+double-clicking the tray icon.
+
+### AttachWindow
+
+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.
+
+### WindowOffset
+
+API: `WindowOffset(offset int) *SystemTray`
+
+The `WindowOffset` method sets the gap in pixels between the system tray and the
+window.
+
+### WindowDebounce
+
+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.
+
+### OpenMenu
+
+API: `OpenMenu()`
+
+The `OpenMenu` method opens the menu associated with the system tray.
@@ -0,0 +1,114 @@
+# Window
+
+To create a window, use
+[Application.NewWebviewWindow](application.md#newwebviewwindow) or
+[Application.NewWebviewWindowWithOptions](application.md#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:
+
+### SetTitle
+
+API: `SetTitle(title string) *WebviewWindow`
+
+This method updates the window title to the provided string. It returns the
+WebviewWindow object, allowing for method chaining.
+
+### Name
+
+API: `Name() string`
+
+This function returns the name of the WebviewWindow.
+
+### SetSize
+
+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.
+
+### SetAlwaysOnTop
+
+API: `SetAlwaysOnTop(b bool) *WebviewWindow`
+
+This function sets the window to stay on top based on the boolean flag provided.
+
+### Show
+
+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.
+
+### Hide
+
+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.
+
+### SetURL
+
+API: `SetURL(s string) *WebviewWindow`
+
+`SetURL` method is used to set the URL of the window to the given URL string.
+
+### SetZoom
+
+API: `SetZoom(magnification float64) *WebviewWindow`
+
+`SetZoom` method sets the zoom level of the window content to the provided
+magnification level.
+
+### GetZoom
+
+API: `GetZoom() float64`
+
+`GetZoom` function returns the current zoom level of the window content.
+
+### GetScreen
+
+API: `GetScreen() (*Screen, error)`
+
+`GetScreen` method returns the screen on which the window is displayed.
+
+#### SetFrameless
+
+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).
+
+#### RegisterContextMenu
+
+API: `RegisterContextMenu(name string, menu *Menu)`
+
+This function is used to register a context menu and assigns it the given name.
+
+#### NativeWindowHandle
+
+API: `NativeWindowHandle() (uintptr, error)`
+
+This function is used to fetch the platform native window handle for the window.
+
+#### Focus
+
+API: `Focus()`
+
+This function is used to focus the window.
+
+#### SetEnabled
+
+API: `SetEnabled(enabled bool)`
+
+This function is used to enable/disable the window based on the provided boolean
+value.
+
+#### SetAbsolutePosition
+
+API: `SetAbsolutePosition(x int, y int)`
+
+This function sets the absolute position of the window in the screen.