API Reference

Every symbol a program uses, exported from cl-windowing and cl-windowing/vulkan. Symbols for writing backends are on Backend Protocol. Every function's docstring says the same in more detail: (describe 'win:adopt-window-size).

Thread rules for everything here: process-events runs on one thread at a time; everything else may be called from any thread. An event struct belongs to the thread that polls into it. See Threads.

Window systems

window-system (class)

A connection to a window system, made by open-window-system. Each backend has a subclass.

open-window-system

(open-window-system &rest options &key backend &allow-other-keys) => window-system

Connects with backend, by default the platform's: :win32 on Windows and :wayland elsewhere. The other options go to the backend. Signals no-backend-error or window-system-error. See Window Systems and Windows.

close-window-system

(close-window-system window-system) => (no values)

Destroys its windows and disconnects, even when the connection has failed. Signals closed-error if it is closed already.

with-window-system (macro)

(with-window-system (variable &rest options) &body body)

Binds variable to (open-window-system ,@options) and closes it however body is left, unless body closed it.

process-events

(process-events window-system &key (timeout 0)) => count

Waits at most timeout seconds for the window system (0 does not wait, nil waits until something arrives), handles what arrived and returns the number of events queued. Call it regularly, from one thread. Signals window-system-error when the connection has failed. See Events.

poll-event

(poll-event window-system event) => boolean

Copies the oldest queued event into event and returns true, or returns false if none is queued. Never waits; allocates nothing.

Window system accessors

Function	Returns
(window-system-backend ws)	The backend's keyword, such as :wayland.
(window-system-open-p ws)	True until it is closed.
(window-system-windows ws)	A fresh list of its windows that are alive, popups included.
(window-system-capabilities ws)	A list of :server-side-decorations, :fractional-scale, :clipboard, :pointer-capture, :keyboard, :pointer. See Capabilities.

clipboard-text, (setf clipboard-text)

(clipboard-text window-system &key (timeout 1)) => string or nil
(setf (clipboard-text window-system) text) => text

The text on the clipboard, with #\Newline ending lines, or nil if it holds none, or if the program whose text it is does not send it within timeout seconds. Setting it puts text there for this and other programs to paste. Do both in answer to the user: on Wayland, setting it signals window-system-error while none of the window system's windows has the keyboard focus. On Windows, both signal window-system-error while the session is locked. See Clipboard.

Windows

window (class)

A window: a top-level window, made by create-window, a dialog of another if made with :parent, or a popup, made by create-popup. Each backend has a subclass.

create-window

(create-window window-system &key (title "") (width 800) (height 600) app-id parent modal)
=> window

Creates a top-level window, asking for width by height units. app-id, a string such as "org.example.Editor", names the application to the window system. The window appears once something is drawn in it, which may happen only after window-configured-p is true. With parent, another top-level window, it is a dialog of it: it stays above the parent, opens over it, and is destroyed with it. With modal true too, the parent and its popups get no input that starts there while it is open; releases still come. Signals dialog-error for modal without parent, or a parent that is a popup or of another window system, and closed-error on a closed window system or a destroyed parent. See Dialogs.

destroy-window

(destroy-window window) => (no values)

Destroys the window, and first its popups and dialogs, the newest first, even when the connection has failed. Destroy anything drawing into them first. Signals closed-error if it is destroyed already.

with-window (macro)

(with-window (variable window-system &rest options) &body body)

Binds variable to (create-window window-system ,@options) and destroys it however body is left, unless body destroyed it.

window-title, (setf window-title)

(window-title window) => string
(setf (window-title window) title) => title

The window's title. Setting it sends it to the window system at once.

window-configured-p

(window-configured-p window) => boolean

True once the window system has proposed the window's first size. Nothing may be drawn before; until then window-pixel-size is 0 by 0.

window-size

(window-size window) => width, height

The size in units, as last adopted, or as asked for until the window is configured. Pointer positions use the same units.

window-scale

(window-scale window) => scale

How many pixels a frame has per unit, as last adopted: 1, 2, 3/2 and so on.

window-pixel-size

(window-pixel-size window) => width, height

The size of the window's frames in pixels: size times scale, rounded to the nearest pixel. 0 and 0 until the window is configured, when nothing may be drawn in it yet.

window-pending-size

(window-pending-size window) => width, height, scale  ; or NIL, NIL, NIL

The size in units and the scale the window system has proposed and adopt-window-size has not taken. Cheap; allocates nothing.

window-pending-pixel-size

(window-pending-pixel-size window) => width, height  ; or NIL, NIL

The pending size in pixels: the size of the next frames while a proposal is pending. Cheap; allocates nothing.

adopt-window-size

(adopt-window-size window) => width, height

Takes the pending size and scale, if any, and tells the window system that the next frame follows them. Call it just before presenting the first frame at the new size. Returns the size in units. Allocates nothing. Signals closed-error on a destroyed window. See Resizing and Scaling.

