windows/user32 · Standard Library · MPL Reference

Windows User32 declarations for windows, classes, messages, monitors, placement, cursor and capture control, device contexts, and pointer-sized values.

Known issue: with -32bits, importing windows/user32 fails to compile at the GetWindowLongPtrW and SetWindowLongPtrW aliases, so this module and windows/gdi32, windows/opengl32, and windows/shell32, which import it, are unavailable for 32-bit targets.

Schemas

`WNDPROC`

(-- WNDPROC) Defines a window-procedure callback schema.

codeRef schema

Field	Schema	Role
`hwnd`	`HWND`	target window handle
`uMsg`	`Nat32`	message identifier
`wParam`	`Natx`	pointer-sized message parameter
`lParam`	`Intx`	pointer-sized message parameter

Callback stack effect: (lParam wParam uMsg hwnd -- result); result: Intx message-processing result.

`HCURSOR`

(-- HCURSOR) Aliases the icon-handle schema for cursor handles.

`HBRUSH`

(-- HBRUSH) Defines a typed brush handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`BRUSH`	`Tuple`	Virtual brush marker.
`unused`	`Int32`	unused storage field

`HDC`

(-- HDC) Defines a typed device-context handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`DC`	`Tuple`	Virtual device-context marker.
`unused`	`Int32`	unused storage field

`HGLRC`

(-- HGLRC) Defines a typed OpenGL rendering-context handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`GLRC`	`Tuple`	Virtual OpenGL rendering-context marker.
`unused`	`Int32`	unused storage field

`HICON`

(-- HICON) Defines a typed icon handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`ICON`	`Tuple`	Virtual icon marker.
`unused`	`Int32`	unused storage field

`HMENU`

(-- HMENU) Defines a typed menu handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`MENU`	`Tuple`	Virtual menu marker.
`unused`	`Int32`	unused storage field

`HMONITOR`

(-- HMONITOR) Defines a typed monitor handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`MONITOR`	`Tuple`	Virtual monitor marker.
`unused`	`Int32`	unused storage field

`HWND`

(-- HWND) Defines a typed window handle.

Cref schema for a Dict-shaped opaque handle

Field	Schema	Role
`WND`	`Tuple`	Virtual window marker.
`unused`	`Int32`	unused storage field

`MONITORINFO`

(-- MONITORINFO) Defines monitor information returned by GetMonitorInfoW.

Dict schema

Field	Schema	Role
`cbSize`	`Nat32`	size of this structure in bytes
`rcMonitor`	`RECT`	monitor display rectangle in virtual-screen coordinates
`rcWork`	`RECT`	monitor work-area rectangle in virtual-screen coordinates
`dwFlags`	`Nat32`	monitor state flags

`MSG`

(-- MSG) Defines a queued window message.

Dict schema

Field	Schema	Role
`hwnd`	`HWND`	window associated with the message
`message`	`Nat32`	message identifier
`wParam`	`Natx`	pointer-sized message parameter
`lParam`	`Intx`	pointer-sized message parameter
`time`	`Nat32`	posting time in milliseconds since the system started
`pt`	`POINT`	cursor position in screen coordinates when the message was posted

`POINT`

(-- POINT) Defines a two-dimensional coordinate.

Dict schema

Field	Schema	Role
`x`	`Int32`	horizontal coordinate
`y`	`Int32`	vertical coordinate

`RECT`

(-- RECT) Defines a rectangular coordinate range.

Dict schema

Field	Schema	Role
`left`	`Int32`	left coordinate
`top`	`Int32`	top coordinate
`right`	`Int32`	right coordinate
`bottom`	`Int32`	bottom coordinate

`WINDOWPLACEMENT`

(-- WINDOWPLACEMENT) Defines a window placement record.

Dict schema

