Struct WindowClassBuilder

pub struct WindowClassBuilder { /* private fields */ }

A builder for registering new window classes.

Implementations

impl WindowClassBuilder

pub const DLGWINDOWEXTRA: c_int = 30i32

The number of extra bytes needed for dialogs.

See wnd_extra_bytes.

pub fn build(self) -> Result<WindowClass, Error>

Create the window class.

Note: the window class is leaked, as its lifetime is most commonly that of the application. Somebody who really wants to reclaim that memory can call UnregisterClass manually and deal with the soundness consequences.

Examples found in repository

examples/hello-win.rs (line 42)

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 class_style(self, style: DWORD) -> Self

Set the window class style.

The argument is the bitwise OR of a number of CS_ values from the Window Class Styles enumeration. It becomes style field in the WNDCLASSEX passed to RegisterClassEx. See Class Styles for more explanation.

pub unsafe fn wnd_extra_bytes(self, extra_bytes: c_int) -> Self

Allocate extra bytes in window instances.

The argument becomes the cbWndExtra field in the WNDCLASSEX passed to RegisterClassEx.

Generally this isn’t that useful unless creating a dialog, in which case it should be DLGWINDOWEXTRA.

Note: there is no corresponding method to set cbClsExtra, as I can’t think of a good reason why it would ever be needed.

Safety

The argument must be a reasonable size (no idea what happens if negative, for example).

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

Set the instance handle.

The argument becomes the hInstance field in the WNDCLASSEX passed to RegisterClassEx.

See the instance method on WindowBuilder for more details.

Safety

The argument must be a valid HINSTANCE reference.

pub unsafe fn icon(self, icon: HICON) -> Self

Set the icon.

The argument becomes the hIcon field in the WNDCLASSEX passed to RegisterClassEx.

Safety

The argument must be a valid HICON reference.

Examples found in repository

examples/hello-win.rs (line 39)

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 unsafe fn small_icon(self, icon: HICON) -> Self

Set the small icon.

The argument becomes the hIconSm field in the WNDCLASSEX passed to RegisterClassEx.

Safety

The argument must be a valid HICON reference.

pub unsafe fn cursor(self, cursor: HCURSOR) -> Self

Set the cursor.

The argument becomes the hCursor field in the WNDCLASSEX passed to RegisterClassEx.

The default implementation of WM_SETCURSOR applies this cursor. In the old-school approach where each control has its own HWND, it’s reasonable to use this to set the cursor, then everything should just work (even without explicit handling of WM_SETCURSOR). However, in the modern approach where there’s a single window for the application, probably a more useful strategy is to set the cursor on WM_MOUSEMOVE, which reports the cursor position (rather than relying on hit testing with the HWND bounds). In that case, setting a default cursor on the window will likely result in flashing, as the two window message handlers will compete.

This Stack overflow question contains more details.

Of course, if the entire window is to have a single cursor, setting it here is quite reasonable.

Safety

The argument must be a valid HCURSOR reference.

Examples found in repository

examples/hello-win.rs (line 40)

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 unsafe fn background(self, brush: HBRUSH) -> Self

Set the background brush.

The argument becomes the hBrBackground field in the WNDCLASSEX passed to RegisterClassEx.

Safety

The argument must be a valid HBRUSH reference.

Examples found in repository

examples/hello-win.rs (line 41)

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 menu_name(self, menu_name: impl AsRef<OsStr>) -> Self

Set the default menu.

The argument becomes the lpszClassName field in the WNDCLASSEX passed to RegisterClassEx.

The string references the resource name of the class menu. There is no mechanism to support the MAKEINTRESOURCE macro.