set-window-size

(set-window-size window width height) => boolean

Asks the window system to make the window width by height units and returns true. The size comes as one the window system proposes, with a :resize event, and window-size stays the old size until it is adopted. Returns nil, asking nothing, while the window system sizes the window itself: on Windows while it is maximised, minimised or fullscreen, and on Wayland while it is maximised, fullscreen or tiled, or the user is resizing it. See Resizing and Scaling.

window-fullscreen-p, (setf window-fullscreen-p)

(window-fullscreen-p window) => boolean
(setf (window-fullscreen-p window) fullscreen) => boolean

True while the window is fullscreen, as the window system last said. Setting it asks the window system to make a top-level window fullscreen on the display it is on, or as it was before; the size it gives comes as a :resize event. Signals popup-error for a popup. See Window Systems and Windows.

window-cursor, (setf window-cursor)

(window-cursor window) => cursor
(setf (window-cursor window) cursor) => cursor

The look of the pointer while it is over the window, a cursor, :default at first. Takes effect at once; cheap when unchanged, so it may be set on every pointer motion. See Cursors and Pointer Modes.

window-pointer-mode, (setf window-pointer-mode)

(window-pointer-mode window) => pointer-mode
(setf (window-pointer-mode window) mode) => mode

How the pointer is held over the window: :free, the default, :confined or :captured. Lasts until it is set again; the window system holds the pointer only while the window has the focus. Signals unsupported-error for :confined or :captured where window-system-capabilities has no :pointer-capture. See Cursors and Pointer Modes.

window-decorations

(window-decorations window) => :server-side or :none

Who draws the title bar and borders: the window system, or nobody yet.

Other window accessors

Function	Returns
(window-window-system window)	The window system it belongs to.
(window-alive-p window)	True until it is destroyed.
(window-popups window)	Its popups that are alive, oldest first.
(window-dialogs window)	Its dialogs that are alive, oldest first.
(window-parent window)	The window it was made on: a dialog's parent, or a popup's; nil for a window of its own.
(window-modal-p window)	True for a modal dialog.

Popups

popup (class)

A window made on another, its parent, for a menu, a list to choose from or a tooltip. It is placed against a rectangle of its parent, stays above it, and is a window like any other. See Popups.

create-popup

