[V3/Docs] Add Events documentation (#3867)

events docs

fix function

fix nav

changelog.md

fix broken link

appease the rabbit

spell check and cleanup

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<--

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

@@ -0,0 +1,131 @@
+# Events
+
+## Event Hooks
+
+--8<--
+./docs/en/API/event_hooks.md
+--8<--
+
+## Custom Events
+You 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.
+
+=== "Go"
+    ```go
+    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")
+    ```
+=== "JS"
+    ```javascript
+    wails.Events.Emit("event1", "Hello from JS")
+
+    wails.Events.On("event2", function(event) {
+        console.log("[JS] CustomEvent received", event)
+        console.log(event.data) // prints "Hello from Go" to the webview console
+    })
+
+    ```
+
+### Emitting Events
+
+`application.EmitEvent(name string, data ...any)`
+:   Emits an event from the application instance
+
+`window.EmitEvent(name string, data ...any)`
+:   Emits an event from the window instance
+
+`wails.Events.Emit(event:wails.Events.EventData)`
+:   Emits an event from the frontend sending an object with `name` and `data` properties or the typescript type WailsEvent 
+
+### Receiving Events
+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))`
+:   Registers an event on the application instance this will trigger every time the event is emitted
+
+`application.OnMultipleEvent(name string, handler func(data ...any), count int)`
+:   Registers an event on the application instance this will trigger every time the event is emitted up to the count specified 
+
+Frontend
+
+`wails.Events.On(name: string, callback: ()=>void)`, 
+:   Registers an event on the frontend, this function returns a function that can be called to remove the event listener
+
+`wails.Events.Once(name: string, callback: ()=>void)`, 
+:   Registers an event on the frontend that will only be called once, this function returns a function that can be called to remove the event listener
+
+`wails.Events.OnMultiple(name: string, callback: ()=>void, count: number)`, 
+:   Registers an event on the frontend that will only be called `count` times, this function returns a function that can be called to remove the event listener
+
+### Removing Events
+There 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)`
+:   Removes an event listener with the specificed name
+
+`application.ResetEvents()`
+:   Removes all registered events and hooks
+
+Frontend
+
+`wails.Events.OffAll()`
+:   Removes all registered events
+
+`wails.Events.Off(name: string)`
+:   Removes an event listener with the specified name
+
+
+## Event Types
+
+### ApplicationEvent
+Returned when an application hook event is triggered. The event can be cancelled by calling the `Cancel()` method on the event.
+```go
+type ApplicationEvent struct {
+  Id        uint
+  ctx       *ApplicationEventContext
+  Cancelled bool
+}
+
+// Cancel the event
+func (a *ApplicationEvent) Cancel() {}
+```
+
+### WindowEvent
+Returned when a window hook event is triggered. The event can be cancelled by calling the `Cancel()` method on the event.
+```go
+type WindowEvent struct {
+	ctx       *WindowEventContext
+	Cancelled bool
+}
+
+// Cancel the event
+func (w *WindowEvent) Cancel() {}
+```
+
+### CustomEvent
+
+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.
+```go
+type CustomEvent struct {
+	Name      string `json:"name"`
+	Data      any    `json:"data"`
+	Sender    string `json:"sender"`
+	Cancelled bool
+}
+
+// Cancel the event
+func (c *CustomEvent) Cancel() {}
+```

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

@@ -0,0 +1,30 @@
+#### Linux Events
+
+##### Application Events
+
+`events.Linux.ApplicationStartup`
+:   Triggered when the application starts
+
+`events.Linux.SystemThemeChanged`
+:   Triggered when the system theme changes
+
+##### Window Events
+
+`events.Linux.WindowLoadChanged`
+:   Triggered when the window load changes
+
+`events.Linux.WindowDeleteEvent`
+:   Triggered when the window is deleted
+
+`events.Linux.WindowDidMove`
+:   Triggered when the window is moved
+
+`events.Linux.WindowDidResize`
+:   Triggered when the window is resized
+
+`events.Linux.WindowFocusIn`
+:   Triggered when the window gains focus
+
+`events.Linux.WindowFocusOut`
+:   Triggered when the window loses focus
+