Windows and messages v0.1.0
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.
Point
pub struct Point {
pub x: int32;
pub y: int32;
}
A point in pixels, the POINT most window calls take.
Fields
| Name | Type | Description |
|---|---|---|
x | int32 | The horizontal coordinate, growing to the right. |
y | int32 | The 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.
Fields
| Name | Type | Description |
|---|---|---|
left | int32 | The left edge. |
top | int32 | The top edge. |
right | int32 | The right edge, one past the last column. |
bottom | int32 | The 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.
Fields
| Name | Type | Description |
|---|---|---|
window | *var opaque | The window the message is for, or null for a message to the thread itself. |
message | uint32 | The message number, such as WM_DESTROY. |
wParam | uint | The first message parameter, whose meaning depends on the message. |
lParam | int | The second message parameter, whose meaning depends on the message. |
time | uint32 | When the message was posted, in milliseconds since the system started. |
point | Point | Where the cursor was when the message was posted, in screen coordinates. |
privateData | uint32 | Reserved 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.
Fields
| Name | Type | Description |
|---|---|---|
size | uint32 | The structure's size in bytes, sizeof(WindowClassEx). |
style | uint32 | The class style bits, such as CS_HREDRAW, combined with |. |
windowProcedure | WindowProcedure | The function that answers the messages for every window of the class. |
classExtra | int32 | Extra bytes the system keeps per class, usually zero. |
windowExtra | int32 | Extra bytes the system keeps per window, usually zero. |
instance | *var opaque | The module the procedure is in, from GetModuleHandleW(null) for the program itself. |
icon | *var opaque | The large icon, or null for the default. |
cursor | *var opaque | The cursor shown over the window, or null to leave it to the procedure. |
background | *var opaque | The brush the background is erased with, or a COLOR_ index plus one cast to a pointer, or null. |
menuName | *char16 | The NUL-terminated UTF-16 menu resource name, or null for no menu. |
className | *char16 | The NUL-terminated UTF-16 class name that CreateWindowExW names the class by. |
smallIcon | *var opaque | The 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.
Fields
| Name | Type | Description |
|---|---|---|
deviceContext | *var opaque | The device context to draw with until EndPaint. |
erase | bool32 | Non-zero when the background still has to be erased. |
paint | Rect | The part of the window that needs painting, in client coordinates. |
restore | bool32 | Reserved for the system. |
includeUpdate | bool32 | Reserved for the system. |
reserved | uint8[N] | Reserved for the system. |
CS_HREDRAW
pub const CS_HREDRAW: uint32 = 0x0002;
CS_HREDRAW: repaint the whole window when its width changes.
CS_VREDRAW
pub const CS_VREDRAW: uint32 = 0x0001;
CS_VREDRAW: repaint the whole window when its height changes.
WS_OVERLAPPED
pub const WS_OVERLAPPED: uint32 = 0x00000000;
WS_OVERLAPPED: a top-level window with a title bar and a border.
WS_CAPTION
pub const WS_CAPTION: uint32 = 0x00C00000;
WS_CAPTION: the window has a title bar.
WS_SYSMENU
pub const WS_SYSMENU: uint32 = 0x00080000;
WS_SYSMENU: the title bar has the window menu and the close button.
WS_THICKFRAME
pub const WS_THICKFRAME: uint32 = 0x00040000;
WS_THICKFRAME: the window has a sizing border.
WS_MINIMIZEBOX
pub const WS_MINIMIZEBOX: uint32 = 0x00020000;
WS_MINIMIZEBOX: the title bar has a minimize button.
WS_MAXIMIZEBOX
pub const WS_MAXIMIZEBOX: uint32 = 0x00010000;
WS_MAXIMIZEBOX: the title bar has a maximize button.
WS_CHILD
pub const WS_CHILD: uint32 = 0x40000000;
WS_CHILD: the window lives inside its parent's client area.
WS_VISIBLE
pub const WS_VISIBLE: uint32 = 0x10000000;
WS_VISIBLE: the window is shown as soon as it is created.
CW_USEDEFAULT
pub const CW_USEDEFAULT: int32 = -2147483648;
CW_USEDEFAULT: let the system choose the position or size.
SW_SHOW
pub const SW_SHOW: int32 = 5;
SW_SHOW: show the window at its current size and position and activate it.
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.
WM_DESTROY
pub const WM_DESTROY: uint32 = 0x0002;
WM_DESTROY: the window is being destroyed; a main window posts the quit message here.
WM_PAINT
pub const WM_PAINT: uint32 = 0x000F;
WM_PAINT: part of the window needs drawing, between BeginPaint and EndPaint.
WM_CLOSE
pub const WM_CLOSE: uint32 = 0x0010;
WM_CLOSE: the user asked to close the window; the default answer destroys it.
WM_SETFONT
pub const WM_SETFONT: uint32 = 0x0030;
WM_SETFONT: a control should draw with the font handle in wParam.
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.
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.
COLOR_WINDOW
pub const COLOR_WINDOW: int32 = 5;
COLOR_WINDOW: the system color of a window's background, for GetSysColor and GetSysColorBrush.
COLOR_WINDOWTEXT
pub const COLOR_WINDOWTEXT: int32 = 8;
COLOR_WINDOWTEXT: the system color of text in a window.
COLOR_GRAYTEXT
pub const COLOR_GRAYTEXT: int32 = 17;
COLOR_GRAYTEXT: the system color of text that is shown but not active.
MB_OK
pub const MB_OK: uint32 = 0x00000000;
MB_OK: the message box has one OK button.
MB_ICONERROR
pub const MB_ICONERROR: uint32 = 0x00000010;
MB_ICONERROR: the message box shows the error icon.
SWP_NOMOVE
pub const SWP_NOMOVE: uint32 = 0x0002;
SWP_NOMOVE: SetWindowPos keeps the window where it is and ignores x and y.
SWP_NOZORDER
pub const SWP_NOZORDER: uint32 = 0x0004;
SWP_NOZORDER: SetWindowPos keeps the window's place in the stacking order and ignores insertAfter.
SWP_NOACTIVATE
pub const SWP_NOACTIVATE: uint32 = 0x0010;
SWP_NOACTIVATE: SetWindowPos does not activate the window.
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.
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.
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.
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.
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
Parameters
| Name | Type | Description |
|---|---|---|
rect | *var Rect | the client rectangle on entry, and the window rectangle on return |
style | uint32 | the window's WS_ style |
menu | bool32 | non-zero when the window has a menu bar |
exStyle | uint32 | the window's extended style |
dpi | uint32 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window being painted |
paint | *var PaintStruct | receives 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
Parameters
| Name | Type | Description |
|---|---|---|
exStyle | uint32 | the extended style bits, usually zero |
className | *char16 | the NUL-terminated UTF-16 name of a registered class |
windowName | *char16 | the NUL-terminated UTF-16 title, or null |
style | uint32 | the WS_ style bits, combined with | |
x | int32 | the left edge, or CW_USEDEFAULT |
y | int32 | the top edge, or CW_USEDEFAULT |
width | int32 | the width, or CW_USEDEFAULT |
height | int32 | the height, or CW_USEDEFAULT |
parent | *var opaque | the parent or owner window, HWND_MESSAGE for a message-only window, or null |
menu | *var opaque | the menu, or for a child window its identifier, or null |
instance | *var opaque | the module the class was registered by |
parameter | *var opaque | a 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window the message is for |
message | uint32 | the message number |
wParam | uint | the first message parameter |
lParam | int | the 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the 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
Parameters
| Name | Type | Description |
|---|---|---|
message | *Message | a 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window being painted |
paint | *PaintStruct | the 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
rect | *var Rect | receives 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the 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
Parameters
| Name | Type | Description |
|---|---|---|
message | *var Message | receives the message |
window | *var opaque | the window to take messages for, or null for every window of the thread |
filterMin | uint32 | the lowest message number to take, or zero for no filter |
filterMax | uint32 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
index | int32 | a 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
Parameters
| Name | Type | Description |
|---|---|---|
index | int32 | a 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
rect | *Rect | the part to mark, or null for the whole client area |
erase | bool32 | non-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
Parameters
| Name | Type | Description |
|---|---|---|
instance | *var opaque | the module holding the cursor, or null for a system cursor |
name | *char16 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
instance | *var opaque | the module holding the icon, or null for a system icon |
name | *char16 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the owner window, or null |
text | *char16 | the NUL-terminated UTF-16 message |
caption | *char16 | the NUL-terminated UTF-16 title, or null for "Error" |
style | uint32 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
exitCode | int32 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
windowClass | *WindowClassEx | what 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
message | uint32 | the message number |
wParam | uint | the first message parameter |
lParam | int | the 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
Parameters
| Name | Type | Description |
|---|---|---|
context | *var opaque | a 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
insertAfter | *var opaque | the window to place it after, ignored with SWP_NOZORDER |
x | int32 | the new left edge |
y | int32 | the new top edge |
width | int32 | the new width |
height | int32 | the new height |
flags | uint32 | SWP_ 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
text | *char16 | the 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
command | int32 | an 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
Parameters
| Name | Type | Description |
|---|---|---|
message | *Message | a 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
Parameters
| Name | Type | Description |
|---|---|---|
className | *char16 | the NUL-terminated UTF-16 class name |
instance | *var opaque | the 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
Parameters
| Name | Type | Description |
|---|---|---|
window | *var opaque | the window |
Returns: non-zero on success, and zero on failure