From b8ddd2650b9e7fdf6396ebff42ea8824a38eb0fe Mon Sep 17 00:00:00 2001 From: Virgil Date: Thu, 2 Apr 2026 19:28:48 +0000 Subject: [PATCH] docs(display): add AX usage examples Co-Authored-By: Virgil --- pkg/display/display.go | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/pkg/display/display.go b/pkg/display/display.go index 54c78a5..e731058 100644 --- a/pkg/display/display.go +++ b/pkg/display/display.go @@ -78,6 +78,7 @@ func Register(wailsApp *application.App) func(*core.Core) (any, error) { // OnStartup loads config and registers IPC handlers synchronously. // CRITICAL: config handlers MUST be registered before returning — // sub-services depend on them during their own OnStartup. +// Use: _ = svc.OnStartup(context.Background()) func (s *Service) OnStartup(ctx context.Context) error { s.loadConfig() @@ -96,6 +97,7 @@ func (s *Service) OnStartup(ctx context.Context) error { // HandleIPCEvents is auto-discovered and registered by core.WithService. // It bridges sub-service IPC actions to WebSocket events for TS apps. +// Use: _ = svc.HandleIPCEvents(core, msg) func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error { switch m := msg.(type) { case core.ActionServiceStartup: @@ -1225,6 +1227,7 @@ func (s *Service) SetWindowOpacity(name string, opacity float32) error { } // ClearWebviewConsole clears the captured console buffer for a window. +// Use: _ = svc.ClearWebviewConsole("editor") func (s *Service) ClearWebviewConsole(name string) error { _, _, err := s.Core().PERFORM(webview.TaskClearConsole{Window: name}) return err @@ -1608,6 +1611,7 @@ func (s *Service) WriteClipboard(text string) error { } // HasClipboard reports whether the clipboard has text or image content. +// Use: hasContent := svc.HasClipboard() func (s *Service) HasClipboard() bool { textResult, textHandled, _ := s.Core().QUERY(clipboard.QueryText{}) if textHandled { @@ -1625,6 +1629,7 @@ func (s *Service) HasClipboard() bool { } // ClearClipboard clears clipboard text and any image data when supported. +// Use: _ = svc.ClearClipboard() func (s *Service) ClearClipboard() error { result, handled, err := s.Core().PERFORM(clipboard.TaskClear{}) if err != nil { @@ -1640,6 +1645,7 @@ func (s *Service) ClearClipboard() error { } // ReadClipboardImage returns the clipboard image content. +// Use: image, err := svc.ReadClipboardImage() func (s *Service) ReadClipboardImage() (clipboard.ClipboardImageContent, error) { result, handled, err := s.Core().QUERY(clipboard.QueryImage{}) if err != nil { @@ -1653,6 +1659,7 @@ func (s *Service) ReadClipboardImage() (clipboard.ClipboardImageContent, error) } // WriteClipboardImage writes raw image data to the clipboard. +// Use: _ = svc.WriteClipboardImage(data) func (s *Service) WriteClipboardImage(data []byte) error { result, handled, err := s.Core().PERFORM(clipboard.TaskSetImage{Data: data}) if err != nil { @@ -1670,6 +1677,7 @@ func (s *Service) WriteClipboardImage(data []byte) error { // --- Notifications --- // ShowNotification sends a native notification. +// Use: _ = svc.ShowNotification(notification.NotificationOptions{Title: "Build complete", Message: "All checks passed"}) func (s *Service) ShowNotification(opts notification.NotificationOptions) error { _, handled, err := s.Core().PERFORM(notification.TaskSend{Opts: opts}) if err != nil { @@ -1682,6 +1690,7 @@ func (s *Service) ShowNotification(opts notification.NotificationOptions) error } // ShowInfoNotification sends an informational notification. +// Use: _ = svc.ShowInfoNotification("Build complete", "All checks passed") func (s *Service) ShowInfoNotification(title, message string) error { return s.ShowNotification(notification.NotificationOptions{ Title: title, @@ -1691,6 +1700,7 @@ func (s *Service) ShowInfoNotification(title, message string) error { } // ShowWarningNotification sends a warning notification. +// Use: _ = svc.ShowWarningNotification("Build warning", "Tests are flaky") func (s *Service) ShowWarningNotification(title, message string) error { return s.ShowNotification(notification.NotificationOptions{ Title: title, @@ -1700,6 +1710,7 @@ func (s *Service) ShowWarningNotification(title, message string) error { } // ShowErrorNotification sends an error notification. +// Use: _ = svc.ShowErrorNotification("Build failed", "See the log output") func (s *Service) ShowErrorNotification(title, message string) error { return s.ShowNotification(notification.NotificationOptions{ Title: title, @@ -1709,6 +1720,7 @@ func (s *Service) ShowErrorNotification(title, message string) error { } // RequestNotificationPermission requests notification permission. +// Use: granted, err := svc.RequestNotificationPermission() func (s *Service) RequestNotificationPermission() (bool, error) { result, handled, err := s.Core().PERFORM(notification.TaskRequestPermission{}) if err != nil { @@ -1722,6 +1734,7 @@ func (s *Service) RequestNotificationPermission() (bool, error) { } // CheckNotificationPermission checks notification permission. +// Use: granted, err := svc.CheckNotificationPermission() func (s *Service) CheckNotificationPermission() (bool, error) { result, handled, err := s.Core().QUERY(notification.QueryPermission{}) if err != nil { @@ -1735,6 +1748,7 @@ func (s *Service) CheckNotificationPermission() (bool, error) { } // ClearNotifications clears notifications when supported. +// Use: _ = svc.ClearNotifications() func (s *Service) ClearNotifications() error { _, handled, err := s.Core().PERFORM(notification.TaskClear{}) if err != nil { @@ -1749,6 +1763,7 @@ func (s *Service) ClearNotifications() error { // --- Dialogs --- // OpenFileDialog opens a file picker and returns all selected paths. +// Use: paths, err := svc.OpenFileDialog(dialog.OpenFileOptions{Title: "Open report"}) func (s *Service) OpenFileDialog(opts dialog.OpenFileOptions) ([]string, error) { result, handled, err := s.Core().PERFORM(dialog.TaskOpenFile{Opts: opts}) if err != nil { @@ -1762,6 +1777,7 @@ func (s *Service) OpenFileDialog(opts dialog.OpenFileOptions) ([]string, error) } // OpenSingleFileDialog opens a file picker and returns the first selected path. +// Use: path, err := svc.OpenSingleFileDialog(dialog.OpenFileOptions{Title: "Open report"}) func (s *Service) OpenSingleFileDialog(opts dialog.OpenFileOptions) (string, error) { paths, err := s.OpenFileDialog(opts) if err != nil { @@ -1774,6 +1790,7 @@ func (s *Service) OpenSingleFileDialog(opts dialog.OpenFileOptions) (string, err } // SaveFileDialog opens a save dialog and returns the selected path. +// Use: path, err := svc.SaveFileDialog(dialog.SaveFileOptions{Title: "Export report"}) func (s *Service) SaveFileDialog(opts dialog.SaveFileOptions) (string, error) { result, handled, err := s.Core().PERFORM(dialog.TaskSaveFile{Opts: opts}) if err != nil { @@ -1787,6 +1804,7 @@ func (s *Service) SaveFileDialog(opts dialog.SaveFileOptions) (string, error) { } // OpenDirectoryDialog opens a directory picker and returns the selected path. +// Use: path, err := svc.OpenDirectoryDialog(dialog.OpenDirectoryOptions{Title: "Choose workspace"}) func (s *Service) OpenDirectoryDialog(opts dialog.OpenDirectoryOptions) (string, error) { result, handled, err := s.Core().PERFORM(dialog.TaskOpenDirectory{Opts: opts}) if err != nil { @@ -1800,6 +1818,7 @@ func (s *Service) OpenDirectoryDialog(opts dialog.OpenDirectoryOptions) (string, } // ConfirmDialog shows a confirmation prompt. +// Use: confirmed, err := svc.ConfirmDialog("Delete file", "Remove report.txt?") func (s *Service) ConfirmDialog(title, message string) (bool, error) { result, handled, err := s.Core().PERFORM(dialog.TaskMessageDialog{ Opts: dialog.MessageDialogOptions{ @@ -1820,6 +1839,7 @@ func (s *Service) ConfirmDialog(title, message string) (bool, error) { } // PromptDialog shows a prompt-style dialog and returns the selected button. +// Use: button, accepted, err := svc.PromptDialog("Rename file", "Enter a new name") func (s *Service) PromptDialog(title, message string) (string, bool, error) { result, handled, err := s.Core().PERFORM(dialog.TaskMessageDialog{ Opts: dialog.MessageDialogOptions{ @@ -1840,6 +1860,7 @@ func (s *Service) PromptDialog(title, message string) (string, bool, error) { } // DialogMessage shows an informational, warning, or error message via the notification pipeline. +// Use: _ = svc.DialogMessage("warning", "Build failed", "Check the log output") func (s *Service) DialogMessage(kind, title, message string) error { var severity notification.NotificationSeverity switch kind { @@ -1863,6 +1884,7 @@ func (s *Service) DialogMessage(kind, title, message string) error { // --- Theme --- // GetTheme returns the current theme state. +// Use: theme := svc.GetTheme() func (s *Service) GetTheme() *Theme { result, handled, err := s.Core().QUERY(environment.QueryTheme{}) if err != nil || !handled { @@ -1876,6 +1898,7 @@ func (s *Service) GetTheme() *Theme { } // GetSystemTheme returns the current system theme preference. +// Use: theme := svc.GetSystemTheme() func (s *Service) GetSystemTheme() string { result, handled, err := s.Core().QUERY(environment.QueryTheme{}) if err != nil || !handled { @@ -1892,6 +1915,7 @@ func (s *Service) GetSystemTheme() string { } // SetTheme overrides the application theme. +// Use: _ = svc.SetTheme(true) func (s *Service) SetTheme(isDark bool) error { _, handled, err := s.Core().PERFORM(environment.TaskSetTheme{IsDark: isDark}) if err != nil { @@ -1906,6 +1930,7 @@ func (s *Service) SetTheme(isDark bool) error { // --- Tray --- // SetTrayIcon sets the tray icon image. +// Use: _ = svc.SetTrayIcon(iconBytes) func (s *Service) SetTrayIcon(data []byte) error { _, handled, err := s.Core().PERFORM(systray.TaskSetTrayIcon{Data: data}) if err != nil { @@ -1918,6 +1943,7 @@ func (s *Service) SetTrayIcon(data []byte) error { } // SetTrayTooltip updates the tray tooltip. +// Use: _ = svc.SetTrayTooltip("Core is ready") func (s *Service) SetTrayTooltip(tooltip string) error { _, handled, err := s.Core().PERFORM(systray.TaskSetTooltip{Tooltip: tooltip}) if err != nil { @@ -1930,6 +1956,7 @@ func (s *Service) SetTrayTooltip(tooltip string) error { } // SetTrayLabel updates the tray label. +// Use: _ = svc.SetTrayLabel("Core") func (s *Service) SetTrayLabel(label string) error { _, handled, err := s.Core().PERFORM(systray.TaskSetLabel{Label: label}) if err != nil { @@ -1942,6 +1969,7 @@ func (s *Service) SetTrayLabel(label string) error { } // SetTrayMenu replaces the tray menu items. +// Use: _ = svc.SetTrayMenu([]systray.TrayMenuItem{{Label: "Quit", ActionID: "quit"}}) func (s *Service) SetTrayMenu(items []systray.TrayMenuItem) error { _, handled, err := s.Core().PERFORM(systray.TaskSetTrayMenu{Items: items}) if err != nil { @@ -1954,6 +1982,7 @@ func (s *Service) SetTrayMenu(items []systray.TrayMenuItem) error { } // GetTrayInfo returns current tray state information. +// Use: info := svc.GetTrayInfo() func (s *Service) GetTrayInfo() map[string]any { svc, err := core.ServiceFor[*systray.Service](s.Core(), "systray") if err != nil || svc == nil || svc.Manager() == nil { @@ -1963,6 +1992,7 @@ func (s *Service) GetTrayInfo() map[string]any { } // ShowTrayMessage shows a tray message or notification. +// Use: _ = svc.ShowTrayMessage("Core", "Sync complete") func (s *Service) ShowTrayMessage(title, message string) error { _, handled, err := s.Core().PERFORM(systray.TaskShowMessage{Title: title, Message: message}) if err != nil { @@ -1975,11 +2005,13 @@ func (s *Service) ShowTrayMessage(title, message string) error { } // GetEventManager returns the event manager for WebSocket event subscriptions. +// Use: events := svc.GetEventManager() func (s *Service) GetEventManager() *WSEventManager { return s.events } // GetEventInfo returns a summary of the live WebSocket event server state. +// Use: info := svc.GetEventInfo() func (s *Service) GetEventInfo() EventServerInfo { if s.events == nil { return EventServerInfo{}