v0.4.0

Windows and messages v0.1.0

Source
Registering a window class, creating windows, the message loop, painting and DPI.

WindowProcedure

pub type WindowProcedure = func(*var opaque, uint32, uint, int) -> int

A window procedure: the function the system calls with each message for a window of a class. Its arguments are the window, the message number and the two message parameters, and its result is the message's answer, which DefWindowProcW supplies for every message the procedure does not handle itself. A Rux function of this type is passed directly; it is called with the platform's C convention on the thread that owns the window.

Source

Point

pub struct Point {
    pub x: int32;
    pub y: int32;
}

A point in pixels, the POINT most window calls take.

Source

Fields

NameTypeDescription
xint32The horizontal coordinate, growing to the right.
yint32The vertical coordinate, growing downward.

Rect

pub struct Rect {
    pub left: int32;
    pub top: int32;
    pub right: int32;
    pub bottom: int32;
}

A rectangle in pixels, the RECT that window sizes and paint regions are given as. The right and bottom edges are exclusive, so the width is right - left and the height bottom - top.

Source

Fields

NameTypeDescription
leftint32The left edge.
topint32The top edge.
rightint32The right edge, one past the last column.
bottomint32The bottom edge, one past the last row.

Message

pub struct Message {
    pub window: *var opaque;
    pub message: uint32;
    pub wParam: uint;
    pub lParam: int;
    pub time: uint32;
    pub point: Point;
    pub privateData: uint32;
}

The MSG that GetMessageW fills in: one message taken from the calling thread's queue.

Source

Fields

NameTypeDescription
window*var opaqueThe window the message is for, or null for a message to the thread itself.
messageuint32The message number, such as WM_DESTROY.
wParamuintThe first message parameter, whose meaning depends on the message.
lParamintThe second message parameter, whose meaning depends on the message.
timeuint32When the message was posted, in milliseconds since the system started.
pointPointWhere the cursor was when the message was posted, in screen coordinates.
privateDatauint32Reserved for the system.

WindowClassEx

pub struct WindowClassEx {
    pub size: uint32;
    pub style: uint32;
    pub windowProcedure: WindowProcedure;
    pub classExtra: int32;
    pub windowExtra: int32;
    pub instance: *var opaque;
    pub icon: *var opaque;
    pub cursor: *var opaque;
    pub background: *var opaque;
    pub menuName: *char16;
    pub className: *char16;
    pub smallIcon: *var opaque;
}

The WNDCLASSEXW that RegisterClassExW reads: what every window of a class shares. The class name and menu name are read during registration only; the system keeps its own copies.

Source

Fields

NameTypeDescription
sizeuint32The structure's size in bytes, sizeof(WindowClassEx).
styleuint32The class style bits, such as CS_HREDRAW, combined with |.
windowProcedureWindowProcedureThe function that answers the messages for every window of the class.
classExtraint32Extra bytes the system keeps per class, usually zero.
windowExtraint32Extra bytes the system keeps per window, usually zero.
instance*var opaqueThe module the procedure is in, from GetModuleHandleW(null) for the program itself.
icon*var opaqueThe large icon, or null for the default.
cursor*var opaqueThe cursor shown over the window, or null to leave it to the procedure.
background*var opaqueThe brush the background is erased with, or a COLOR_ index plus one cast to a pointer, or null.
menuName*char16The NUL-terminated UTF-16 menu resource name, or null for no menu.
className*char16The NUL-terminated UTF-16 class name that CreateWindowExW names the class by.
smallIcon*var opaqueThe small icon, or null to derive it from the large one.

PaintStruct

pub struct PaintStruct {
    pub deviceContext: *var opaque;
    pub erase: bool32;
    pub paint: Rect;
    pub restore: bool32;
    pub includeUpdate: bool32;
    pub reserved: uint8[N];
}

The PAINTSTRUCT that BeginPaint fills in and EndPaint reads back.

Source

Fields

NameTypeDescription
deviceContext*var opaqueThe device context to draw with until EndPaint.
erasebool32Non-zero when the background still has to be erased.
paintRectThe part of the window that needs painting, in client coordinates.
restorebool32Reserved for the system.
includeUpdatebool32Reserved for the system.
reserveduint8[N]Reserved for the system.

CS_HREDRAW

pub const CS_HREDRAW: uint32 = 0x0002;

CS_HREDRAW: repaint the whole window when its width changes.

Source

CS_VREDRAW

