Trait WindowExtWindows

pub trait WindowExtWindows {
    // Required methods
    fn set_enable(&self, enabled: bool);
    fn set_taskbar_icon(&self, taskbar_icon: Option<Icon>);
    fn set_skip_taskbar(&self, skip: bool);
    fn set_undecorated_shadow(&self, shadow: bool);
    fn set_system_backdrop(&self, backdrop_type: BackdropType);
    fn set_border_color(&self, color: Option<Color>);
    fn set_title_background_color(&self, color: Option<Color>);
    fn set_title_text_color(&self, color: Color);
    fn set_corner_preference(&self, preference: CornerPreference);
    fn set_cloaked(&self, cloaked: bool);
    unsafe fn window_handle_any_thread(
        &self,
    ) -> Result<WindowHandle<'_>, HandleError>;
}

Additional methods on Window that are specific to Windows.

Required Methods

fn set_enable(&self, enabled: bool)

Enables or disables mouse and keyboard input to the specified window.

A window must be enabled before it can be activated. If an application has create a modal dialog box by disabling its owner window (as described in WindowAttributesExtWindows::with_owner_window), the application must enable the owner window before destroying the dialog box. Otherwise, another window will receive the keyboard focus and be activated.

If a child window is disabled, it is ignored when the system tries to determine which window should receive mouse messages.

For more information, see https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-enablewindow#remarks and https://docs.microsoft.com/en-us/windows/win32/winmsg/window-features#disabled-windows

fn set_taskbar_icon(&self, taskbar_icon: Option<Icon>)

This sets ICON_BIG. A good ceiling here is 256x256.

fn set_skip_taskbar(&self, skip: bool)

Whether to show or hide the window icon in the taskbar.

fn set_undecorated_shadow(&self, shadow: bool)

Shows or hides the background drop shadow for undecorated windows.

Enabling the shadow causes a thin 1px line to appear on the top of the window.

fn set_system_backdrop(&self, backdrop_type: BackdropType)

Sets system-drawn backdrop type.

Requires Windows 11 build 22523+.

fn set_border_color(&self, color: Option<Color>)

Sets the color of the window border.

Supported starting with Windows 11 Build 22000.

fn set_title_background_color(&self, color: Option<Color>)

Sets the background color of the title bar.

Supported starting with Windows 11 Build 22000.

fn set_title_text_color(&self, color: Color)

Sets the color of the window title.

Supported starting with Windows 11 Build 22000.

fn set_corner_preference(&self, preference: CornerPreference)

Sets the preferred style of the window corners.

Supported starting with Windows 11 Build 22000.

fn set_cloaked(&self, cloaked: bool)

Cloaks the window such that it is not visible to the user. The window is still composed by DWM.

A cloaked window will not appear on Taskbar. Cloaking is particularly useful when you want a window to complete its UI layout, sizing, etc. without flickering in front of the user. Not supported on Windows 7 and earlier.

unsafe fn window_handle_any_thread( &self, ) -> Result<WindowHandle<'_>, HandleError>

Get the raw window handle for this Window without checking for thread affinity.

Window handles in Win32 have a property called “thread affinity” that ties them to their origin thread. Some operations can only happen on the window’s origin thread, while others can be called from any thread. For example, SetWindowSubclass is not thread safe while GetDC is thread safe.

In Rust terms, the window handle is Send sometimes but !Send other times.

Therefore, in order to avoid confusing threading errors, Window only returns the window handle when the window_handle function is called from the thread that created the window. In other cases, it returns an Unavailable error.

However in some cases you may already know that you are using the window handle for operations that are guaranteed to be thread-safe. In which case this function aims to provide an escape hatch so these functions are still accessible from other threads.

Safety

It is the responsibility of the user to only pass the window handle into thread-safe Win32 APIs.

Example

use std::thread;
use rio_window::platform::windows::WindowExtWindows;
use rio_window::raw_window_handle::HasWindowHandle;

// We can get the window handle on the current thread.
let handle = window.window_handle().unwrap();

// However, on another thread, we can't!
thread::spawn(move || {
    assert!(window.window_handle().is_err());

    // We can use this function as an escape hatch.
    let handle = unsafe { window.window_handle_any_thread().unwrap() };
});

Implementors

impl WindowExtWindows for Window