Honor title-bar double-click preferences in custom chrome (#48)

Hidden macOS title bars restore the background double-click action.

Author: lijy91

src/capi/window_c.cpp

@@ -1390,6 +1390,19 @@ bool native_window_is_system_menu_supported(void) {
   }
 }
 
+bool native_window_perform_title_bar_double_click(native_window_t window) {
+  auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
+  if (!self) {
+    return false;
+  }
+  try {
+    return self->PerformTitleBarDoubleClick();
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_perform_title_bar_double_click");
+    return false;
+  }
+}
+
 void native_window_start_dragging(native_window_t window) {
   auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
   if (!self) {

src/capi/window_c.h

@@ -426,6 +426,9 @@ bool native_window_show_system_menu(native_window_t window, native_point_t posit
 FFI_PLUGIN_EXPORT
 bool native_window_is_system_menu_supported(void);
 
+FFI_PLUGIN_EXPORT
+bool native_window_perform_title_bar_double_click(native_window_t window);
+
 FFI_PLUGIN_EXPORT
 void native_window_start_dragging(native_window_t window);
 

src/platform/android/window_android.cpp

@@ -454,6 +454,10 @@ bool Window::IsSystemMenuSupported() {
   return false;
 }
 
+bool Window::PerformTitleBarDoubleClick() {
+  return false;
+}
+
 void Window::StartDragging() {
   ALOGW("StartDragging not supported on Android");
 }

src/platform/ios/window_ios.mm

@@ -497,6 +497,10 @@
   return false;
 }
 
+bool Window::PerformTitleBarDoubleClick() {
+  return false;
+}
+
 void Window::StartDragging() {
   // Not applicable to iOS
 }

src/platform/linux/window_linux.cpp

@@ -1919,6 +1919,15 @@ bool Window::IsSystemMenuSupported() {
   return false;
 }
 
+bool Window::PerformTitleBarDoubleClick() {
+  GdkWindow* window = pimpl_->gdk_window_;
+  if (!window || gdk_window_is_destroyed(window) || IsFullScreen() || IsMinimized() ||
+      !IsMaximizable()) return false;
+  if (IsMaximized()) Unmaximize();
+  else Maximize();
+  return true;
+}
+
 void Window::StartDragging() {
   if (!pimpl_->gdk_window_) {
     return;

src/platform/macos/window_macos.mm

@@ -184,6 +184,91 @@ static void NativeApiUpdateWindowMovable(NSWindow* window) {
   [window setMovable:requested && !NativeApiWindowIsTitleBarHidden(window)];
 }
 
+static bool NativeApiPerformTitleBarDoubleClick(NSWindow* window) {
+  if (!window) return false;
+  NSString* action = [NSUserDefaults.standardUserDefaults stringForKey:@"AppleActionOnDoubleClick"];
+  if ([action isEqualToString:@"None"]) return true;
+  if ((window.styleMask & NSWindowStyleMaskFullScreen) || window.isMiniaturized) return false;
+  if ([action isEqualToString:@"Minimize"]) {
+    if (!(window.styleMask & NSWindowStyleMaskMiniaturizable)) return false;
+    [window miniaturize:nil];
+    return true;
+  }
+  if ([action isEqualToString:@"Fill"]) {
+    if (!(window.styleMask & NSWindowStyleMaskResizable)) return false;
+    // AppKit exposes no public Fill action. Ask for the native action only
+    // when this OS provides it, rather than substituting standard-state zoom.
+    SEL selector = NSSelectorFromString(@"_zoomFill:");
+    if (![window respondsToSelector:selector]) return false;
+    using Action = void (*)(id, SEL, id);
+    reinterpret_cast<Action>([window methodForSelector:selector])(window, selector, nil);
+    return true;
+  }
+  if (!action || [action isEqualToString:@"Maximize"] || [action isEqualToString:@"Zoom"]) {
+    if (!(window.styleMask & NSWindowStyleMaskResizable)) return false;
+    // Use the action itself so custom chrome does not require a native zoom box.
+    [window zoom:nil];
+    return true;
+  }
+  return false;
+}
+
+// A plain hidden window still has a conventional title-bar band. Only empty
+// backgrounds inherit its double-click action: controls and views that handle
+// mouse presses/releases own their gestures (Flutter uses the explicit action).
+static bool NativeApiIsEmptyTitleBarBackground(NSWindow* window, NSEvent* event) {
+  if (!NativeApiWindowIsTitleBarHidden(window) || event.window != window ||
+      event.type != NSEventTypeLeftMouseUp || event.clickCount != 2) return false;
+  NSView* content = window.contentView;
+  if (!content) return false;
+  const NSWindowStyleMask mask = (window.styleMask | NSWindowStyleMaskTitled) &
+                                 ~NSWindowStyleMaskFullSizeContentView;
+  const NSRect frame = NSMakeRect(0, 0, window.frame.size.width, window.frame.size.height);
+  const CGFloat height = NSHeight(frame) - NSHeight([NSWindow contentRectForFrameRect:frame styleMask:mask]);
+  const NSPoint point = [content convertPoint:event.locationInWindow fromView:nil];
+  const NSRect band = NSMakeRect(NSMinX(content.bounds),
+      content.isFlipped ? NSMinY(content.bounds) : NSMaxY(content.bounds) - height,
+      NSWidth(content.bounds), height);
+  if (!NSPointInRect(point, band)) return false;
+  const NSPoint hit_point = content.superview
+      ? [content.superview convertPoint:event.locationInWindow fromView:nil] : event.locationInWindow;
+  NSView* target = [content hitTest:hit_point];
+  if (!target) return false;
+  const IMP default_down = class_getMethodImplementation([NSView class], @selector(mouseDown:));
+  const IMP default_up = class_getMethodImplementation([NSView class], @selector(mouseUp:));
+  for (NSView* view = target; view; view = view.superview) {
+    if ([view isKindOfClass:[NSControl class]] ||
+        class_getMethodImplementation(object_getClass(view), @selector(mouseDown:)) != default_down ||
+        class_getMethodImplementation(object_getClass(view), @selector(mouseUp:)) != default_up)
+      return false;
+    if (view == content) return true;
+  }
+  return false;
+}
+
+// Preserve the live runtime class (including AppKit's KVO bookkeeping). The
+// associated hidden flag makes this override inert on other class instances.
+static void NativeApiInstallTitleBarDoubleClick(NSWindow* window) {
+  static const void* installed_key = &installed_key;
+  Class cls = object_getClass(window);
+  if (objc_getAssociatedObject(cls, installed_key)) return;
+  SEL selector = @selector(sendEvent:);
+  Method method = class_getInstanceMethod(cls, selector);
+  auto original = reinterpret_cast<void (*)(id, SEL, NSEvent*)>(method_getImplementation(method));
+  // A host with its own window-level event dispatch owns the gesture as well.
+  const IMP implementation = method_getImplementation(method);
+  if (implementation != class_getMethodImplementation([NSWindow class], selector) &&
+      implementation != class_getMethodImplementation([NSPanel class], selector)) return;
+  IMP replacement = imp_implementationWithBlock(^(NSWindow* instance, NSEvent* event) {
+    if (NativeApiIsEmptyTitleBarBackground(instance, event) &&
+        NativeApiPerformTitleBarDoubleClick(instance)) return;
+    original(instance, selector, event);
+  });
+  if (!class_addMethod(cls, selector, replacement, method_getTypeEncoding(method)))
+    class_replaceMethod(cls, selector, replacement, method_getTypeEncoding(method));
+  objc_setAssociatedObject(cls, installed_key, @YES, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+}
+
 static BOOL NativeApiWindowIsFocusable(NSWindow* window) {
   NSNumber* value = objc_getAssociatedObject(window, kWindowFocusableKey);
   return value ? [value boolValue] : YES;
@@ -258,6 +343,7 @@ static void NativeApiUpdateWindowClass(NSWindow* window, bool non_activating) {
     // helper window away as soon as the user clicks into another app.
     panel.hidesOnDeactivate = NO;
     panel.becomesKeyOnlyIfNeeded = NO;
+    if (NativeApiWindowIsTitleBarHidden(window)) NativeApiInstallTitleBarDoubleClick(window);
     return;
   }
   if (NativeApiWindowIsNonActivating(window)) {
@@ -268,6 +354,7 @@ static void NativeApiUpdateWindowClass(NSWindow* window, bool non_activating) {
       (NativeApiWindowIsTitleBarHidden(window) && objc_getAssociatedObject(window, kWindowShapeFrameKey))) {
     NativeApiInstallFocusOverride(window);
   }
+  if (NativeApiWindowIsTitleBarHidden(window)) NativeApiInstallTitleBarDoubleClick(window);
 }
 
 #include "window_shadow_macos.h"
@@ -1072,6 +1159,10 @@ static void NativeApiSendMouseUp(NSWindow* window, NSEvent* mouse_up) {
   return false;
 }
 
+bool Window::PerformTitleBarDoubleClick() {
+  return NativeApiPerformTitleBarDoubleClick(pimpl_->ns_window_);
+}
+
 void Window::StartDragging() {
   NSWindow* window = pimpl_->ns_window_;
   NSEvent* event = window.currentEvent;

src/platform/ohos/window_ohos.cpp

@@ -438,6 +438,10 @@ bool Window::IsSystemMenuSupported() {
   return false;
 }
 
+bool Window::PerformTitleBarDoubleClick() {
+  return false;
+}
+
 void Window::StartDragging() {
   // StartDragging not supported on OpenHarmony
 }

src/platform/windows/window_windows.cpp

@@ -2194,6 +2194,14 @@ bool Window::IsSystemMenuSupported() {
   return true;
 }
 
+bool Window::PerformTitleBarDoubleClick() {
+  HWND hwnd = pimpl_->hwnd_;
+  if (!hwnd || !IsWindow(hwnd) || IsFullScreen() || IsIconic(hwnd) || !IsMaximizable())
+    return false;
+  SendMessageW(hwnd, WM_SYSCOMMAND, IsZoomed(hwnd) ? SC_RESTORE : SC_MAXIMIZE, 0);
+  return true;
+}
+
 void Window::StartDragging() {
   if (pimpl_->hwnd_) {
     StartSystemFrameDrag(pimpl_->hwnd_, HTCAPTION);

src/window.h

@@ -49,7 +49,10 @@ enum class TitleBarStyle {
    *
    * The content owns the area where the title bar was: dragging there does
    * not move the window. Move it from custom chrome with
-   * Window::StartDragging() (or a WindowDragSession).
+   * Window::StartDragging() (or a WindowDragSession). Handle a double-click
+   * in that custom chrome with Window::PerformTitleBarDoubleClick(). On macOS,
+   * empty backgrounds in the original title-bar band automatically perform that
+   * action; controls, custom mouse handlers and host window dispatchers keep it.
    * - macOS: the content extends under a title bar that is transparent and
    *   empty; the window buttons are hidden. The system is kept from moving
    *   the window, even while IsMovable() is true. To keep the buttons over
@@ -1391,6 +1394,35 @@ class Window : public NativeObjectProvider, public std::enable_shared_from_this<
    */
   static bool IsSystemMenuSupported();
 
+  /**
+   * @brief Performs the double-click action for a custom title bar.
+   * @return true if an action was requested, or the macOS preference explicitly
+   *         disables it; false if unsupported, unavailable or rejected.
+   *
+   * Call from your custom title bar's double-click handler. Hidden title bars
+   * leave hit testing to the application. On macOS, empty backgrounds within the
+   * original title-bar band also invoke this action automatically; controls and
+   * custom mouse handlers and host window event dispatchers are excluded.
+   * The macOS preference is read on each call, so changes take effect immediately.
+   * A successful request does not guarantee the window manager applies it.
+   *
+   * @note Platform availability:
+   * - macOS: ✅ Uses the user's AppleActionOnDoubleClick preference: Maximize
+   *   (or unset) zooms, Minimize miniaturizes, None deliberately does nothing.
+   *   Legacy Zoom is also accepted. Fill requests the OS native Fill action when
+   *   available; this currently requires a runtime-checked private AppKit action.
+   *   Unsupported or unknown actions return false.
+   * - Windows: ✅ Toggles maximize/restore using the native system command.
+   * - Linux: ⚠️ Requests maximize/unmaximize; the window manager may ignore it.
+   * - Android: ❌ Not applicable - Always returns false
+   * - iOS: ❌ Not applicable - Always returns false
+   * - OpenHarmony: ❌ Not applicable - Always returns false
+   *
+   * Full-screen and minimized windows reject state changes. Disabled maximize or
+   * minimize controls reject their corresponding action.
+   */
+  bool PerformTitleBarDoubleClick();
+
   /**
    * @brief Initiates a user drag operation for moving the window.
    *

tests/CMakeLists.txt

@@ -35,6 +35,12 @@ add_test(NAME window_shadow_blur_test COMMAND window_shadow_blur_test)
 
 if(APPLE AND NOT CMAKE_SYSTEM_NAME STREQUAL "iOS")
   enable_language(OBJCXX)
+  # Explicit guarded GUI integration; no automatic CTest registration.
+  add_executable(window_title_bar_double_click_gui_macos_test window_title_bar_double_click_gui_macos_test.mm)
+  target_link_libraries(window_title_bar_double_click_gui_macos_test PRIVATE nativeapi)
+  add_executable(window_title_bar_double_click_macos_test window_title_bar_double_click_macos_test.mm)
+  target_link_libraries(window_title_bar_double_click_macos_test PRIVATE nativeapi)
+  add_test(NAME window_title_bar_double_click_macos_test COMMAND window_title_bar_double_click_macos_test)
   add_executable(window_mouse_forwarding_macos_test window_mouse_forwarding_macos_test.mm)
   target_link_libraries(window_mouse_forwarding_macos_test PRIVATE nativeapi)
   add_test(NAME window_mouse_forwarding_macos_test COMMAND window_mouse_forwarding_macos_test)
@@ -127,6 +133,8 @@ if(WIN32 AND NATIVEAPI_ENABLE_WINUI3)
 endif()
 
 if(WIN32)
+  add_executable(window_title_bar_double_click_windows_test window_title_bar_double_click_windows_test.cpp)
+  target_link_libraries(window_title_bar_double_click_windows_test PRIVATE nativeapi)
   add_executable(window_mouse_forwarding_windows_test window_mouse_forwarding_windows_test.cpp)
   target_link_libraries(window_mouse_forwarding_windows_test PRIVATE nativeapi)
   add_test(NAME window_mouse_forwarding_windows_test COMMAND window_mouse_forwarding_windows_test)
@@ -169,6 +177,8 @@ endif()
 # Explicit desktop integration test; requires a running window manager.
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
   # Inspect real server input regions without injecting input into the desktop.
+  add_executable(window_title_bar_double_click_linux_test window_title_bar_double_click_linux_test.cpp)
+  target_link_libraries(window_title_bar_double_click_linux_test PRIVATE nativeapi)
   add_executable(window_mouse_forwarding_linux_test window_mouse_forwarding_linux_test.cpp)
   target_link_libraries(window_mouse_forwarding_linux_test PRIVATE nativeapi)
   add_test(NAME window_mouse_forwarding_linux_test COMMAND window_mouse_forwarding_linux_test)