Report whether a window can be seen (#74)

Window::GetOcclusionState() returns WindowOcclusionState Unknown, Visible
or Occluded, IsOcclusionStateSupported() says whether anything but Unknown
is reported, and WindowOcclusionChangedEvent carries each change after a
window's first reading, on the Window and on WindowManager.

- macOS: NSWindow.occlusionState and its change notification.
- Windows: hidden, minimized and cloaked windows are occluded; otherwise the
  opaque windows above it in the Z order, clipped to the screens, must cover
  it entirely (click-through and translucent layered windows do not).
  System-wide WinEvents (show/hide/reorder, location, cloak, minimize,
  foreground) arm a 100 ms timer that recomputes the process's windows, so
  listeners never run inside another window's message handling.
- Linux: hidden and minimized windows are occluded; a shown window is
  Unknown, since X11 visibility is meaningless under a compositing manager
  (GDK reports one even on Xvfb + Openbox) and Wayland does not tell.
- Android, iOS, OpenHarmony: Unknown.

tests/window_occlusion_test shows real windows, so it is run by hand.
window_property_changed_test gets a longer CTest timeout: GTK start-up and
the keep-above probe take up to 20 s on WSL.

Author: lijy91

src/capi/window_c.cpp

@@ -193,6 +193,28 @@ bool native_window_is_visible(native_window_t window) {
   }
 }
 
