Add Widget::IsVisibleOnScreen() API to distinguish between window mapping state and on-screen visibility

Commit: e7c8be57 | 2025-04-23 18:45:47+00:00

← Back to List

Add Widget::IsVisibleOnScreen() API to distinguish between window mapping state and on-screen visibility

Moderate
Commit Hash: e7c8be576285195257b0813326b3bab154dc7e73
Commit Time: 2025-04-23 18:45:47+00:00
Impact Level: Moderate
Generated By: webview2-upstream-sentry
Upstream Review: View Upstream Review 🔗

📋 Summary

This submission introduces a new API, Widget::IsVisibleOnScreen(), for detecting whether a Widget is visible to the user on the screen. This API differentiates between the existing IsVisible() (which only checks whether the window is mapped by the window server) and the new IsVisibleOnScreen() (which checks whether the window is actually visible to the user on the active virtual desktop). On macOS, this functionality is implemented by tracking the NSWindow’s isOnActiveSpace property, including listening to the NSWorkspaceActiveSpaceDidChangeNotification notification and the windowDidChangeOcclusionState callback. On other platforms, this method is currently equivalent to IsVisible(). This change also updates the documentation for the IsVisible() method to clarify that it only checks the window mapping status and does not check actual screen visibility.

🎯 Impact Analysis

This change has a moderate impact on WebView2Mac. The newly added IsVisibleOnScreen() API provides WebView2Mac with more precise visibility detection capabilities, especially in macOS multi-desktop environments. WebView2Mac can utilize this API to: 1) more accurately determine whether the WebView is visible to the user, thereby optimizing rendering performance and resource usage; 2) adjust behavior accordingly during virtual desktop switching; 3) deliver a better user experience by avoiding unnecessary operations on hidden desktops. Since WebView2Mac is based on the Remote Cocoa architecture, this change extends Remote Cocoa’s window visibility management capabilities and enhances downstream WebView2Mac functionality. However, as this is a newly added API, it does not break existing compatibility; the impact is primarily functional enhancement rather than risk.

Impacted Classes:

NativeWidgetNSWindowBridge ViewsNSWindowDelegate NativeWidgetNSWindowHost NativeWidgetMac Widget