This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

API Reference

Every exported symbol of the package cl-win32, by topic. Every function declaims the full domain of its arguments, and SBCL signals a type-error for one outside it, before Windows is called, and warns of a constant one when it compiles the call. A window, an event or a cursor is a handle but not 0; a position in pixels is a 32-bit signed integer, and a width or a height one that is not negative. The keywords that name something, such as a style or a command, are types, such as window-style and show-command: a keyword of none of them is refused, with the valid ones in the error. Each of these types is also a cl-ffi enum or bitfield of its C values, for bindings of one's own.

• Basics
• Event objects
• Window procedures and classes
• Windows
• Displays and DPI
• Messages
• Keyboard and pointer
• Input methods
• The clipboard

Basics

handle type

A Win32 handle, such as a window or an event, as an integer: (unsigned-byte 64) on x86-64. 0 is no handle.

win32-error condition

Signalled when a Win32 function fails. Subtype of error. Reports as Function failed with Windows error code: description. See Errors.

win32-error-function condition → string

The Win32 function that failed, such as "CreateWindowExW".

win32-error-code condition → (unsigned-byte 32)

Windows' error code, as GetLastError returns it.

win32-error-message condition → string

Windows' description of the error code.

module-handle → handle

The module handle (HINSTANCE) of the executable: the Lisp running.

current-thread-id → (unsigned-byte 32)

Windows' identifier of the calling thread.

low-word value → (unsigned-byte 16)

Bits 0–15 of value, a wparam or lparam, as LOWORD.

high-word value → (unsigned-byte 16)

Bits 16–31 of value, as HIWORD.

signed-low-word value → (signed-byte 16)

Bits 0–15 of value as a signed integer, as GET_X_LPARAM.

signed-high-word value → (signed-byte 16)

Bits 16–31 of value as a signed integer, as GET_Y_LPARAM and GET_WHEEL_DELTA_WPARAM.

make-lparam low high → (unsigned-byte 32)

The parameter with low in its low word and high in its high word, as MAKELPARAM. Negative words are taken as 16-bit two's complement.

Event objects

See Event Objects. Events may be used from any thread.

make-event &key manual-reset signalled → handle

A new event object. Auto-reset unless manual-reset; unsignalled unless signalled. Release it with close-event.

set-event event → (no values)

Signal event. Allocates nothing.

reset-event event → (no values)

Unsignal event.

wait-for-event event &optional timeout → boolean

Wait at most timeout seconds, a non-negative real, or forever if nil, the default, for event to be signalled. True if it was, false if the time ran out.

close-event event → (no values)

Release event, which may no longer be used.

with-event (var &rest options) &body body macro

Evaluate body with var bound to an event made with options, as make-event takes them, and close it afterwards.

Window procedures and classes

See Window Procedures and Classes.

define-window-procedure name (window message wparam lparam) &body body macro

Define name as a window procedure, and as a function of the four arguments that the procedure calls. body returns the message's result, an integer, or nil for the default handling. It may start with a documentation string and declarations. It must not leave by a non-local exit; an error it signals is caught, the message gets the default handling, and the error is signalled again from the cl-win32 call during which Windows called the procedure.

default-window-procedure window message wparam lparam → (signed-byte 64)

Handle message for window the default way, as DefWindowProcW.

register-window-class name procedure &key styles (cursor :arrow) → (unsigned-byte 16)

Register the window class name, a string, whose window procedure is procedure, a symbol naming one defined with define-window-procedure, and return its atom.

• styles: a list of class-style keywords.
• cursor: :arrow, or nil to leave the cursor to the window procedure.

class-style type

A class style: :own-dc, :double-clicks, :horizontal-redraw, :vertical-redraw or :no-close, the CS_ bits.

unregister-window-class name → (no values)

Unregister the window class name, whose windows have all been destroyed.

Windows

See Windows.