+native_window_occlusion_state_t native_window_get_occlusion_state(native_window_t window) {
+  auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
+  if (!self) {
+    return (native_window_occlusion_state_t)NATIVE_WINDOW_OCCLUSION_STATE_UNKNOWN;
+  }
+  try {
+    return to_c_window_occlusion_state(self->GetOcclusionState());
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_get_occlusion_state");
+    return (native_window_occlusion_state_t)NATIVE_WINDOW_OCCLUSION_STATE_UNKNOWN;
+  }
+}
+
+bool native_window_is_occlusion_state_supported(void) {
+  try {
+    return nativeapi::Window::IsOcclusionStateSupported();
+  } catch (...) {
+    fprintf(stderr, "[nativeapi] %s: unexpected exception\n", "native_window_is_occlusion_state_supported");
+    return false;
+  }
+}
+
 void native_window_maximize(native_window_t window) {
   auto self = nativeapi::HandleTable::GetInstance().Resolve<nativeapi::Window>(window);
   if (!self) {
@@ -1630,6 +1652,11 @@ bool to_c_window_event(const nativeapi::WindowEvent& event, native_window_event_
     out->data.property_changed.property = to_c_window_property(typed->GetProperty());
     return true;
   }
+  if (const auto* typed = dynamic_cast<const nativeapi::WindowOcclusionChangedEvent*>(&event)) {
+    out->type = NATIVE_WINDOW_EVENT_TYPE_OCCLUSION_CHANGED;
+    out->data.occlusion_changed.occlusion_state = to_c_window_occlusion_state(typed->GetOcclusionState());
+    return true;
+  }
   return false;
 }
 

src/capi/window_c.h

@@ -57,6 +57,12 @@ typedef enum {
   NATIVE_WINDOW_PROPERTY_TITLE_BAR_STYLE = 10,
 } native_window_property_t;
 
+typedef enum {
+  NATIVE_WINDOW_OCCLUSION_STATE_UNKNOWN = 0,
+  NATIVE_WINDOW_OCCLUSION_STATE_VISIBLE = 1,
+  NATIVE_WINDOW_OCCLUSION_STATE_OCCLUDED = 2,
+} native_window_occlusion_state_t;
+
 typedef enum {
   NATIVE_VISUAL_EFFECT_NONE = 0,
   NATIVE_VISUAL_EFFECT_BLUR = 1,
@@ -111,6 +117,7 @@ typedef enum {
   NATIVE_WINDOW_EVENT_TYPE_EXITED_FULL_SCREEN = 10,
   NATIVE_WINDOW_EVENT_TYPE_CLOSE_REQUESTED = 11,
   NATIVE_WINDOW_EVENT_TYPE_PROPERTY_CHANGED = 12,
+  NATIVE_WINDOW_EVENT_TYPE_OCCLUSION_CHANGED = 13,
 } native_window_event_type_t;
 
 /// One WindowEvent, tagged by its concrete type.
@@ -133,6 +140,9 @@ typedef struct {
     struct {
       native_window_property_t property;
     } property_changed;
+    struct {
+      native_window_occlusion_state_t occlusion_state;
+    } occlusion_changed;
   } data;
 } native_window_event_t;
 
@@ -181,6 +191,12 @@ void native_window_hide(native_window_t window);
 FFI_PLUGIN_EXPORT
 bool native_window_is_visible(native_window_t window);
 
+FFI_PLUGIN_EXPORT
+native_window_occlusion_state_t native_window_get_occlusion_state(native_window_t window);
+
+FFI_PLUGIN_EXPORT
+bool native_window_is_occlusion_state_supported(void);
+
 FFI_PLUGIN_EXPORT
 void native_window_maximize(native_window_t window);
 
@@ -528,6 +544,8 @@ inline native_window_corner_preference_t to_c_window_corner_preference(nativeapi
 inline nativeapi::WindowCornerPreference to_cpp_window_corner_preference(native_window_corner_preference_t value);
 inline native_window_property_t to_c_window_property(nativeapi::WindowProperty value);
 inline nativeapi::WindowProperty to_cpp_window_property(native_window_property_t value);
+inline native_window_occlusion_state_t to_c_window_occlusion_state(nativeapi::WindowOcclusionState value);
+inline nativeapi::WindowOcclusionState to_cpp_window_occlusion_state(native_window_occlusion_state_t value);
 inline native_visual_effect_t to_c_visual_effect(nativeapi::VisualEffect value);
 inline nativeapi::VisualEffect to_cpp_visual_effect(native_visual_effect_t value);
 inline native_resize_edge_t to_c_resize_edge(nativeapi::ResizeEdge value);
@@ -643,6 +661,32 @@ inline nativeapi::WindowProperty to_cpp_window_property(native_window_property_t
   }
 }
 
+inline native_window_occlusion_state_t to_c_window_occlusion_state(nativeapi::WindowOcclusionState value) {
+  switch (value) {
+    case nativeapi::WindowOcclusionState::Unknown:
+      return NATIVE_WINDOW_OCCLUSION_STATE_UNKNOWN;
+    case nativeapi::WindowOcclusionState::Visible:
+      return NATIVE_WINDOW_OCCLUSION_STATE_VISIBLE;
+    case nativeapi::WindowOcclusionState::Occluded:
+      return NATIVE_WINDOW_OCCLUSION_STATE_OCCLUDED;
+    default:
+      return NATIVE_WINDOW_OCCLUSION_STATE_UNKNOWN;
+  }
+}
+
+inline nativeapi::WindowOcclusionState to_cpp_window_occlusion_state(native_window_occlusion_state_t value) {
+  switch (value) {
+    case NATIVE_WINDOW_OCCLUSION_STATE_UNKNOWN:
+      return nativeapi::WindowOcclusionState::Unknown;
+    case NATIVE_WINDOW_OCCLUSION_STATE_VISIBLE:
+      return nativeapi::WindowOcclusionState::Visible;
+    case NATIVE_WINDOW_OCCLUSION_STATE_OCCLUDED:
+      return nativeapi::WindowOcclusionState::Occluded;
+    default:
+      return static_cast<nativeapi::WindowOcclusionState>(value);
+  }
+}
+
 inline native_visual_effect_t to_c_visual_effect(nativeapi::VisualEffect value) {
   switch (value) {
     case nativeapi::VisualEffect::None:

src/platform/android/window_android.cpp

@@ -97,6 +97,14 @@ bool Window::IsVisible() const {
   return pimpl_->native_window_ != nullptr;
 }
 
+WindowOcclusionState Window::GetOcclusionState() const {
+  return WindowOcclusionState::Unknown;
+}
+
+bool Window::IsOcclusionStateSupported() {
+  return false;
+}
+
 void Window::Maximize() {
   // Maximize is not applicable to Android Activities
   ALOGW("Maximize not supported on Android");

src/platform/ios/window_ios.mm

@@ -88,6 +88,14 @@
   return pimpl_->ui_window_ && !pimpl_->ui_window_.hidden;
 }
 
+WindowOcclusionState Window::GetOcclusionState() const {
+  return WindowOcclusionState::Unknown;
+}
+
+bool Window::IsOcclusionStateSupported() {
+  return false;
+}
+
 void Window::Maximize() {
   // Maximize is not applicable to iOS (fullscreen is used instead)
 }

src/platform/linux/window_linux.cpp

@@ -782,6 +782,12 @@ static void RefreshPropertiesOf(GtkWidget* widget) {
   detail::WindowPropertyDispatch::Refresh(window);
 }
 
+static void RefreshOcclusionOf(GtkWidget* widget) {
+  if (!widget || gtk_widget_in_destruction(widget)) return;
+  Window window(widget);
+  detail::WindowPropertyDispatch::RefreshOcclusion(window);
+}
+
 static bool ObserveWindowProperties(GtkWidget* widget) {
   if (!widget || !GTK_IS_WINDOW(widget) || g_object_get_data(G_OBJECT(widget), kPropertyObserverKey))
     return false;
@@ -795,9 +801,16 @@ static bool ObserveWindowProperties(GtkWidget* widget) {
                          G_CALLBACK(+[](GtkWidget* self, GdkEventWindowState* event, gpointer) {
                            if (event->changed_mask & (GDK_WINDOW_STATE_ABOVE | GDK_WINDOW_STATE_BELOW))
                              RefreshPropertiesOf(self);
+                           if (event->changed_mask &
+                               (GDK_WINDOW_STATE_ICONIFIED | GDK_WINDOW_STATE_WITHDRAWN))
+                             RefreshOcclusionOf(self);
                            return FALSE;
                          }),
                          nullptr);
+  // Occlusion: shown and hidden (minimizing is the window-state-event above).
+  auto on_mapping = +[](GtkWidget* self, gpointer) { RefreshOcclusionOf(self); };
+  g_signal_connect_after(widget, "map", G_CALLBACK(on_mapping), nullptr);
+  g_signal_connect_after(widget, "unmap", G_CALLBACK(on_mapping), nullptr);
   return true;
 }
 
@@ -843,8 +856,11 @@ Window::Window() {
 
   // Only create the instance, don't show the window
   pimpl_ = std::make_unique<Impl>(widget, gdk_window);
-  if (ObserveWindowProperties(widget))
-    detail::WindowPropertyDispatch::Refresh(*this);  // The values changes are compared with.
+  if (ObserveWindowProperties(widget)) {
+    // The values later changes are compared with.
+    detail::WindowPropertyDispatch::Refresh(*this);
+    detail::WindowPropertyDispatch::RefreshOcclusion(*this);
+  }
 }
 
 Window::Window(void* native_window) {
@@ -898,8 +914,11 @@ Window::Window(void* native_window) {
   }
 
   pimpl_ = std::make_unique<Impl>(widget, gdk_window);
-  if (ObserveWindowProperties(widget))
-    detail::WindowPropertyDispatch::Refresh(*this);  // The values changes are compared with.
+  if (ObserveWindowProperties(widget)) {
+    // The values later changes are compared with.
+    detail::WindowPropertyDispatch::Refresh(*this);
+    detail::WindowPropertyDispatch::RefreshOcclusion(*this);
+  }
 }
 
 Window::~Window() {
@@ -1194,6 +1213,25 @@ bool Window::IsVisible() const {
   return false;
 }
 
+// Whether other windows cover a shown window is not known: X11's
+// VisibilityNotify is meaningless under the compositing managers every
+// desktop runs (GDK reports one even on Xvfb with Openbox), and Wayland tells
+// clients nothing about it.
+WindowOcclusionState Window::GetOcclusionState() const {
+  GtkWidget* widget = pimpl_->widget_;
+  GdkWindow* surface = pimpl_->gdk_window_;
+  if (!widget && !surface) return WindowOcclusionState::Unknown;
+  if (!IsVisible() || (widget && !gtk_widget_get_mapped(widget)) ||
+      (surface && (gdk_window_get_state(surface) &
+                   (GDK_WINDOW_STATE_ICONIFIED | GDK_WINDOW_STATE_WITHDRAWN))))
+    return WindowOcclusionState::Occluded;
+  return WindowOcclusionState::Unknown;
+}
+
+bool Window::IsOcclusionStateSupported() {
+  return true;
+}
+
 void Window::Maximize() {
   if (pimpl_->gdk_window_) {
     AllowProgrammaticWindowControl(pimpl_->widget_, pimpl_->gdk_window_, true);

src/platform/macos/window_macos.mm

@@ -455,7 +455,9 @@ static void NativeApiObserveWindowProperties(NSWindow* window) {
   pimpl_ = std::make_unique<Impl>(id, ns_window);
   if (ns_window && !objc_getAssociatedObject(ns_window, kWindowPropertyObserverKey)) {
     NativeApiObserveWindowProperties(ns_window);
-    detail::WindowPropertyDispatch::Refresh(*this);  // The values changes are compared with.
+    // The values later changes are compared with.
+    detail::WindowPropertyDispatch::Refresh(*this);
+    detail::WindowPropertyDispatch::RefreshOcclusion(*this);
   }
 }
 
@@ -503,6 +505,17 @@ static void NativeApiObserveWindowProperties(NSWindow* window) {
   return [pimpl_->ns_window_ isVisible];
 }
 
+WindowOcclusionState Window::GetOcclusionState() const {
+  NSWindow* window = pimpl_->ns_window_;
+  if (!window) return WindowOcclusionState::Unknown;
+  return ([window occlusionState] & NSWindowOcclusionStateVisible) ? WindowOcclusionState::Visible
+                                                                   : WindowOcclusionState::Occluded;
+}
+
+bool Window::IsOcclusionStateSupported() {
+  return true;
+}
+
 void Window::Maximize() {
   if (!IsMaximized()) {
     [pimpl_->ns_window_ zoom:nil];

src/platform/macos/window_manager_macos.mm

@@ -9,6 +9,7 @@
 
 #include "../../window.h"
 #include "../../window_manager.h"
+#include "../../window_property_dispatch.h"
 #include "../../window_registry.h"
 #include "coordinate_utils_macos.h"
 
@@ -443,6 +444,9 @@ static WindowId ResolveWindowId(NSWindow* ns_window) {
         manager_->DispatchWindowEvent(restored_event);
       }
     }
+  } else if (event_type == "occlusion") {
+    Window wrapper((__bridge void*)window);
+    detail::WindowPropertyDispatch::RefreshOcclusion(wrapper);
   } else if (event_type == "moved") {
     // Same top-left origin as Window::GetPosition()
     CGPoint top_left = NSRectExt::topLeft([window frame]);

src/platform/ohos/window_ohos.cpp

@@ -92,6 +92,14 @@ bool Window::IsVisible() const {
   return pimpl_->native_window_ != nullptr;
 }
 
+WindowOcclusionState Window::GetOcclusionState() const {
+  return WindowOcclusionState::Unknown;
+}
+
+bool Window::IsOcclusionStateSupported() {
+  return false;
+}
+
 void Window::Maximize() {
   // Maximize is not applicable to OpenHarmony Abilities
   // Maximize not supported on OpenHarmony