Merge branch 'v3-alpha' into v3-alpha-feature/3659-support-webview-op…

…tions

.github/pull_request_template.md

@@ -1,9 +1,19 @@
 
 <!--
-READ CAREFULLY: Before submitting your PR, please ensure you have created an issue for your PR.
-It is essential that you do this so that we can discuss the proposed changes before you spend time on them.
-If you do not create an issue, your PR may be rejected without review.
-If a relevant issue already exists, please reference it in your PR by including `Fixes #<issue number>` in your PR description.
+
+*********************************************************************
+*               PLEASE READ BEFORE SUBMITTING YOUR PR               *
+*     YOUR PR MAY BE REJECTED IF IT DOES NOT FOLLOW THESE STEPS     *
+*********************************************************************
+
+- *DO NOT* submit PRs for v3 alpha enhancements, unless you have opened a post on the discord channel.
+  All enhancements must be discussed first.
+  The feedback guide for v3 is here: https://v3alpha.wails.io/getting-started/feedback/
+
+- Before submitting your PR, please ensure you have created and linked the PR to an issue.
+- If a relevant issue already exists, please reference it in your PR by including `Fixes #<issue number>` in your PR description.
+- Please fill in the checklists.
+
 -->
 
 # Description
@@ -14,7 +24,7 @@ Fixes # (issue)
 
 ## Type of change
 
-Please delete options that are not relevant.
+Please select the option that is relevant.
 
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
@@ -28,6 +38,8 @@ Please describe the tests that you ran to verify your changes. Provide instructi
 - [ ] Windows
 - [ ] macOS
 - [ ] Linux
+
+If you checked Linux, please specify the distro and version.
 
 ## Test Configuration
 

mkdocs-website/Dockerfile

@@ -0,0 +1,2 @@
+FROM squidfunk/mkdocs-material
+RUN python3 -m pip install mkdocs-table-reader-plugin mkdocs-git-committers-plugin-2 mkdocs-static-i18n

mkdocs-website/Taskfile.yml

@@ -20,6 +20,10 @@ tasks:
     cmds:
       - python3 -m pip install -r requirements.insiders.txt --user
 
+  build:docker:
+    cmds:
+      - docker build -t wailsapp/mkdocs .
+
   upgrade:insiders:
     summary: Upgrade the project (insiders)
     preconditions:
@@ -38,11 +42,8 @@ tasks:
 
   serve:
     summary: Builds the documentation and serves it locally
-    preconditions:
-      - sh: mkdocs --version
-        msg: "Looks like mkdocs isn't installed. Run `wails3 task setup` or `task setup` in the documentation directory to install it."
     cmds:
-      - mkdocs serve
+      - docker run --rm -it -p 8000:8000 -v $PWD:/docs wailsapp/mkdocs
 
   serve:insiders:
     summary: Builds the documentation and serves it locally

mkdocs-website/docs/en/API/application.md

@@ -133,6 +133,57 @@ API: `Show()`
     app.Show()
 ```
 
+### Path
+
+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
+
+```go
+    // 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
+```
+
+## Paths
+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
+
+
 --8<--
 ./docs/en/API/application_window.md
 ./docs/en/API/application_menu.md

mkdocs-website/docs/en/API/application_dialogs.md

@@ -1,4 +1,33 @@
 
+!!! warning "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.
+
+    ```go
+    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:
+
+    ```go
+    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()
+    })
+    ```
+
 ### ShowAboutDialog
 
 API: `ShowAboutDialog()`

mkdocs-website/docs/en/API/application_events.md

@@ -1,12 +1,42 @@
+### OnEvent
 
-### On
+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.
+
+### OffEvent
+API:
+`OffEvent(name string)`
+
+`OffEvent()` removes an event listener for a specific named event specified.
+
+### OnMultipleEvent
+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.
+
+### ResetEvents
+API:
+`ResetEvents()`
+
+`ResetEvents()` removes all event listeners for all application events.
+
+### OnApplicationEvent
+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/events/#applicationevent)
 
+### RegisterApplicationHook
 API:
-`On(eventType events.ApplicationEventType, callback func(event *Event)) func()`
+`RegisterApplicationEventHook(eventType events.ApplicationEventType, callback func(event *ApplicationEvent)) 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.
+`RegisterApplicationEventHook()` registers a callback to be triggered based on specific application events.
 
 ### RegisterHook
 

mkdocs-website/docs/en/API/event_hooks.md

@@ -0,0 +1,119 @@
+wails3 provides an event system that allows for hooking into application and window events
+
+```go
+// Notification of application start
+application.RegisterApplicationEventHook(events.Common.ApplicationStarted, func(event *application.ApplicationEvent) {
+    app.Logger.Info("Application started!")
+})
+```
+
+```go
+// 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!")
+    }
+})
+```
+
+```go
+// 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()
+})
+```
+
+```go
+// Notification of window focus
+window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
+    app.Logger.Info("[ApplicationEvent] Window focus!")
+})
+```
+
+### Application Events
+
+Application events are hookable events that can be registered with `application.RegisterApplicationEventHook()`
+and `application.OnApplicationEvent()`. These events are based on `events.ApplicationEventType`.
+
+`events.Common.ApplicationStarted`
+:   Triggered when the application starts
+
+`events.Common.ThemeChanged`
+:   Triggered when the application theme changes
+
+
+### Window Events
+
+`events.Common.WindowMaximised` 
+:   Triggered when the window is maximised
+
+`events.Common.WindowUnmaximised`
+:   Triggered when the window is unmaximised
+
+`events.Common.WindowMinimised` 
+:   Triggered when the window is minimised
+
+`events.Common.WindowUnminimised`
+:   Triggered when the window is unminimised
+
+`events.Common.WindowFullscreen`
+:   Triggered when the window is set to fullscreen
+
+`events.Common.WindowUnfullscreen`
+:   Triggered when the window is unfullscreened
+
+`events.Common.WindowRestored`
+:   Triggered when the window is restored
+
+`events.Common.WindowClosing`
+:   Triggered before the window closes
+
+`events.Common.WindowZoom` 
+:   Triggered when the window is zoomed
+
+`events.Common.WindowZoomOut`
+:   Triggered when the window is zoomed out
+
+`events.Common.WindowZoomIn` 
+:   Triggered when the window is zoomed in
+
+`events.Common.WindowZoomReset`
+:   Triggered when the window zoom is reset
+
+`events.Common.WindowFocus` 
+:   Triggered when the window gains focus
+
+`events.Common.WindowLostFocus` 
+:   Triggered when the window loses focus
+
+`events.Common.WindowShow`
+:   Triggered when the window is shown
+
+`events.Common.WindowHide` 
+:   Triggered when the window is hidden
+
+`events.Common.WindowDPIChanged`
+:   Triggered when the window DPI changes
+
+`events.Common.WindowFilesDropped`
+:   Triggered when files are dropped on the window
+
+`events.Common.WindowRuntimeReady`
+:   Triggered when the window runtime is ready
+
+`events.Common.WindowDidMove` 
+:   Triggered when the window is moved
+
+`events.Common.WindowDidResize` 
+:   Triggered when the window is resized
+
+### OS-Specific Events
+--8<--
+./docs/en/API/events_linux.md
+./docs/en/API/events_windows.md
+./docs/en/API/events_mac.md
+--8<--