create-window class &key (title "") (styles '(:overlapped-window)) extended-styles (x :default) (y :default) (width :default) (height :default) parent → handle

Create a window of the class class, belonging to the calling thread.

• styles: a list of window-style keywords, which combine as their bits do.
• extended-styles: a list of extended-window-style keywords.
• x, y, width, height: in pixels, frame included, or :default.
• parent: a window, or for a :popup window its owner, which it stays above and goes with; :message for a message-only window; or nil.

window-style type

A window style, one of the WS_ bits: :overlapped-window, :overlapped, :popup, :child, :visible, :disabled, :clip-siblings, :clip-children, :caption, :border, :system-menu, :thick-frame, :minimize-box, :maximize-box, :minimize or :maximize.

extended-window-style type

An extended window style, one of the WS_EX_ bits: :topmost, :tool-window, :app-window, :no-redirection-bitmap or :no-activate.

destroy-window window → (no values)

Destroy window, which must belong to the calling thread.

window-p object → boolean

True if object is the handle of a window that exists.

window-enabled-p window → boolean

True if window takes input from the mouse and keyboard, as it does unless disabled. setf it to nil to disable the window, as a modal dialog disables its owner while it is open, and to true to enable it again: Windows activates no disabled window and gives it no input, while its owned windows keep theirs.

show-window window &optional (command :show) → boolean

Show, hide, minimise or maximise window: command is a show-command. True if it was visible before.

show-command type

A command of show-window, one of the SW_ values: :show, :show-normal, :show-no-activate, :show-minimized, :hide, :minimize, :maximize or :restore.

window-text window → string

The text of window: a top-level window's title. setf-able.

client-size window → width, height

The size of window's client area, in pixels.

window-bounds window → left, top, width, height

window's place on the screen and its size, frame included, in pixels.

set-window-bounds window &key x y width height → (no values)

Move and size window, frame included, in pixels, without activating it or changing its order. x and y go together, as do width and height, and one without the other signals a type-error; what is left out stays as it is.

change-window-styles window &key add remove → (no values)

Give window the window styles add and take away remove, lists of window-style keywords, keeping the rest, and have Windows draw its frame anew. The window keeps its bounds, so its client area changes size, which +wm-size+ tells.

window-placement window → left, top, width, height, maximized-p, minimized-p

Where window is when neither minimised nor maximised, in workspace coordinates; whether it is maximised, or is to be when restored if it is minimised; and whether it is minimised. Give it back to set-window-placement as it came.

set-window-placement window x y width height &key maximized minimized → (no values)

Place window at x, y, width by height when neither minimised nor maximised, and show it: maximised if maximized; minimised if minimized, and then maximised when restored if maximized too; otherwise there. Shown there or minimised it is not activated; shown maximised it is.

window-thread-id window → (unsigned-byte 32)

The identifier of the thread window belongs to.

validate-window window → (no values)

Mark all of window as painted.

read-rect address → left, top, right, bottom

Read the RECT at address, such as +wm-dpichanged+'s lparam.

Displays and DPI

See DPI.

+default-dpi+ constant

96: the DPI of a display at 100%.

set-thread-dpi-awareness awareness → (no values)

Set the calling thread's DPI awareness, a dpi-awareness, for the windows it creates from then on. Windows 10 version 1607 or later.

dpi-awareness type

A thread's awareness of displays' DPI, one of the DPI_AWARENESS_CONTEXT values: :per-monitor-aware-v2, :per-monitor-aware, :system-aware, :unaware or :unaware-gdi-scaled.

window-dpi window → (integer 1)

The DPI of the display window is on.

display-bounds window → left, top, width, height

All of the display that has the largest part of window, or of the display nearest it, taskbar included, in pixels: what a fullscreen window covers.

display-work-area x y width height → left, top, width, height

The work area of the display that has the largest part of the rectangle at x, y of width by height on the screen, or of the display nearest it: the part windows may cover, without the taskbar. To keep a window, such as a menu, on the screen.

window-size-for-client-size width height &key (styles '(:overlapped-window)) extended-styles (dpi 96) → width, height

The size of a window with styles and extended-styles, on a display of dpi, whose client area is width by height pixels.

Messages

See Messages and Message Loops.

Message constants

+wm-null+, +wm-create+, +wm-destroy+, +wm-move+, +wm-size+, +wm-activate+, +wm-setfocus+, +wm-killfocus+, +wm-settext+, +wm-gettext+, +wm-paint+, +wm-close+, +wm-quit+, +wm-erasebkgnd+, +wm-showwindow+, +wm-setcursor+, +wm-getminmaxinfo+, +wm-windowposchanging+, +wm-windowposchanged+, +wm-nccreate+, +wm-ncdestroy+, +wm-keydown+, +wm-keyup+, +wm-char+, +wm-deadchar+, +wm-syskeydown+, +wm-syskeyup+, +wm-syschar+, +wm-sysdeadchar+, +wm-syscommand+, +wm-mousemove+, +wm-lbuttondown+, +wm-lbuttonup+, +wm-lbuttondblclk+, +wm-rbuttondown+, +wm-rbuttonup+, +wm-mbuttondown+, +wm-mbuttonup+, +wm-mousewheel+, +wm-xbuttondown+, +wm-xbuttonup+, +wm-mousehwheel+, +wm-capturechanged+, +wm-entersizemove+, +wm-exitsizemove+, +wm-mouseleave+, +wm-dpichanged+, +wm-activateapp+, +wm-mouseactivate+, +wm-nchittest+, +wm-nclbuttondown+, +wm-ncrbuttondown+, +wm-ncmbuttondown+, +wm-ncxbuttondown+, +wm-input+, +wm-ime-setcontext+, +wm-ime-startcomposition+, +wm-ime-composition+, +wm-ime-endcomposition+, +wm-user+, +wm-app+: the WM_ messages. Each docstring says what the parameters hold.

+size-restored+, +size-minimized+, +size-maximized+: +wm-size+'s wparam. +wheel-delta+: 120, a wheel notch. +xbutton1+, +xbutton2+: the extra buttons, in wparam's high word. +ma-noactivate+: an answer to +wm-mouseactivate+, not to be activated. +htclient+: the client area, in +wm-setcursor+'s lparam and as an answer to +wm-nchittest+; +httransparent+: an answer to +wm-nchittest+, to let the pointer through. +gcs-compstr+, +gcs-resultstr+: in +wm-ime-composition+'s lparam, the text being composed and the text chosen. +isc-showuicompositionwindow+: in +wm-ime-setcontext+'s lparam, the input method's own composition window.

post-message window message &optional (wparam 0) (lparam 0) → (no values)

Put message on the queue of window's thread, and return. Any thread.

send-message window message &optional (wparam 0) (lparam 0) → (signed-byte 64)

Call window's procedure with message, on window's thread, wait, and return its result.

post-quit-message &optional (code 0) → (no values)

End the calling thread's message loop with code, after the messages before.

run-message-loop → (signed-byte 32)

Hand the calling thread's messages to their window procedures, waiting for them, until post-quit-message; return its code. Translates key messages. Signals errors from window procedures right after their message. Allocates nothing per message.

process-messages → quit-p, code

Hand over the messages waiting, without waiting for more. t and the code if the quit message came, nil otherwise.

peek-message &key (window 0) (first 0) (last 0) → message, wparam, lparam, time

The next message waiting for the calling thread, without taking it, or nil. window, if not 0, and first and last, if not both 0, narrow which messages count.

message-time → (unsigned-byte 32)

The time of the message being handled, in milliseconds since Windows started.

message-position → x, y

Where the pointer was on the screen, in pixels, as of the message being handled: for a message that carries no position, such as +wm-capturechanged+, where it was when the thread last took a message from its queue. Unlike cursor-position, it cannot fail.

Keyboard and pointer

See Keyboard and Pointer.

virtual-key type

A virtual key's name: :shift, :lcontrol, :return, :f1, :numpad0, :oem-plus, :key-a, :key-0 and so on.

virtual-key-name code → virtual-key or nil

The name of the virtual key code. Allocates nothing.

virtual-key-code key → (unsigned-byte 8)

The code of key, a name, or a code already. Allocates nothing.

key-state key → down-p, toggled-p

Whether key, a name or a code, is down and toggled on, as of the message being handled.

map-virtual-key code translation → (unsigned-byte 32)

Translate code for the calling thread's keyboard layout, or 0: translation is a key-translation. Allocates nothing.

key-translation type

A translation of map-virtual-key, one of the MAPVK_ values: :virtual-key-to-scancode, :virtual-key-to-scancode-ex, :scancode-to-virtual-key, :scancode-to-virtual-key-ex or :virtual-key-to-character.

track-pointer-leave window → (no values)

Have +wm-mouseleave+ posted once the pointer leaves window.

set-capture window → (no values)

Send the pointer's messages to window until release-capture. window must belong to the calling thread.

release-capture → (no values)

End the capture.

capture → handle or nil

The calling thread's window that has the capture.

screen-to-client window x y → x, y

A screen position in window's client coordinates, in pixels.

system-metric metric → (signed-byte 32)

The system metric metric, a system-metric-name.

system-metric-name type

A system metric, one of the SM_ indices: :screen-width, :screen-height, :mouse-present, :mouse-buttons, :mouse-wheel-present or :swap-buttons.

client-to-screen window x y → x, y

The position x, y in window's client coordinates, on the screen.

system-cursor name → handle

The system cursor name, a system-cursor-name, in the user's cursor scheme. Shared: never destroy one. Allocates nothing, so a window procedure may call it for each +wm-setcursor+.

system-cursor-name type

A system cursor, one of the IDC_ numbers: :arrow, :ibeam, :hand, :wait, :app-starting, :cross, :up-arrow, :help, :no, :size-all, :size-we, :size-ns, :size-nwse or :size-nesw.

set-cursor cursor → handle or nil

Show cursor, from system-cursor, or hide the pointer for nil; return the cursor shown before. A window procedure keeps its own cursor by calling it for +wm-setcursor+ when lparam's low word is +htclient+, and returning 1. Call it from the thread of the window the pointer is over.

cursor-position → x, y

Where the pointer is on the screen, in pixels.

set-cursor-position x y → (no values)

Move the pointer to x, y on the screen, or as near as clip-cursor allows. Move it only as the user asks.

clip-cursor &optional x y width height → (no values)

Keep the pointer within the rectangle on the screen, or let it go anywhere when given none; some of the four without the others signal a type-error. Let it go before another program has the focus.

cursor-clip → left, top, width, height

The rectangle the pointer is kept within: all of the screens while nothing keeps it.

register-raw-mouse window → (no values)

Have the mice send their raw motion to window as +wm-input+ while the program is in the foreground. The program has one such window, the last registered.

unregister-raw-mouse → (no values)

Stop the mice sending raw input.

raw-mouse-motion input → dx, dy

How far a mouse moved across and down, in its own counts, by the raw input input, a +wm-input+'s lparam; nil and nil if it is not a mouse's relative motion. Allocates nothing.

Input methods

See Input Methods and the Clipboard. Call these from the window's thread.

enable-input-method window → (no values)

Let the input method compose text for window, as while one of its text fields has the keyboard focus. A window's input method is enabled when it is made.

disable-input-method window → (no values)

Keep the input method from composing text for window, so keys reach it as they are typed. Text being composed is dropped.

input-method-enabled-p window → boolean

True if the input method composes text for window.

input-method-composition window → text, caret

The text window's input method is composing, and the index of its caret in it: "" and 0 if it composes nothing. Read it when +wm-ime-composition+ comes with +gcs-compstr+.

input-method-result window → string

The text the user chose, or "". Read it when +wm-ime-composition+ comes with +gcs-resultstr+, and answer the message yourself, or Windows sends the text again as +wm-char+.

set-input-method-caret window x y width height → (no values)

Tell the input method where the caret is, as a rectangle in client pixels: its candidate list goes beside it. Does nothing while the input method is disabled.

input-method-caret window → x, y, width, height

The rectangle set-input-method-caret gave last, or nils while the input method is disabled.

cancel-input-method-composition window → (no values)

Drop the text being composed, if any.

The clipboard

clipboard-text window &key (timeout 1) → string or nil

The text on the clipboard, or nil if it holds none, opening the clipboard for window. CR LF between lines is kept. While another program has the clipboard open, tries again for up to timeout seconds, then signals win32-error, as also while the session is locked.

(setf clipboard-text) text window &key (timeout 1)

Put text on the clipboard, in place of what it held, with window as its owner. Windows expects CR LF between lines. Waits and signals as clipboard-text does.