pub const CS_VREDRAW: uint32 = 0x0001;

CS_VREDRAW: repaint the whole window when its height changes.

Source

WS_OVERLAPPED

pub const WS_OVERLAPPED: uint32 = 0x00000000;

WS_OVERLAPPED: a top-level window with a title bar and a border.

Source

WS_CAPTION

pub const WS_CAPTION: uint32 = 0x00C00000;

WS_CAPTION: the window has a title bar.

Source

WS_SYSMENU

pub const WS_SYSMENU: uint32 = 0x00080000;

WS_SYSMENU: the title bar has the window menu and the close button.

Source

WS_THICKFRAME

pub const WS_THICKFRAME: uint32 = 0x00040000;

WS_THICKFRAME: the window has a sizing border.

Source

WS_MINIMIZEBOX

pub const WS_MINIMIZEBOX: uint32 = 0x00020000;

WS_MINIMIZEBOX: the title bar has a minimize button.

Source

WS_MAXIMIZEBOX

pub const WS_MAXIMIZEBOX: uint32 = 0x00010000;

WS_MAXIMIZEBOX: the title bar has a maximize button.

Source

WS_CHILD

pub const WS_CHILD: uint32 = 0x40000000;

WS_CHILD: the window lives inside its parent's client area.

Source

WS_VISIBLE

pub const WS_VISIBLE: uint32 = 0x10000000;

WS_VISIBLE: the window is shown as soon as it is created.

Source

CW_USEDEFAULT

pub const CW_USEDEFAULT: int32 = -2147483648;

CW_USEDEFAULT: let the system choose the position or size.

Source

SW_SHOW

pub const SW_SHOW: int32 = 5;

SW_SHOW: show the window at its current size and position and activate it.

Source

WM_CREATE

pub const WM_CREATE: uint32 = 0x0001;

WM_CREATE: the window has been created and is not yet shown; answer zero to keep it.

Source

WM_DESTROY

pub const WM_DESTROY: uint32 = 0x0002;

WM_DESTROY: the window is being destroyed; a main window posts the quit message here.

Source

WM_PAINT

pub const WM_PAINT: uint32 = 0x000F;

WM_PAINT: part of the window needs drawing, between BeginPaint and EndPaint.

Source

WM_CLOSE

pub const WM_CLOSE: uint32 = 0x0010;

WM_CLOSE: the user asked to close the window; the default answer destroys it.

Source

WM_SETFONT

pub const WM_SETFONT: uint32 = 0x0030;

WM_SETFONT: a control should draw with the font handle in wParam.

Source

WM_USER

pub const WM_USER: uint32 = 0x0400;

WM_USER: the first message number a program may give its own messages within one window class.

Source

WM_DPICHANGED

pub const WM_DPICHANGED: uint32 = 0x02E0;

WM_DPICHANGED: the window moved to a monitor with another scale. The new DPI is in both halves of wParam, and lParam points to the Rect the system suggests for the window.

Source

COLOR_WINDOW

pub const COLOR_WINDOW: int32 = 5;

COLOR_WINDOW: the system color of a window's background, for GetSysColor and GetSysColorBrush.

Source

COLOR_WINDOWTEXT

pub const COLOR_WINDOWTEXT: int32 = 8;

COLOR_WINDOWTEXT: the system color of text in a window.

Source

COLOR_GRAYTEXT

pub const COLOR_GRAYTEXT: int32 = 17;

COLOR_GRAYTEXT: the system color of text that is shown but not active.

Source

MB_OK

pub const MB_OK: uint32 = 0x00000000;

MB_OK: the message box has one OK button.

Source

MB_ICONERROR

pub const MB_ICONERROR: uint32 = 0x00000010;

MB_ICONERROR: the message box shows the error icon.

Source

SWP_NOMOVE

pub const SWP_NOMOVE: uint32 = 0x0002;

SWP_NOMOVE: SetWindowPos keeps the window where it is and ignores x and y.

Source

SWP_NOZORDER

pub const SWP_NOZORDER: uint32 = 0x0004;

SWP_NOZORDER: SetWindowPos keeps the window's place in the stacking order and ignores insertAfter.

Source

SWP_NOACTIVATE

pub const SWP_NOACTIVATE: uint32 = 0x0010;

SWP_NOACTIVATE: SetWindowPos does not activate the window.

Source

IDC_ARROW

pub const IDC_ARROW: uint64 = 32512;

