[v3] Add option for showing the toolbar in fullscreen mode on macOS (#3282)

* Add option for showing the toolbar in fullscreen mode on macOS * Add an example demonstrating the ShowToolbarWhenFullscreen option * Update docs * Add changelog entry * Run go mod tidy
2026-03-14 14:45:49 +01:00 · 2024-03-02 10:10:25 +01:00 · 2024-03-02 10:10:25 +01:00 · 7e687750b2
commit 7e687750b2
parent 0c3025d695
9 changed files with 113 additions and 19 deletions
--- a/mkdocs-website/docs/en/API/fullapi.md
+++ b/mkdocs-website/docs/en/API/fullapi.md
@ -1760,6 +1760,8 @@ type MacTitleBar struct {
    UseToolbar bool
    // HideToolbarSeparator will hide the toolbar separator
    HideToolbarSeparator bool
+    // ShowToolbarWhenFullscreen will keep the toolbar visible when the window is in fullscreen mode
+	ShowToolbarWhenFullscreen bool
    // ToolbarStyle is the style of toolbar to use
    ToolbarStyle MacToolbarStyle
 }
--- a/mkdocs-website/docs/en/changelog.md
+++ b/mkdocs-website/docs/en/changelog.md
@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 - [darwin] add Event ApplicationShouldHandleReopen to be able to handle dock icon click by @5aaee9 in [#2991](https://github.com/wailsapp/wails/pull/2991)
 - [darwin] add getPrimaryScreen/getScreens to impl by @tmclane in [#2618](https://github.com/wailsapp/wails/pull/2618)
+- [darwin] add option for showing the toolbar in fullscreen mode on macOS by [@fbbdev](https://github.com/fbbdev) in [#3282](https://github.com/wailsapp/wails/pull/3282)
 - [linux] add onKeyPress logic to convert linux keypress into an accelerator @[Atterpac](https://github.com/Atterpac) in[#3022](https://github.com/wailsapp/wails/pull/3022])
 - [linux] add task `run:linux` by [@marcus-crane](https://github.com/marcus-crane) in [#3146](https://github.com/wailsapp/wails/pull/3146)
 - export `SetIcon` method by  @almas1992 in [PR](https://github.com/wailsapp/wails/pull/3147)
--- a/v3/examples/show-macos-toolbar/README.md
+++ b/v3/examples/show-macos-toolbar/README.md
@ -0,0 +1,20 @@
+# Show macOS Toolbar Example
+
+This example is a demonstration of the macOS option `ShowToolbarWhenFullscreen`, which keeps
+the system toolbar visible when in fullscreen mode.
+
+## Running the example
+
+To run the example (on macOS), simply run the following command:
+
+```bash
+go run .
+```
+
+# Status
+
+| Platform | Status  |
+|----------|---------|
+| Mac      | Working |
+| Windows  | N/A     |
+| Linux    | N/A     |
--- a/v3/examples/show-macos-toolbar/main.go
+++ b/v3/examples/show-macos-toolbar/main.go
@ -0,0 +1,51 @@
+package main
+
+import (
+	_ "embed"
+	"log"
+
+	"github.com/wailsapp/wails/v3/pkg/application"
+)
+
+func main() {
+	app := application.New(application.Options{
+		Name:        "Show macOS Toolbar",
+		Description: "A demo of the ShowToolbarWhenFullscreen option",
+		Mac: application.MacOptions{
+			ApplicationShouldTerminateAfterLastWindowClosed: true,
+		},
+	})
+
+	// Create window
+	app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
+		Title: "Toolbar hidden (default behaviour)",
+		HTML:  "<html><body><h1>Switch this window to fullscreen: the toolbar will be hidden</h1></body></html>",
+		CSS:   `body { background-color: blue; color: white; height: 100vh; display: flex; justify-content: center; align-items: center; }`,
+		Mac: application.MacWindow{
+			TitleBar: application.MacTitleBar{
+				UseToolbar:           true,
+				HideToolbarSeparator: true,
+			},
+		},
+	})
+
+	// Create window
+	app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
+		Title: "Toolbar visible",
+		HTML:  "<html><body><h1>Switch this window to fullscreen: the toolbar will stay visible</h1></body></html>",
+		CSS:   `body { background-color: red; color: white; height: 100vh; display: flex; justify-content: center; align-items: center; }`,
+		Mac: application.MacWindow{
+			TitleBar: application.MacTitleBar{
+				UseToolbar:                true,
+				HideToolbarSeparator:      true,
+				ShowToolbarWhenFullscreen: true,
+			},
+		},
+	})
+
+	err := app.Run()
+
+	if err != nil {
+		log.Fatal(err)
+	}
+}
--- a/v3/go.mod
+++ b/v3/go.mod
@ -32,7 +32,6 @@ require (
 	github.com/pkg/browser v0.0.0-20210911075715-681adbf594b8
 	github.com/pkg/errors v0.9.1
 	github.com/pterm/pterm v0.12.51
-	github.com/rjeczalik/notify v0.9.3
 	github.com/samber/lo v1.38.1
 	github.com/tc-hib/winres v0.1.6
 	github.com/wailsapp/go-webview2 v1.0.9
@ -84,6 +83,7 @@ require (
 	github.com/radovskyb/watcher v1.0.7 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.4 // indirect
+	github.com/rjeczalik/notify v0.9.3 // indirect
 	github.com/sajari/fuzzy v1.0.0 // indirect
 	github.com/sergi/go-diff v1.2.0 // indirect
 	github.com/skeema/knownhosts v1.2.1 // indirect
--- a/v3/pkg/application/options_mac.go
+++ b/v3/pkg/application/options_mac.go
@ -1,7 +1,9 @@
 package application

-import "github.com/wailsapp/wails/v3/pkg/events"
-import "github.com/leaanthony/u"
+import (
+	"github.com/leaanthony/u"
+	"github.com/wailsapp/wails/v3/pkg/events"
+)

 // MacBackdrop is the backdrop type for macOS
 type MacBackdrop int
@ -87,6 +89,8 @@ type MacTitleBar struct {
 	UseToolbar bool
 	// HideToolbarSeparator will hide the toolbar separator
 	HideToolbarSeparator bool
+	// ShowToolbarWhenFullscreen will keep the toolbar visible when the window is in fullscreen mode
+	ShowToolbarWhenFullscreen bool
 	// ToolbarStyle is the style of toolbar to use
 	ToolbarStyle MacToolbarStyle
 }
--- a/v3/pkg/application/webview_window_darwin.go
+++ b/v3/pkg/application/webview_window_darwin.go
@ -443,18 +443,12 @@ void windowSetHideTitle(void* nsWindow, bool hideTitle) {
 }

 // Set Window use toolbar
-void windowSetUseToolbar(void* nsWindow, bool useToolbar, int toolbarStyle) {
+void windowSetUseToolbar(void* nsWindow, bool useToolbar) {
 	WebviewWindow* window = (WebviewWindow*)nsWindow;
 	if( useToolbar ) {
 		NSToolbar *toolbar = [[NSToolbar alloc] initWithIdentifier:@"wails.toolbar"];
 		[toolbar autorelease];
 		[window setToolbar:toolbar];
-
-		// If macos 11 or higher, set toolbar style
-		if (@available(macOS 11.0, *)) {
-			[window setToolbarStyle:toolbarStyle];
-		}
-
 	} else {
 		[window setToolbar:nil];
 	}
@ -462,11 +456,15 @@ void windowSetUseToolbar(void* nsWindow, bool useToolbar, int toolbarStyle) {

 // Set window toolbar style
 void windowSetToolbarStyle(void* nsWindow, int style) {
+	WebviewWindow* window = (WebviewWindow*)nsWindow;
 	// use @available to check if the function is available
 	// if not, return
 	if (@available(macOS 11.0, *)) {
-		NSToolbar* toolbar = [(WebviewWindow*)nsWindow toolbar];
-		[toolbar setShowsBaselineSeparator:style];
+		NSToolbar* toolbar = [window toolbar];
+		if ( toolbar == nil ) {
+			return;
+		}
+		[window setToolbarStyle:style];
 	}
 }

@ -479,6 +477,15 @@ void windowSetHideToolbarSeparator(void* nsWindow, bool hideSeparator) {
 	[toolbar setShowsBaselineSeparator:!hideSeparator];
 }

+// Configure the toolbar auto-hide feature
+void windowSetShowToolbarWhenFullscreen(void* window, bool setting) {
+	WebviewWindow* nsWindow = (WebviewWindow*)window;
+	// Get delegate
+	WebviewWindowDelegate* delegate = (WebviewWindowDelegate*)[nsWindow delegate];
+	// Set height
+	delegate.showToolbarWhenFullscreen = setting;
+}
+
 // Set Window appearance type
 void windowSetAppearanceTypeByName(void* nsWindow, const char *appearanceName) {
 	// set window appearance type by name
@ -745,11 +752,12 @@ void windowFocus(void *window) {
 */
 import "C"
 import (
-	"github.com/wailsapp/wails/v3/internal/assetserver"
-	"github.com/wailsapp/wails/v3/internal/runtime"
 	"sync"
 	"unsafe"

+	"github.com/wailsapp/wails/v3/internal/assetserver"
+	"github.com/wailsapp/wails/v3/internal/runtime"
+
 	"github.com/wailsapp/wails/v3/pkg/events"
 )

@ -968,7 +976,6 @@ func (w *macosWebviewWindow) setEnabled(enabled bool) {
 }

 func (w *macosWebviewWindow) execJS(js string) {
-
 	InvokeAsync(func() {
 		if globalApplication.performingShutdown {
 			return
@ -1146,11 +1153,12 @@ func (w *macosWebviewWindow) run() {
 			C.windowSetHideTitleBar(w.nsWindow, C.bool(titleBarOptions.Hide))
 			C.windowSetHideTitle(w.nsWindow, C.bool(titleBarOptions.HideTitle))
 			C.windowSetFullSizeContent(w.nsWindow, C.bool(titleBarOptions.FullSizeContent))
-			if titleBarOptions.UseToolbar {
-				C.windowSetUseToolbar(w.nsWindow, C.bool(titleBarOptions.UseToolbar), C.int(titleBarOptions.ToolbarStyle))
-			}
+			C.windowSetUseToolbar(w.nsWindow, C.bool(titleBarOptions.UseToolbar))
+			C.windowSetToolbarStyle(w.nsWindow, C.int(titleBarOptions.ToolbarStyle))
+			C.windowSetShowToolbarWhenFullscreen(w.nsWindow, C.bool(titleBarOptions.ShowToolbarWhenFullscreen))
 			C.windowSetHideToolbarSeparator(w.nsWindow, C.bool(titleBarOptions.HideToolbarSeparator))
 		}
+
 		if macOptions.Appearance != "" {
 			C.windowSetAppearanceTypeByName(w.nsWindow, C.CString(string(macOptions.Appearance)))
 		}
@ -1186,7 +1194,7 @@ func (w *macosWebviewWindow) run() {
 				if options.CSS != "" {
 					C.windowInjectCSS(w.nsWindow, C.CString(options.CSS))
 				}
-				if options.Hidden == false {
+				if !options.Hidden {
 					C.windowShow(w.nsWindow)
 					w.setHasShadow(!options.Mac.DisableShadow)
 				} else {
--- a/v3/pkg/application/webview_window_darwin.h
+++ b/v3/pkg/application/webview_window_darwin.h
@ -23,6 +23,7 @@
@property unsigned int windowId;
@property (retain) NSEvent* leftMouseEvent;
@property unsigned int invisibleTitleBarHeight;
+@property BOOL showToolbarWhenFullscreen;
@property NSWindowStyleMask previousStyleMask; // Used to restore the window style mask when using frameless

 - (void)handleLeftMouseUp:(NSWindow *)window;
--- a/v3/pkg/application/webview_window_darwin.m
+++ b/v3/pkg/application/webview_window_darwin.m
@ -241,6 +241,13 @@ extern bool hasListeners(unsigned int);
        }
    }
 }
+- (NSApplicationPresentationOptions)window:(NSWindow *)window willUseFullScreenPresentationOptions:(NSApplicationPresentationOptions)proposedOptions {
+    if (self.showToolbarWhenFullscreen) {
+        return proposedOptions;
+    } else {
+        return proposedOptions | NSApplicationPresentationAutoHideToolbar;
+    }
+}
 // GENERATED EVENTS START
 - (void)windowDidBecomeKey:(NSNotification *)notification {
    if( hasListeners(EventWindowDidBecomeKey) ) {