Field	Schema	Role
`length`	`Nat32`	native structure size in bytes
`flags`	`Nat32`	placement flags
`showCmd`	`Nat32`	show-state command
`ptMinPosition`	`POINT`	minimized position
`ptMaxPosition`	`POINT`	maximized position
`rcNormalPosition`	`RECT`	normal window rectangle
`rcDevice`	`RECT`	device rectangle

ptMinPosition, ptMaxPosition, and rcNormalPosition are in workspace coordinates for a top-level window without the WS_EX_TOOLWINDOW extended style, and in screen coordinates otherwise.

Known issue: this binding includes rcDevice, which the Windows layout lacks, so the record occupies 60 bytes instead of the native 44; GetWindowPlacement and SetWindowPlacement fail unless length is set to 44n32.

`WNDCLASSW`

(-- WNDCLASSW) Defines a wide-character window-class description.

Dict schema

Field	Schema	Role
`style`	`Nat32`	class style flags
`lpfnWndProc`	`WNDPROC`	window-procedure callback
`cbClsExtra`	`Int32`	extra class bytes
`cbWndExtra`	`Int32`	extra window bytes
`hInstance`	`HINSTANCE`	module instance handle
`hIcon`	`HICON`	class icon handle
`hCursor`	`HCURSOR`	class cursor handle
`hbrBackground`	`HBRUSH`	class background brush handle
`lpszMenuName`	`Natx`	zero-terminated UTF-16 menu-resource-name address, encoded menu identifier, or `0nx`
`lpszClassName`	`Natx`	zero-terminated UTF-16 class-name address or registered-class atom

Imported functions

Stack effects list a C function's parameters with the first parameter on top; see importFunction.

`ClientToScreen`

(lpPoint hWnd -- result) Converts a client-area point to screen coordinates.

Inputs

lpPoint: POINT Ref caller-owned writable point storage; the call updates it.
hWnd: HWND window whose client area contains the point.

Outputs

result: Int32 nonzero on success, 0 on failure.

`CreateWindowExW`

(lpParam hInstance hMenu hWndParent nHeight nWidth Y X dwStyle lpWindowName lpClassName dwExStyle -- result) Creates an overlapped, pop-up, or child window.

Inputs

lpParam: Natx address of creation data, or 0nx for none.
hInstance: HINSTANCE module instance associated with the window class.
hMenu: HMENU menu handle or child-window identifier.
hWndParent: HWND parent or owner window handle.
nHeight: Int32 window height.
nWidth: Int32 window width.
Y: Int32 initial vertical position.
X: Int32 initial horizontal position.
dwStyle: Nat32 window style flags.
lpWindowName: Natx address of the zero-terminated UTF-16 window-name string.
lpClassName: Natx address of a zero-terminated UTF-16 class-name string, or a registered-class atom in the low-order 16 bits with all other bits zero.
dwExStyle: Nat32 extended window style flags.

Outputs

result: HWND created window handle, or NIL on failure.

`DefWindowProcW`

(lParam wParam Msg hWnd -- result) Provides default processing for a window message.

Inputs

lParam: Intx pointer-sized message parameter.
wParam: Natx pointer-sized message parameter.
Msg: Nat32 message identifier.
hWnd: HWND window handle receiving the message.

Outputs

result: Intx default message-processing result.

`DestroyWindow`

(hWnd -- result) Destroys a window.

Inputs

hWnd: HWND window handle to destroy.

Outputs

result: Int32 nonzero on success, 0 on failure.

`DispatchMessageW`

(lpMsg -- result) Dispatches a message to its window procedure.

Inputs

lpMsg: MSG Cref borrowed message record to dispatch.

Outputs

result: Intx value returned by the window procedure.

`GetDC`

(hWnd -- result) Retrieves a device context for a window.

Inputs

hWnd: HWND window handle, or a NIL HWND for the entire screen.

Outputs

result: HDC device-context handle, or NIL on failure.

Remarks

A common device context requires the Windows ReleaseDC function on the acquiring thread; this module provides no ReleaseDC binding.