IDC_ARROW: the standard arrow cursor, as the resource number LoadCursorW takes in place of a name. It is a number, not a string, so it is cast to the name pointer: IDC_ARROW as *char16.

Source

IDI_APPLICATION

pub const IDI_APPLICATION: uint64 = 32512;

IDI_APPLICATION: the default application icon, as the resource number LoadIconW takes in place of a name.

Source

HWND_MESSAGE

pub const HWND_MESSAGE: uint64 = 0xFFFFFFFFFFFFFFFD;

HWND_MESSAGE: the parent that makes a window message-only, never shown and never enumerated. It is -3 as a pointer, so it is cast at the call: HWND_MESSAGE as *var opaque.

Source

DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2

pub const DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2: uint64 = 0xFFFFFFFFFFFFFFFC;

DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2: the process draws for each monitor's own scale. It is -4 as a pointer, so it is cast at the call. Without it the system stretches the window's pixels on any monitor scaled above 100%, which is what makes an old program's text blurry.

Source

AdjustWindowRectExForDpi

pub extern func AdjustWindowRectExForDpi(
    rect: *var Rect,
    style: uint32,
    menu: bool32,
    exStyle: uint32,
    dpi: uint32
) -> bool32

Grows a client rectangle to the window rectangle that holds it, at a given DPI. The result includes the title bar and borders the style adds, measured for that DPI rather than the system's.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-adjustwindowrectexfordpi

Source

Parameters

NameTypeDescription
rect*var Rectthe client rectangle on entry, and the window rectangle on return
styleuint32the window's WS_ style
menubool32non-zero when the window has a menu bar
exStyleuint32the window's extended style
dpiuint32the DPI to measure the frame at, usually from GetDpiForWindow

Returns: non-zero on success, and zero on failure with the reason in GetLastError

BeginPaint

pub extern func BeginPaint(
    window: *var opaque,
    paint: *var PaintStruct
) -> *var opaque

Prepares a window for painting and fills in what needs painting. Called only in answer to WM_PAINT, and always paired with EndPaint, which validates the region.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-beginpaint

Source

Parameters

NameTypeDescription
window*var opaquethe window being painted
paint*var PaintStructreceives the device context and the region to paint

Returns: the device context to draw with, or null when none is available

CreateWindowExW

pub extern func CreateWindowExW(
    exStyle: uint32,
    className: *char16,
    windowName: *char16,
    style: uint32,
    x: int32,
    y: int32,
    width: int32,
    height: int32,
    parent: *var opaque,
    menu: *var opaque,
    instance: *var opaque,
    parameter: *var opaque
) -> *var opaque

Creates a window of a registered class. The procedure receives WM_CREATE before this call returns, so the window is already set up when it does.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-createwindowexw

Source

Parameters

NameTypeDescription
exStyleuint32the extended style bits, usually zero
className*char16the NUL-terminated UTF-16 name of a registered class
windowName*char16the NUL-terminated UTF-16 title, or null
styleuint32the WS_ style bits, combined with |
xint32the left edge, or CW_USEDEFAULT
yint32the top edge, or CW_USEDEFAULT
widthint32the width, or CW_USEDEFAULT
heightint32the height, or CW_USEDEFAULT
parent*var opaquethe parent or owner window, HWND_MESSAGE for a message-only window, or null
menu*var opaquethe menu, or for a child window its identifier, or null
instance*var opaquethe module the class was registered by
parameter*var opaquea value passed through to WM_CREATE, or null

Returns: the new window, or null on failure with the reason in GetLastError

DefWindowProcW

pub extern func DefWindowProcW(
    window: *var opaque,
    message: uint32,
    wParam: uint,
    lParam: int
) -> int

Answers a message the way the system does when a window procedure does not handle it. A procedure passes every message it does not answer itself on to this call, unchanged, and returns its result.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-defwindowprocw

Source

Parameters

NameTypeDescription
window*var opaquethe window the message is for
messageuint32the message number
wParamuintthe first message parameter
lParamintthe second message parameter

Returns: the message's default answer

DestroyWindow

pub extern func DestroyWindow(window: *var opaque) -> bool32

Destroys a window and its children, sending them WM_DESTROY. Only the thread that created the window may destroy it.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-destroywindow

Source

Parameters

NameTypeDescription
window*var opaquethe window to destroy

Returns: non-zero on success, and zero on failure with the reason in GetLastError

DispatchMessageW

pub extern func DispatchMessageW(message: *Message) -> int

Hands a message to the window procedure of the window it is for.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-dispatchmessagew

