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.

The events API lets you attach callbacks for user input and query the real-time state of the mouse and keyboard. Callbacks are registered once before the render loop and are invoked automatically by GHandleWindowEvents as matching X11 events arrive. Query functions (GQueryMouse, GQueryKeyboard, GQueryKeyDown) can be called at any time — including inside GSimpleWindowLoop’s on_every callback — to poll current device state.

​
GEventAttachKey

void GEventAttachKey(void (*Key)(int key));
Registers a callback invoked on every key-down event that is not consumed by a focused element (input fields and consoles handle key events internally and stop propagation). The callback receives the character code of the pressed key.
​
Key
void (*)(int key)
required
Callback function. key is the ASCII code for printable characters, or one of the LWXGL key constants for non-printable keys (see below). A value of 0 is never delivered.
Key constants 
#define LWXGL_KEY_LEFT   170   // Left arrow
#define LWXGL_KEY_RIGHT  171   // Right arrow
#define LWXGL_KEY_UP     172   // Up arrow
#define LWXGL_KEY_DOWN   173   // Down arrow
#define LWXGL_KEY_FN     150   // Base value for function keys
                               // F1 = 151, F2 = 152, … F12 = 162
F-key codes are calculated as LWXGL_KEY_FN + n where n is the function-key number (1–12). For example, F1 produces code 151 and F12 produces 162.
F12 is reserved. Pressing F12 toggles the built-in debug performance overlay and is never forwarded to the Key callback. Ctrl+Escape is also reserved and triggers GDeleteWindow.
void on_key(int key) {
    if (key == 'q') GDeleteWindow();
    if (key == LWXGL_KEY_LEFT)  move_left();
    if (key == LWXGL_KEY_RIGHT) move_right();
}
GEventAttachKey(on_key);

​
GEventAttachClick

void GEventAttachClick(void (*Click)(int x, int y, int btn));
Registers a callback invoked on mouse button release events that are not consumed by an element (buttons, checkboxes, and consoles intercept clicks that land inside their bounds). The callback is also suppressed while a modal dialog is open.
​
Click
void (*)(int x, int y, int btn)
required
Callback function. x and y are the window-relative pixel coordinates of the cursor at the time of release. btn is the X button number: 1 = left, 2 = middle, 3 = right.
void on_click(int x, int y, int btn) {
    if (btn == 1) {
        place_tile(x, y);
    }
}
GEventAttachClick(on_click);

​
GEventAttachDelete

void GEventAttachDelete(int (*on_exit)());
Registers a callback invoked when the window manager’s close button is clicked (the WM_DELETE_WINDOW client message). The return value of the callback controls whether the close is allowed.
​
on_exit
int (*)()
required
Callback function. Return 1 to allow the window to close (sets the closing flag). Return 0 to block the close — the window remains open and the render loop continues.
int on_exit(void) {
    if (has_unsaved_changes()) {
        GSpawnModal(1, "Unsaved changes. Really quit?", save_and_quit);
        return 0; // block the close for now
    }
    return 1; // allow close immediately
}
GEventAttachDelete(on_exit);

​
GEnableResizing

void GEnableResizing(void (*Resize)(int w, int h));
Registers a resize callback and removes the fixed-size WM hints, allowing the user to freely resize the window. The callback fires after the back-buffer pixmap has already been recreated at the new dimensions, so it is safe to call any LWXGL drawing function from inside the callback. See the Window API for the full description.
​
Resize
void (*)(int w, int h)
required
Callback function. w and h are the new window dimensions in pixels.

​
GQueryMouse

void GQueryMouse(int* x, int* y, int* btn);
Fills the three output pointers with the current mouse state as tracked by the most recently processed motion and button events. Safe to call at any point in the frame, including inside the on_every callback of GSimpleWindowLoop.
​
x
int*
required
Receives the cursor’s current X position in window-relative pixels. Set to -1 when the cursor is outside the window.
​
y
int*
required
Receives the cursor’s current Y position in window-relative pixels. Set to -1 when the cursor is outside the window.
​
btn
int*
required
Receives the currently pressed button number (1=left, 2=middle, 3=right), or 0 if no button is pressed. Only one button is tracked at a time; the first button pressed takes precedence until it is released.
int mx, my, mbtn;
GQueryMouse(&mx, &my, &mbtn);
if (mbtn == 1 && mx >= 0) {
    draw_brush(mx, my);
}

​
GQueryKeyboard

unsigned char* GQueryKeyboard(void);
Returns a pointer to the internal 8-element pressed_keys array. Each slot holds the character code of a currently held key, or 0 if that slot is empty. LWXGL tracks up to 8 simultaneous key presses. Character codes use the same values delivered to the GEventAttachKey callback, including the LWXGL key constants for arrow and function keys. The returned pointer is valid for the lifetime of the window. Do not free it. 
unsigned char* keys = GQueryKeyboard();
for (int i = 0; i < 8; i++) {
    if (keys[i] != 0) printf("held: %d\n", keys[i]);
}

​
GQueryKeyDown

int GQueryKeyDown(int ch);
Returns 1 if the key with character code ch is currently held down, 0 otherwise. Equivalent to scanning the full GQueryKeyboard array for ch, but more convenient for checking individual keys.
​
ch
int
required
Character code to test. Use ASCII values for printable characters or the LWXGL key constants for arrows and function keys.
void on_every(int tick, float dt) {
    if (GQueryKeyDown(LWXGL_KEY_LEFT))  player_x -= 2;
    if (GQueryKeyDown(LWXGL_KEY_RIGHT)) player_x += 2;
    if (GQueryKeyDown(LWXGL_KEY_UP))    player_y -= 2;
    if (GQueryKeyDown(LWXGL_KEY_DOWN))  player_y += 2;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us