`GetMonitorInfoW`

(lpmi hMonitor -- result) Retrieves information about a display monitor.

Inputs

lpmi: MONITORINFO Ref caller-owned writable monitor-information storage with cbSize set to its size; the call fills it.
hMonitor: HMONITOR monitor handle.

Outputs

result: Int32 nonzero on success, 0 on failure.

`GetWindowLongPtrW`

(nIndex hWnd -- result) Retrieves a pointer-sized value from a window.

Inputs

nIndex: Int32 window-value index.
hWnd: HWND window handle.

Outputs

result: Intx requested window value, or 0ix on failure; 0ix can also be a valid value.

Remarks

When the Natx does not occupy 8 bytes, GetWindowLongPtrW aliases GetWindowLongW.

`GetWindowLongW`

(nIndex hWnd -- result) Retrieves a value from a window.

Inputs

nIndex: Int32 window-value index.
hWnd: HWND window handle.

Outputs

result: Intx requested window value, or 0ix on failure; 0ix can also be a valid value.

Remarks

GetWindowLongW is available only when the Natx does not occupy 8 bytes; GetWindowLongPtrW aliases it.

`GetWindowPlacement`

(lpwndpl hWnd -- result) Retrieves a window placement record.

Inputs

lpwndpl: WINDOWPLACEMENT Ref caller-owned writable placement storage with length set to 44n32; the call fills it.
hWnd: HWND window handle.

Outputs

result: Int32 nonzero on success, 0 on failure.

`LoadCursorW`

(lpCursorName hInstance -- result) Loads a cursor.

Inputs

lpCursorName: Natx address of a zero-terminated UTF-16 cursor-name string, or a cursor resource identifier in the low-order 16 bits with all other bits zero.
hInstance: HINSTANCE module instance handle, or a NIL HINSTANCE for a system cursor.

Outputs

result: HCURSOR cursor handle, or NIL on failure.

`MonitorFromWindow`

(dwFlags hwnd -- result) Retrieves the display monitor associated with a window.

Inputs

dwFlags: Nat32 monitor-selection flags.
hwnd: HWND window handle.

Outputs

result: HMONITOR monitor handle, or NIL only when the window intersects no monitor and dwFlags is 0n32.

`PeekMessageW`

(wRemoveMsg wMsgFilterMax wMsgFilterMin hWnd lpMsg -- result) Retrieves a message without waiting for one.

Inputs

wRemoveMsg: Nat32 message-removal flags.
wMsgFilterMax: Nat32 maximum message value in the filter range.
wMsgFilterMin: Nat32 minimum message value in the filter range.
hWnd: HWND window filter handle, or a NIL HWND for no window filter.
lpMsg: MSG Ref caller-owned writable message storage; the call fills it.

Outputs

result: Int32 nonzero when a message is retrieved, 0 when none is available.

`RegisterClassW`

(lpWndClass -- result) Registers a window class.

Inputs

lpWndClass: WNDCLASSW Cref borrowed window-class description.

Outputs

result: Nat16 atom identifying the registered class, or 0n16 on failure.

`ReleaseCapture`

(-- result) Releases mouse capture from the current window.

Inputs

None.

Outputs

result: Int32 nonzero on success, 0 on failure.

`SetCapture`

(hWnd -- result) Sets mouse capture to a window.

Inputs

hWnd: HWND window handle to receive mouse input.

Outputs

result: HWND previous capture window handle, or NIL if none.

`SetCursorPos`

(Y X -- result) Moves the cursor to a screen coordinate.

Inputs

Y: Int32 screen vertical coordinate.
X: Int32 screen horizontal coordinate.

Outputs

result: Int32 nonzero on success, 0 on failure.

`SetWindowLongPtrW`

(dwNewLong nIndex hWnd -- result) Sets a pointer-sized value in a window.

Inputs