Source

Parameters

NameTypeDescription
message*Messagea message from GetMessageW

Returns: what the window procedure returned

EndPaint

pub extern func EndPaint(
    window: *var opaque,
    paint: *PaintStruct
) -> bool32

Ends the painting BeginPaint began and marks the region painted.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-endpaint

Source

Parameters

NameTypeDescription
window*var opaquethe window being painted
paint*PaintStructthe structure BeginPaint filled in

Returns: non-zero, always

GetClientRect

pub extern func GetClientRect(
    window: *var opaque,
    rect: *var Rect
) -> bool32

Retrieves the window's client area, whose top-left corner is always zero.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-getclientrect

Source

Parameters

NameTypeDescription
window*var opaquethe window
rect*var Rectreceives the client area

Returns: non-zero on success, and zero on failure with the reason in GetLastError

GetDpiForWindow

pub extern func GetDpiForWindow(window: *var opaque) -> uint32

Retrieves the DPI of the monitor the window is on, which is 96 at 100% scaling. A process that is not DPI aware always receives 96.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-getdpiforwindow

Source

Parameters

NameTypeDescription
window*var opaquethe window

Returns: the window's DPI, or zero when window is not a window

GetMessageW

pub extern func GetMessageW(
    message: *var Message,
    window: *var opaque,
    filterMin: uint32,
    filterMax: uint32
) -> int32

Waits for the next message of the calling thread and takes it from the queue. The result has three meanings, not two: positive for a message, zero for WM_QUIT, which ends the loop, and -1 for an error with the reason in GetLastError, which a loop testing only for non-zero would spin on.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-getmessagew

Source

Parameters

NameTypeDescription
message*var Messagereceives the message
window*var opaquethe window to take messages for, or null for every window of the thread
filterMinuint32the lowest message number to take, or zero for no filter
filterMaxuint32the highest message number to take, or zero for no filter

Returns: positive for a message, zero for WM_QUIT, or -1 on failure

GetSysColor

pub extern func GetSysColor(index: int32) -> uint32

Retrieves one of the system colors, as 0x00BBGGRR.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-getsyscolor

Source

Parameters

NameTypeDescription
indexint32a COLOR_ value

Returns: the color, or zero for an index the system does not know

GetSysColorBrush

pub extern func GetSysColorBrush(index: int32) -> *var opaque

Retrieves the brush of one of the system colors, which the system owns and must not be deleted.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-getsyscolorbrush

Source

Parameters

NameTypeDescription
indexint32a COLOR_ value

Returns: the brush, or null for an index the system does not know

InvalidateRect

pub extern func InvalidateRect(
    window: *var opaque,
    rect: *Rect,
    erase: bool32
) -> bool32

Marks part of the window as needing paint, so the next pass of the loop sends WM_PAINT.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-invalidaterect

Source

Parameters

NameTypeDescription
window*var opaquethe window
rect*Rectthe part to mark, or null for the whole client area
erasebool32non-zero to erase the background before painting

Returns: non-zero on success, and zero on failure

LoadCursorW

pub extern func LoadCursorW(
    instance: *var opaque,
    name: *char16
) -> *var opaque

Loads a cursor; with a null instance and a resource number such as IDC_ARROW, one of the system's. A system cursor is shared and must not be destroyed.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-loadcursorw

Source

Parameters

NameTypeDescription
instance*var opaquethe module holding the cursor, or null for a system cursor
name*char16the NUL-terminated UTF-16 resource name, or a resource number cast to a pointer

Returns: the cursor, or null on failure with the reason in GetLastError

LoadIconW

pub extern func LoadIconW(
    instance: *var opaque,
    name: *char16
) -> *var opaque

Loads an icon; with a null instance and a resource number such as IDI_APPLICATION, one of the system's. A system icon is shared and must not be destroyed.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-loadiconw

Source

Parameters

NameTypeDescription
instance*var opaquethe module holding the icon, or null for a system icon
name*char16the NUL-terminated UTF-16 resource name, or a resource number cast to a pointer

Returns: the icon, or null on failure with the reason in GetLastError

MessageBoxW

pub extern func MessageBoxW(
    window: *var opaque,
    text: *char16,
    caption: *char16,
    style: uint32
) -> int32

Shows a modal message box and waits for the user to close it.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-messageboxw

Source

Parameters

