Implement headless mode window zoom
Minor
Commit Hash:
b16dacd52cdb1c96d73fc36be1a21225ab48b59c
Commit Time: 2026-01-23 18:27:40+00:00
Impact Level: Minor
Generated By: webview2-upstream-sentry
Upstream Review:
View Upstream Review 🔗
📋 Summary
This commit implements window zoom functionality for headless mode on macOS. It injects headless-aware zoom behavior into NativeWidgetMacNSWindow through runtime ObjC swizzling, ensuring that window zoom behavior in headless mode conforms to headless screen characteristics while not affecting normal mode window zoom behavior.
Main changes include:
1. Added native_widget_mac_nswindow_headless.h/mm files, defining the NativeWidgetMacNSWindowHeadlessInfo structure to store headless window zoom state (is_zoomed) and restored bounds (restored_bounds)
2. Added headlessInfo method to NativeWidgetMacNSWindow to retrieve additional information for headless windows
3. Removed the _isHeadless BOOL member variable from NativeWidgetMacNSWindow, now determining if a window is headless through headlessInfo
4. Replaced isZoomed, setIsZoomed, and zoom: method implementations for NativeWidgetMacNSWindow through swizzling to make them aware of headless screen boundaries in headless mode
5. Updated test cases, removing conditional compilation restrictions for the MaximizeRestoreWindow test on macOS
This is the first CL in a series of headless window management improvements, with minimize, fullscreen and other features to follow.
Main changes include:
1. Added native_widget_mac_nswindow_headless.h/mm files, defining the NativeWidgetMacNSWindowHeadlessInfo structure to store headless window zoom state (is_zoomed) and restored bounds (restored_bounds)
2. Added headlessInfo method to NativeWidgetMacNSWindow to retrieve additional information for headless windows
3. Removed the _isHeadless BOOL member variable from NativeWidgetMacNSWindow, now determining if a window is headless through headlessInfo
4. Replaced isZoomed, setIsZoomed, and zoom: method implementations for NativeWidgetMacNSWindow through swizzling to make them aware of headless screen boundaries in headless mode
5. Updated test cases, removing conditional compilation restrictions for the MaximizeRestoreWindow test on macOS
This is the first CL in a series of headless window management improvements, with minimize, fullscreen and other features to follow.
🎯 Impact Analysis
The impact of this change on WebView2Mac is Minor. The main reasons are:
1. **Feature Isolation**: The changes primarily target headless mode, which WebView2Mac typically does not run in. The new headless zoom logic is only activated when a window's isHeadless property is YES. Windows created by WebView2Mac are usually normal mode windows and will not be affected by headless-specific logic.
2. **Safe Implementation Approach**: Function injection is implemented through ObjC swizzling, only replacing method implementations in headless mode. This design ensures zero impact on existing non-headless window behavior. Swizzling is applied dynamically at runtime and does not change the static interface of NativeWidgetMacNSWindow.
3. **API Interface Changes**: The newly added headlessInfo method is an optional extension interface that may return nullptr (for non-headless windows). This is a backward-compatible addition that does not break existing code.
4. **Member Variable Refactoring**: Changing the _isHeadless BOOL member variable to determination through headlessInfo is an internal implementation detail change. The reference to _isHeadless in the constrainFrameRect:toScreen: method is preserved (through the self.isHeadless property), maintaining compatibility with existing code.
5. **Potential Risk Points**:
- If WebView2Mac's host application runs in a headless environment (e.g., automation testing scenarios), the new zoom behavior will be activated
- The constrainFrameRect:toScreen: method still uses _isHeadless, which still exists in the new code, so it will not break existing logic
- If WebView2Mac needs to support headless mode in the future, this change provides foundational support
6. **Test Impact**: Test case changes only affect headless mode tests and will not impact WebView2Mac's normal testing process.
Overall, this is a specific optimization for headless mode that, through good code isolation and backward-compatible design, does not substantially impact WebView2Mac's existing functionality. It is recommended to monitor subsequent related CLs for minimize and fullscreen functionality to ensure that the entire headless window management feature set does not introduce unexpected side effects.
1. **Feature Isolation**: The changes primarily target headless mode, which WebView2Mac typically does not run in. The new headless zoom logic is only activated when a window's isHeadless property is YES. Windows created by WebView2Mac are usually normal mode windows and will not be affected by headless-specific logic.
2. **Safe Implementation Approach**: Function injection is implemented through ObjC swizzling, only replacing method implementations in headless mode. This design ensures zero impact on existing non-headless window behavior. Swizzling is applied dynamically at runtime and does not change the static interface of NativeWidgetMacNSWindow.
3. **API Interface Changes**: The newly added headlessInfo method is an optional extension interface that may return nullptr (for non-headless windows). This is a backward-compatible addition that does not break existing code.
4. **Member Variable Refactoring**: Changing the _isHeadless BOOL member variable to determination through headlessInfo is an internal implementation detail change. The reference to _isHeadless in the constrainFrameRect:toScreen: method is preserved (through the self.isHeadless property), maintaining compatibility with existing code.
5. **Potential Risk Points**:
- If WebView2Mac's host application runs in a headless environment (e.g., automation testing scenarios), the new zoom behavior will be activated
- The constrainFrameRect:toScreen: method still uses _isHeadless, which still exists in the new code, so it will not break existing logic
- If WebView2Mac needs to support headless mode in the future, this change provides foundational support
6. **Test Impact**: Test case changes only affect headless mode tests and will not impact WebView2Mac's normal testing process.
Overall, this is a specific optimization for headless mode that, through good code isolation and backward-compatible design, does not substantially impact WebView2Mac's existing functionality. It is recommended to monitor subsequent related CLs for minimize and fullscreen functionality to ensure that the entire headless window management feature set does not introduce unexpected side effects.
Impacted Classes:
remote_cocoa::NativeWidgetMacNSWindow
NativeWidgetMacNSWindowHeadlessInfo
NativeWidgetMacHeadlessNSWindow