Add DWMWA_SYSTEMBACKDROP_TYPE support on Windows (#3257)

CHANGELOG.md

@@ -33,7 +33,7 @@ Unreleased` header.
 - Add the `OwnedDisplayHandle` type for allowing safe display handle usage outside of trivial cases.
 - **Breaking:** Rename `TouchpadMagnify` to `PinchGesture`, `SmartMagnify` to `DoubleTapGesture` and `TouchpadRotate` to `RotationGesture` to represent the action rather than the intent.
 - on iOS, add detection support for `PinchGesture`, `DoubleTapGesture` and `RotationGesture`.
-- on Windows: add `with_border_color`, `with_title_background_color`, `with_title_text_color` and `with_corner_preference`
+- on Windows: add `with_system_backdrop`, `with_border_color`, `with_title_background_color`, `with_title_text_color` and `with_corner_preference`
 - On Windows, Remove `WS_CAPTION`, `WS_BORDER` and `WS_EX_WINDOWEDGE` styles for child windows without decorations.
 - On Windows, fixed a race condition when sending an event through the loop proxy.
 

FEATURES.md

@@ -126,6 +126,7 @@ If your PR makes notable changes to Winit's features, please update this section
 * Setting a menu bar
 * `WS_EX_NOREDIRECTIONBITMAP` support
 * Theme the title bar according to Windows 10 Dark Mode setting or set a preferred theme
+* Changing a system-drawn backdrop
 * Setting the window border color
 * Setting the title bar background color
 * Setting the title color

src/platform/windows.rs

@@ -15,6 +15,38 @@ pub type HMENU = isize;
 /// Monitor Handle type used by Win32 API
 pub type HMONITOR = isize;
 
+/// Describes a system-drawn backdrop material of a window.
+///
+/// For a detailed explanation, see [`DWM_SYSTEMBACKDROP_TYPE docs`].
+///
+/// [`DWM_SYSTEMBACKDROP_TYPE docs`]: https://learn.microsoft.com/en-us/windows/win32/api/dwmapi/ne-dwmapi-dwm_systembackdrop_type
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum BackdropType {
+ /// Corresponds to `DWMSBT_AUTO`.
+ ///
+ /// Usually draws a default backdrop effect on the title bar.
+ #[default]
+ Auto = 0,
+
+ /// Corresponds to `DWMSBT_NONE`.
+ None = 1,
+
+ /// Corresponds to `DWMSBT_MAINWINDOW`.
+ ///
+ /// Draws the Mica backdrop material.
+ MainWindow = 2,
+
+ /// Corresponds to `DWMSBT_TRANSIENTWINDOW`.
+ ///
+ /// Draws the Background Acrylic backdrop material.
+ TransientWindow = 3,
+
+ /// Corresponds to `DWMSBT_TABBEDWINDOW`.
+ ///
+ /// Draws the Alt Mica backdrop material.
+ TabbedWindow = 4,
+}
+
 /// Describes a color used by Windows
 #[repr(transparent)]
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
@@ -188,6 +220,11 @@ pub trait WindowExtWindows {
  /// Enabling the shadow causes a thin 1px line to appear on the top of the window.
  fn set_undecorated_shadow(&self, shadow: bool);
 
+ /// Sets system-drawn backdrop type.
+ ///
+ /// Requires Windows 11 build 22523+.
+ fn set_system_backdrop(&self, backdrop_type: BackdropType);
+
  /// Sets the color of the window border.
  ///
  /// Supported starting with Windows 11 Build 22000.
@@ -230,6 +267,11 @@ impl WindowExtWindows for Window {
  self.window.set_undecorated_shadow(shadow)
  }
 
+ #[inline]
+ fn set_system_backdrop(&self, backdrop_type: BackdropType) {
+ self.window.set_system_backdrop(backdrop_type)
+ }
+
  #[inline]
  fn set_border_color(&self, color: Option<Color>) {
  self.window.set_border_color(color.unwrap_or(Color::NONE))
@@ -315,6 +357,11 @@ pub trait WindowBuilderExtWindows {
  /// Enabling the shadow causes a thin 1px line to appear on the top of the window.
  fn with_undecorated_shadow(self, shadow: bool) -> Self;
 
+ /// Sets system-drawn backdrop type.
+ ///
+ /// Requires Windows 11 build 22523+.
+ fn with_system_backdrop(self, backdrop_type: BackdropType) -> Self;
+
  /// This sets or removes `WS_CLIPCHILDREN` style.
  fn with_clip_children(self, flag: bool) -> Self;
 
@@ -388,6 +435,12 @@ impl WindowBuilderExtWindows for WindowBuilder {
  self
  }
 
+ #[inline]
+ fn with_system_backdrop(mut self, backdrop_type: BackdropType) -> Self {
+ self.window.platform_specific.backdrop_type = backdrop_type;
+ self
+ }
+
  #[inline]
  fn with_clip_children(mut self, flag: bool) -> Self {
  self.window.platform_specific.clip_children = flag;

src/platform_impl/windows/mod.rs

@@ -25,7 +25,7 @@ use crate::platform_impl::Fullscreen;
 use crate::event::DeviceId as RootDeviceId;
 use crate::icon::Icon;
 use crate::keyboard::Key;
-use crate::platform::windows::{Color, CornerPreference};
+use crate::platform::windows::{BackdropType, Color, CornerPreference};
 
 #[derive(Clone, Debug)]
 pub struct PlatformSpecificWindowBuilderAttributes {
@@ -37,6 +37,7 @@ pub struct PlatformSpecificWindowBuilderAttributes {
  pub skip_taskbar: bool,
  pub class_name: String,
  pub decoration_shadow: bool,
+ pub backdrop_type: BackdropType,
  pub clip_children: bool,
  pub border_color: Option<Color>,
  pub title_background_color: Option<Color>,
@@ -55,6 +56,7 @@ impl Default for PlatformSpecificWindowBuilderAttributes {
  skip_taskbar: false,
  class_name: "Window Class".to_string(),
  decoration_shadow: false,
+ backdrop_type: BackdropType::default(),
  clip_children: true,
  border_color: None,
  title_background_color: None,

src/platform_impl/windows/window.rs

@@ -16,8 +16,9 @@ use windows_sys::Win32::{
  Graphics::{
  Dwm::{
  DwmEnableBlurBehindWindow, DwmSetWindowAttribute, DWMWA_BORDER_COLOR,
- DWMWA_CAPTION_COLOR, DWMWA_TEXT_COLOR, DWMWA_WINDOW_CORNER_PREFERENCE,
- DWM_BB_BLURREGION, DWM_BB_ENABLE, DWM_BLURBEHIND, DWM_WINDOW_CORNER_PREFERENCE,
+ DWMWA_CAPTION_COLOR, DWMWA_SYSTEMBACKDROP_TYPE, DWMWA_TEXT_COLOR,
+ DWMWA_WINDOW_CORNER_PREFERENCE, DWM_BB_BLURREGION, DWM_BB_ENABLE, DWM_BLURBEHIND,
+ DWM_SYSTEMBACKDROP_TYPE, DWM_WINDOW_CORNER_PREFERENCE,
  },
  Gdi::{
  ChangeDisplaySettingsExW, ClientToScreen, CreateRectRgn, DeleteObject, InvalidateRgn,
@@ -60,12 +61,12 @@ use windows_sys::Win32::{
 
 use log::warn;
 
-use crate::platform::windows::{Color, CornerPreference};
 use crate::{
  cursor::Cursor,
  dpi::{PhysicalPosition, PhysicalSize, Position, Size},
  error::{ExternalError, NotSupportedError, OsError as RootOsError},
  icon::Icon,
+ platform::windows::{BackdropType, Color, CornerPreference},
  platform_impl::platform::{
  dark_mode::try_theme,
  definitions::{
@@ -1019,6 +1020,18 @@ impl Window {
  });
  }
 
+ #[inline]
+ pub fn set_system_backdrop(&self, backdrop_type: BackdropType) {
+ unsafe {
+ DwmSetWindowAttribute(
+ self.hwnd(),
+ DWMWA_SYSTEMBACKDROP_TYPE,
+ &(backdrop_type as i32) as *const _ as _,
+ mem::size_of::<DWM_SYSTEMBACKDROP_TYPE>() as _,
+ );
+ }
+ }
+
  #[inline]
  pub fn focus_window(&self) {
  let window_flags = self.window_state_lock().window_flags();
@@ -1308,6 +1321,8 @@ impl<'a> InitData<'a> {
  win.set_outer_position(position);
  }
 
+ win.set_system_backdrop(self.attributes.platform_specific.backdrop_type);
+
  if let Some(color) = self.attributes.platform_specific.border_color {
  win.set_border_color(color);
  }