NameTypeDescription
window*var opaquethe owner window, or null
text*char16the NUL-terminated UTF-16 message
caption*char16the NUL-terminated UTF-16 title, or null for "Error"
styleuint32the MB_ bits choosing the buttons and the icon

Returns: the button the user chose, such as IDOK, or zero on failure with the reason in GetLastError

PostQuitMessage

pub extern func PostQuitMessage(exitCode: int32)

Posts WM_QUIT to the calling thread, which makes its GetMessageW return zero. A main window calls it from WM_DESTROY, so closing the window ends the loop.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-postquitmessage

Source

Parameters

NameTypeDescription
exitCodeint32the code the quit message carries in wParam

RegisterClassExW

pub extern func RegisterClassExW(windowClass: *WindowClassEx) -> uint16

Registers a window class that CreateWindowExW can then create windows of. A class name is per module: registering one twice fails with ERROR_CLASS_ALREADY_EXISTS.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-registerclassexw

Source

Parameters

NameTypeDescription
windowClass*WindowClassExwhat the class's windows share, with size set to sizeof(WindowClassEx)

Returns: the class atom, or zero on failure with the reason in GetLastError

SendMessageW

pub extern func SendMessageW(
    window: *var opaque,
    message: uint32,
    wParam: uint,
    lParam: int
) -> int

Sends a message to a window and waits for its procedure to answer. On the window's own thread this is a direct call of the procedure; from another thread it waits for the owner's loop to deliver it.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-sendmessagew

Source

Parameters

NameTypeDescription
window*var opaquethe window
messageuint32the message number
wParamuintthe first message parameter
lParamintthe second message parameter

Returns: the procedure's answer

SetProcessDpiAwarenessContext

pub extern func SetProcessDpiAwarenessContext(context: *var opaque) -> bool32

Sets how the process is told about display scale, which only takes effect before its first window exists. Fails with ERROR_ACCESS_DENIED when the awareness is already set, by an earlier call or a manifest.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-setprocessdpiawarenesscontext

Source

Parameters

NameTypeDescription
context*var opaquea DPI_AWARENESS_CONTEXT_ value cast to a pointer

Returns: non-zero on success, and zero on failure with the reason in GetLastError

SetWindowPos

pub extern func SetWindowPos(
    window: *var opaque,
    insertAfter: *var opaque,
    x: int32,
    y: int32,
    width: int32,
    height: int32,
    flags: uint32
) -> bool32

Changes the window's size, position or stacking order with one call.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-setwindowpos

Source

Parameters

NameTypeDescription
window*var opaquethe window
insertAfter*var opaquethe window to place it after, ignored with SWP_NOZORDER
xint32the new left edge
yint32the new top edge
widthint32the new width
heightint32the new height
flagsuint32SWP_ bits saying which of the values to apply

Returns: non-zero on success, and zero on failure with the reason in GetLastError

SetWindowTextW

pub extern func SetWindowTextW(
    window: *var opaque,
    text: *char16
) -> bool32

Changes the window's title, or a control's text.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-setwindowtextw

Source

Parameters

NameTypeDescription
window*var opaquethe window
text*char16the NUL-terminated UTF-16 text

Returns: non-zero on success, and zero on failure with the reason in GetLastError

ShowWindow

pub extern func ShowWindow(
    window: *var opaque,
    command: int32
) -> bool32

Shows, hides, minimizes or restores a window.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-showwindow

Source

Parameters

NameTypeDescription
window*var opaquethe window
commandint32an SW_ value, such as SW_SHOW

Returns: non-zero when the window was visible before, and zero when it was hidden; it reports no failure

TranslateMessage

pub extern func TranslateMessage(message: *Message) -> bool32

Translates key presses into character messages, posted to the same queue.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-translatemessage

Source

Parameters

NameTypeDescription
message*Messagea message from GetMessageW

Returns: non-zero when a character message was posted

UnregisterClassW

pub extern func UnregisterClassW(
    className: *char16,
    instance: *var opaque
) -> bool32

Removes a window class once no window of it remains.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-unregisterclassw

Source

Parameters

NameTypeDescription
className*char16the NUL-terminated UTF-16 class name
instance*var opaquethe module that registered it

Returns: non-zero on success, and zero on failure with the reason in GetLastError

UpdateWindow

pub extern func UpdateWindow(window: *var opaque) -> bool32

Paints any part of the window that needs it now, rather than when the loop is next idle.

See also: https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-updatewindow

Source

Parameters

NameTypeDescription
window*var opaquethe window

Returns: non-zero on success, and zero on failure