Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DRESsedAlarm184/LWXGL/llms.txt

Use this file to discover all available pages before exploring further.

LWXGL uses a callback registration model for input events. Each event type has a single slot; calling the same EventAttach* function again replaces the previous handler. Callbacks are invoked from within the main window loop — you do not need to poll a queue manually. All callbacks registered here are blocked while a modal dialog is open, with the exception of EventAttachDelete (which is still processed if Ctrl+Escape is pressed).

​
EventAttachKey

void EventAttachKey(void (*Key)(int key));
Registers a callback to be invoked whenever a key press event is received. LWXGL calls XkbSetDetectableAutoRepeat(display, True, NULL) during window creation, which enables detectable auto-repeat — the X server sends real KeyPress events for every repeated key while it is held. The callback is therefore invoked on every auto-repeat event, not just on the initial press. Use QueryKeyDown in the per-frame callback if you only want to act on the held state without receiving repeated callbacks. The key argument passed to the callback is an ASCII value for printable characters, or one of the following constants for special keys:
ConstantValueKey
KEY_LEFT170Left arrow
KEY_RIGHT171Right arrow
KEY_UP172Up arrow
KEY_DOWN173Down arrow
KEY_FN + 1151F1
KEY_FN + 2152F2
………
KEY_FN + 12162F12
\n (10)10Enter / Return
Two key combinations are consumed internally and never forwarded to the callback:
  • Ctrl+Escape — triggers DeleteWindow() (window close)
  • F12 — toggles the debug overlay
​
Key
void (*)(int key)
required
Callback function. Receives the key value as described above.
Key callbacks fire before the per-frame callback. If a modal is open, Key is not called — modal input is handled internally.

​
EventAttachClick

void EventAttachClick(void (*Click)(int x, int y, int btn));
Registers a callback to be invoked on mouse button release. The callback receives the cursor’s window coordinates and the button identifier.
btnButton
1Left
2Middle
3Right
4Scroll wheel up
5Scroll wheel down
The click callback is not called in any of these situations:
  • A modal dialog is currently open
  • The release occurred over a button element (the button’s own onclick handler fires instead)
  • The release occurred over a checkbox element (the checkbox toggle fires instead)
  • Scroll wheel events (4/5) over a console element or when window scroll is enabled
​
Click
void (*)(int x, int y, int btn)
required
Callback function. x and y are window-relative cursor coordinates; btn is the button identifier.

​
EventAttachDelete

void EventAttachDelete(int (*on_exit)());
Registers a callback to be invoked when the window manager sends a WM_DELETE_WINDOW message or when Ctrl+Escape is pressed. The callback must return an integer:
ReturnEffect
1Close is confirmed — window exits on the next loop iteration
0Close is cancelled — window remains open
If no delete handler is registered, the window always closes immediately.
​
on_exit
int (*)()
required
Callback function. Return 1 to allow the window to close, 0 to prevent it.

​
EventAttachResize

void EventAttachResize(void (*Resize)(int w, int h));
Registers a callback to be invoked after the window is resized. Only fires when FLAG_RESIZE was passed to CreateWindow. The callback receives the new window dimensions in pixels. Resize events are coalesced — if multiple ConfigureNotify events are queued, only the final dimensions are delivered.
​
Resize
void (*)(int w, int h)
required
Callback function. w and h are the new window width and height in pixels.
After a resize you typically need to recreate or resize image elements to match the new window dimensions. Call ElemModifyBounds or recreate with CreateImage using w = 0, h = 0 to auto-fit.

​
Scroll Event

The scroll event is not registered through a standalone EventAttach* function. Instead, it is provided as the third argument to ReserveScroll, which must be called before CreateWindow: 
void ReserveScroll(int height, int scrollbar_color, void (*Scroll)(int offset));
The Scroll callback is invoked whenever the scroll offset changes — either from the user scrolling with the mouse wheel or from a window resize that adjusts the scroll clamp.
ArgumentMeaning
heightTotal virtual canvas height in pixels
scrollbar_colorTwo palette indices packed into one byte: low nibble (L) = track background fill color; high nibble (H) = thumb fill color. Pass CLR_NONE (-1) to hide the scrollbar entirely.
Scrollvoid (*)(int offset) — called with the new scroll offset in pixels
See also QueryScroll() for polling the current offset without a callback.

​
Code Example

#include "libLWXGL.h"
#include <stdio.h>

void on_key(int key) {
    if (key == KEY_UP)    printf("Up arrow\n");
    if (key == KEY_DOWN)  printf("Down arrow\n");
    if (key >= 32 && key < 127)
        printf("Char: %c\n", (char)key);
}

void on_click(int x, int y, int btn) {
    printf("Click at (%d, %d) button %d\n", x, y, btn);
}

int on_delete(void) {
    // Show a confirm modal instead of closing immediately
    SpawnModal(MODAL_CONFIRM, "Really quit?", NULL);
    return 0; // cancel close; user must re-trigger
}

void on_resize(int w, int h) {
    // Re-fit the canvas image to the new window size
    ElemModifyBounds(1, 0, 0, w, h);
}

int main(void) {
    EventAttachKey(on_key);
    EventAttachClick(on_click);
    EventAttachDelete(on_delete);
    EventAttachResize(on_resize);

    CreateWindow(640, 480, "Events Demo", CLR_BLACK, FLAG_RESIZE);
    CreateImage(1, 0, 0, 640, 480);

    MainWindowLoop(60, NULL);
    TerminateWindow();
    return 0;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us