(create-popup parent width height
              &key (rectangle '(0 0 0 0)) (anchor :bottom-left) (popup-anchor :top-left)
                   (offset-x 0) (offset-y 0) (adjustments '(:flip-x :flip-y :slide-x :slide-y))
                   grab (pointer-input t))
=> popup

Creates a popup on parent, asking for width by height units, with its popup-anchor point at the anchor point of rectangle, (x y width height) in the parent's coordinates, moved by offset-x and offset-y. Where it would not fit, the window system moves it as adjustments allow. With grab, it grabs the keyboard, as a menu does, and the window system may dismiss it; make it in answer to a button or key press. With pointer-input false, the pointer goes through it. The parent must have been drawn. Signals popup-error when a popup that grabs is made anywhere but on the newest popup that grabs, or on a top-level window while none grabs.

reposition-popup

(reposition-popup popup width height &key rectangle anchor popup-anchor
                                          offset-x offset-y adjustments)
=> (no values)

Places the popup again, asking for width by height units, with the placement's arguments given and the others as they were. A new size comes as a :resize event. On Wayland it needs xdg_wm_base version 3 or later; signals popup-error otherwise.

place-rectangle

(place-rectangle width height bounds
                 &key (rectangle '(0 0 0 0)) (anchor :bottom-left) (popup-anchor :top-left)
                      (offset-x 0) (offset-y 0) (adjustments '(:flip-x :flip-y :slide-x :slide-y)))
=> x, y, width, height

Returns where a popup of width by height units goes within bounds, (x y width height), placed against rectangle and moved to fit as create-popup's arguments of the same names say: for popups a program draws itself inside one of its windows. The rectangle is rounded out to whole units and cut to the bounds; the results are whole units. See Popups.

Popup accessors

Function	Returns
(popup-parent popup)	The window it was made on, as window-parent says.
(popup-grab-p popup)	True if it grabs the keyboard.
(popup-pointer-input-p popup)	True if it takes the pointer; false if the pointer goes through it.
(popup-position popup)	Two values: its left and top in its parent's coordinates, as last placed; 0 and 0 until then.
(popup-placement popup)	Where it was last asked to go, as create-popup's keyword arguments, in a plist.
(popup-dismissed-p popup)	True once the window system has dismissed it, as a :close event told. Destroy it then.

Input methods

See Input Methods.

Function	Does
(start-text-input window)	Has the window take text from the input method, as when a text field gains the focus.
(stop-text-input window)	Stops it, dropping text being composed, with a :preedit of "" if there was some, and forgetting the caret and surrounding text.
(set-text-input-caret window x y width height)	Tells the input method where the caret is, a rectangle in the window's coordinates. Cheap when unchanged.
(set-text-input-surrounding window text cursor &optional (anchor cursor))	Tells it the text around the caret, without the text being composed, and the caret's character index in it; anchor is the selection's other end. Cheap when unchanged. Windows' input methods are not told it.
(text-input-active-p window)	True between start-text-input and stop-text-input.
(text-input-caret window)	Four values: the caret last given, or four nils.
(text-input-surrounding window)	Three values: the text, cursor and anchor last given, or three nils.

Events

event (struct)

An event, filled in by poll-event. Make one with make-event and reuse it. A program reads events; backends write them, so the readers' setf writers are exported for backends, and for tests that stand in for one. See Events.

make-event

(make-event) => event

copy-event

(copy-event from to) => to

Copies every field of the event from into the event to, the text into to's own string: to keep an event past the next poll-event, or to hand it on. Allocates nothing unless the text is longer than to's string has room for.

Event readers

Reader	Returns
(event-type event)	An event-type: what the event reports.
(event-window event)	The window it concerns.
(event-width event), (event-height event)	:resize: the new size in units.
(event-scale event)	:resize: the new scale.
(event-key event)	Key events: the physical key.
(event-symbol event)	Key events: the logical key, or nil.
(event-scancode event)	Key events: the platform's code for the key.
(event-repeat-p event)	:key-press: true for a repeat of a held key.
(event-text event)	:text: the text typed or chosen. :preedit: the text being composed. Reused by the next poll-event; copy it to keep it.
(event-caret-start event), (event-caret-end event)	:preedit: the input method's caret in the text, or nil.
(event-delete-before event), (event-delete-after event)	:delete-surrounding: the characters to delete before and after the caret.
(event-button event)	Button events: the button.
(event-x event), (event-y event)	Pointer, button and scroll events: the pointer's position in units.
(event-dx event), (event-dy event)	:pointer-motion: how far the pointer moved, in units; while it is captured, the device's own motion.
(event-scroll-x event), (event-scroll-y event)	:scroll: steps right and down.

event-modifier-p

(event-modifier-p event modifier) => boolean

True if modifier was in effect when the event happened. For key, pointer, button and scroll events. Allocates nothing.

event-modifiers

(event-modifiers event) => mask

The modifiers in effect when the event happened, as a mask of modifier-bit bits. For key, pointer, button and scroll events; 0 for others. setf sets it, for a backend or a test that fills an event.

Types

event-type

(member :resize :close :focus-in :focus-out :key-press :key-release :text :pointer-enter :pointer-leave :pointer-motion :button-press :button-release :scroll :preedit :delete-surrounding). See Events.

key

A keyword naming a key by its place on a US keyboard, or :unknown. See Key Names.

button

(or (member :left :right :middle :back :forward) (integer 0)).

modifier

(member :shift :control :alt :super :caps-lock :num-lock).

scale

(rational (0)): a positive rational, such as 1, 2 or 3/2.

cursor

A keyword naming the pointer's look as CSS names cursors, such as :default, :text, :pointer or :ew-resize, or :hidden. See Cursors and Pointer Modes for them all.

pointer-mode

(member :free :confined :captured).

rectangle

(x y width height), a list of four reals, its width and height at least 0: the rectangle of a parent that create-popup, reposition-popup and place-rectangle place popups against, and place-rectangle's bounds.

popup-point

(member :top-left :top :top-right :left :center :right :bottom-left :bottom :bottom-right): a point of a rectangle.

popup-adjustment

(member :flip-x :flip-y :slide-x :slide-y :resize-x :resize-y): a way the window system may move a popup that would not fit.

Conditions

Condition	Reader	Signalled when
windowing-error		The base of all of them.
window-system-error	window-system-error-message	The window system cannot be reached, or the connection failed.
no-backend-error	no-backend-error-backend	The backend asked for, or the platform's, is not loaded.
popup-error	popup-error-message	A popup asked for breaks the window system's rules.
dialog-error	dialog-error-message	A dialog asked for cannot be made: modal without a parent, or its parent a popup or of another window system.
unsupported-error	unsupported-error-message	The window system cannot do what was asked.
closed-error	closed-error-object	A closed window system or a destroyed window was used.

See Errors.

cl-windowing/vulkan

vulkan-instance-extensions

(cl-windowing/vulkan:vulkan-instance-extensions window-system) => list of strings

The Vulkan instance extensions that surfaces of the window system need, for cl-vk:create-instance's :extensions.

create-vulkan-surface

(cl-windowing/vulkan:create-vulkan-surface window instance) => cl-vk:surface

Creates a Vulkan surface for window from instance. Destroy it with cl-vk:destroy-surface before the window. Size its swapchain by window-pixel-size, and by window-pending-pixel-size while a size is pending. Present nothing before window-configured-p is true. Signals cl-vk:unsupported-error if the instance lacks an extension, and closed-error for a destroyed window. See Vulkan Surfaces.