dwNewLong: Intx new pointer-sized window value.
nIndex: Int32 window-value index.
hWnd: HWND window handle.

Outputs

result: Intx previous window value, or 0ix on failure; 0ix can also be a valid previous value.

Remarks

When the Natx does not occupy 8 bytes, SetWindowLongPtrW aliases SetWindowLongW.
Clear the thread's last-error code with the Windows SetLastError function before the call; a zero result indicates failure only if GetLastError then returns a nonzero code.

`SetWindowLongW`

(dwNewLong nIndex hWnd -- result) Sets a value in a window.

Inputs

dwNewLong: Intx new window value.
nIndex: Int32 window-value index.
hWnd: HWND window handle.

Outputs

result: Intx previous window value, or 0ix on failure; 0ix can also be a valid previous value.

Remarks

SetWindowLongW is available only when the Natx does not occupy 8 bytes; SetWindowLongPtrW aliases it.

`SetWindowPlacement`

(lpwndpl hWnd -- result) Sets a window placement record.

Inputs

lpwndpl: WINDOWPLACEMENT Cref borrowed placement record with length set to 44n32.
hWnd: HWND window handle.

Outputs

result: Int32 nonzero on success, 0 on failure.

`SetWindowPos`

(uFlags cy cx Y X hWndInsertAfter hWnd -- result) Changes a window position, size, or z-order.

Inputs

uFlags: Nat32 positioning flags.
cy: Int32 new window height.
cx: Int32 new window width.
Y: Int32 new vertical position.
X: Int32 new horizontal position.
hWndInsertAfter: HWND z-order placement window handle.
hWnd: HWND window handle to position.

Outputs

result: Int32 nonzero on success, 0 on failure.

`ShowCursor`

(bShow -- result) Changes the cursor display counter.

Inputs

bShow: Int32 nonzero to increment the display counter, or 0 to decrement it.

Outputs

result: Int32 new cursor display-counter value.

Remarks

The cursor is displayed only when the counter is nonnegative.

`ShowWindow`

(nCmdShow hWnd -- result) Sets a window show state.

Inputs

nCmdShow: Int32 show-state command.
hWnd: HWND window handle.

Outputs

result: Int32 nonzero if the window was previously visible, 0 if it was previously hidden.

`TranslateMessage`

(lpMsg -- result) Translates a virtual-key message.

Inputs

lpMsg: MSG Cref borrowed message record to translate.

Outputs

result: Int32 nonzero for WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, regardless of whether a character message is posted; 0 otherwise.

Signature examples

Printing imported names during compilation shows the exact imported signatures.

"control"        use
"windows/user32" use

{} Int32 {} [
  @CreateWindowExW printStack _:;
  @GetWindowLongPtrW printStack _:;
  @GetDC printStack _:;
  0
] "main" exportFunction

Expected Output During Compilation

{dwExStyle: Nat32; lpClassName: Natx; lpWindowName: Natx; dwStyle: Nat32; X: Int32; Y: Int32; nWidth: Int32; nHeight: Int32; hWndParent: {WND: (); unused: Int32;} Cref; hMenu: {MENU: (); unused: Int32;} Cref; hInstance: {INSTANCE: (); unused: Int32;} Cref; lpParam: Natx;} {WND: (); unused: Int32;} Cref {convention: "";} codeRef
{hWnd: {WND: (); unused: Int32;} Cref; nIndex: Int32;} Intx {convention: "";} codeRef
{hWnd: {WND: (); unused: Int32;} Cref;} {DC: (); unused: Int32;} Cref {convention: "";} codeRef

See also

windows/kernel32: Kernel32 declarations for synchronization, process, thread, file, and timing helpers.
windows/gdi32: GDI32 pixel-format and buffer-swap declarations.
windows/opengl32: OpenGL32 WGL context declarations.
windows/shell32: Shell folder path declarations.
windows/unicode: UTF-8 to zero-terminated UTF-16 conversion helper.