Struct WindowBuilder 

pub struct WindowBuilder<'a> { /* private fields */ }

A builder for creating new windows.

Implementations

impl<'a> WindowBuilder<'a>

pub fn new( window_proc: impl WindowProc + 'static, window_class: &WindowClass, ) -> WindowBuilder<'_>

Create a new window builder.

The window procedure and window class are set here.

Discussion question: would it ever make sense to create a window without a window procedure?

Examples found in repository

examples/hello-win.rs (line 44)

fn main() {
    unsafe {
        let icon = LoadIconW(0 as HINSTANCE, IDI_APPLICATION);
        let cursor = LoadCursorW(0 as HINSTANCE, IDC_ARROW);
        let brush = CreateSolidBrush(0xff_ff_ff);
        let win_class = WindowClass::builder("rust")
            .icon(icon)
            .cursor(cursor)
            .background(brush)
            .build()
            .unwrap();
        let hwnd = WindowBuilder::new(MyWindowProc, &win_class)
            .name("win-win example")
            .style(WS_OVERLAPPEDWINDOW)
            .build();
        ShowWindow(hwnd, SW_SHOWNORMAL);
        win_win::runloop(null_mut());
    }
}

pub fn build(self) -> HWND

Build a window.

The return value is the HWND for the window, or 0 on error.

The lifetime of the window is until WM_NCDESTROY is called, at which point the window procedure is dropped.

Examples found in repository

examples/hello-win.rs (line 47)

fn main() {
    unsafe {
        let icon = LoadIconW(0 as HINSTANCE, IDI_APPLICATION);
        let cursor = LoadCursorW(0 as HINSTANCE, IDC_ARROW);
        let brush = CreateSolidBrush(0xff_ff_ff);
        let win_class = WindowClass::builder("rust")
            .icon(icon)
            .cursor(cursor)
            .background(brush)
            .build()
            .unwrap();
        let hwnd = WindowBuilder::new(MyWindowProc, &win_class)
            .name("win-win example")
            .style(WS_OVERLAPPEDWINDOW)
            .build();
        ShowWindow(hwnd, SW_SHOWNORMAL);
        win_win::runloop(null_mut());
    }
}

pub fn name(self, name: impl AsRef<OsStr>) -> Self

Set the window name.

This becomes the lpWindowName parameter to CreateWindowEx.

Examples found in repository

examples/hello-win.rs (line 45)

fn main() {
    unsafe {
        let icon = LoadIconW(0 as HINSTANCE, IDI_APPLICATION);
        let cursor = LoadCursorW(0 as HINSTANCE, IDC_ARROW);
        let brush = CreateSolidBrush(0xff_ff_ff);
        let win_class = WindowClass::builder("rust")
            .icon(icon)
            .cursor(cursor)
            .background(brush)
            .build()
            .unwrap();
        let hwnd = WindowBuilder::new(MyWindowProc, &win_class)
            .name("win-win example")
            .style(WS_OVERLAPPEDWINDOW)
            .build();
        ShowWindow(hwnd, SW_SHOWNORMAL);
        win_win::runloop(null_mut());
    }
}

pub fn style(self, style: DWORD) -> Self

Set the window style.

The argument is the bitwise OR of a number of WS_ values from the Window Styles enumeration. It becomes the dwStyle parameter to CreateWindowEx.

Examples found in repository

examples/hello-win.rs (line 46)

fn main() {
    unsafe {
        let icon = LoadIconW(0 as HINSTANCE, IDI_APPLICATION);
        let cursor = LoadCursorW(0 as HINSTANCE, IDC_ARROW);
        let brush = CreateSolidBrush(0xff_ff_ff);
        let win_class = WindowClass::builder("rust")
            .icon(icon)
            .cursor(cursor)
            .background(brush)
            .build()
            .unwrap();
        let hwnd = WindowBuilder::new(MyWindowProc, &win_class)
            .name("win-win example")
            .style(WS_OVERLAPPEDWINDOW)
            .build();
        ShowWindow(hwnd, SW_SHOWNORMAL);
        win_win::runloop(null_mut());
    }
}

pub fn ex_style(self, style: DWORD) -> Self

Set the extended window style.

The argument is the bitwise OR of a number of WS_EX values from the Extended Window Styles enumeration. It becomes the dwExStyle parameter to CreateWindowEx.

An interesting parameter is WS_EX_NOREDIRECTIONBITMAP, which disables the redirection bitmap. It is useful to set when the window will contain a swapchain and no GDI content (in particular, no menus). There is a particular source of artifacting on window resize that is reduced when the redirection bitmap is disabled. It should almost always be set when using DirectComposition, see this article by Kenny Kerr.

pub fn position(self, x: c_int, y: c_int) -> Self

Set the window position.

The arguments become the x and y parameters to CreateWindowEx. To set one but not the other, use CW_USEDEFAULT. These are in raw pixel values.

The position is relative to the top left corner of the primary monitor. See EnumDisplayMonitors for more information about multiple monitors.

pub fn size(self, width: c_int, height: c_int) -> Self

Set the window size.

The arguments become the nWidth and nHeight parameters to CreateWindowEx. To set one but not the other, use CW_USEDEFAULT. These are in raw pixel values.

pub unsafe fn parent_hwnd(self, parent: HWND) -> Self

Set the parent window.

The argument becomes the hWndParent parameter to CreateWindowEx.

Safety

The argument must be a valid HWND reference.

pub unsafe fn menu(self, menu: HMENU) -> Self

Set the menu.

The argument becomes the hMenu parameter to CreateWindowEx.

Safety

The argument must be a valid HMENU reference.

pub unsafe fn instance(self, instance: HINSTANCE) -> Self

Set the instance handle.

The argument becomes the hInstance parameter to CreateWindowEx.

Instance handles are a namespace mechanism, so that components (in a DLL, for example) don’t interfere with each other. For a top-level application, it is safe to leave this unset.

Raymond Chen’s blog has a bit of information about HINSTANCE, including its historical distinction from HMODULE (they are now the same).

Safety

The argument must be a valid HINSTANCE reference.