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.

By the end of this guide you will have a working X11 window containing a text label and a clickable button. You will understand how to register elements by ID, attach an event callback, and run the frame loop — the three concepts that underpin every LWXGL application. No prior Xlib knowledge is required.

​
Complete Example

Save the following file as hello.c: 
#include <stdio.h>
#include <libLWXGL.h>

/* Button click callback — called by LWXGL when the button is pressed */
void on_click(void) {
    printf("Button clicked!\n");
}

int main(void) {
    /* Open a 400×300 window titled "Hello LWXGL" with a black background.
       Returns 0 on success, non-zero on failure.                          */
    int rc = CreateWindow(
        400,          /* window width  in pixels */
        300,          /* window height in pixels */
        "Hello LWXGL",/* title bar text           */
        CLR_BLACK     /* background palette index */
    );
    if (rc != 0) return rc;

    /* Create a button (element ID 0).
       Parameters: id, x, y, width, height,
                   normal color, hover color, pressed color,
                   label text, click callback.              */
    CreateButton(
        0,            /* element ID               */
        100, 120,     /* top-left corner (x, y)   */
        160, 30,      /* width, height in pixels  */
        CLR_GRAY,     /* normal background color  */
        CLR_LGRAY,    /* hover  background color  */
        CLR_BLUE,     /* pressed background color */
        "Click me",   /* label text               */
        on_click      /* callback function        */
    );

    /* Create a text label (element ID 1).
       Parameters: id, x, y, text, color.  */
    CreateText(
        1,            /* element ID               */
        100, 90,      /* position (x, y)          */
        "Hello, LWXGL!", /* string to display      */
        CLR_WHITE     /* text palette color       */
    );

    /* Enter the main loop at 60 fps.
       NULL means no per-frame callback. Blocks until window is closed. */
    MainWindowLoop(60, NULL);

    /* Release all X11 resources and close the display connection */
    TerminateWindow();
    return 0;
}

​
Compile and Run

gcc hello.c -o hello -lLWXGL -lX11 -lGL
./hello
A 400×300 window will appear with the text “Hello, LWXGL!” above a gray button. Clicking the button prints Button clicked! to stdout. Close the window to exit.

​
How the Loop Works

MainWindowLoop is a blocking call that drives the entire application lifecycle. Internally, each iteration:
  1. Processes X11 events — mouse moves, button presses, key presses, and the window-close protocol are all dispatched here. If a mouse click lands inside a button’s bounding box, the button’s onclick callback is invoked immediately.
  2. Calls on_every (if non-NULL) — your per-frame callback receives the current tick counter (int) and the delta time since the last frame in seconds (float). This is where you would update game state, call Immediate* drawing functions, or modify element properties.
  3. Renders all visible elements onto the back-buffer pixmap in their registered order, then blits the finished frame to the visible window in one atomic operation.
  4. Sleeps for the remainder of the frame budget so that CPU usage scales with target_fps rather than spinning at 100%.
The loop exits as soon as the window’s close button is clicked. After MainWindowLoop returns, call TerminateWindow to free every element, release the 16 allocated Xlib colors, destroy the back-buffer pixmap, and close the display connection.
Element IDs are global. If you call CreateButton(0, ...) and later CreateText(0, ...), the second call overwrites element slot 0 without warning. Use distinct IDs for every element in your application.
To run logic every frame — for example, to animate an element’s position — pass a callback as the second argument to MainWindowLoop:
void every_frame(int tick, float dt) {
    /* dt is the elapsed time in seconds since the previous frame */
    ElemModifyBounds(0, 100 + tick % 80, 120, 160, 30);
}

MainWindowLoop(60, every_frame);

​
Next Steps

Window Management

Learn the full CreateWindow return codes, SetWindowTitle, EnableResizing, scrolling, and the modal dialog API.

Elements

Explore every retained element type: buttons, inputs, images, consoles, checkboxes, OpenGL surfaces, and more.

Color Palette

Understand the 16-color palette, all CLR_* constants, and how to customise colors at runtime with PaletteModify.

Events

Attach keyboard and mouse callbacks, query real-time input state, and handle window-close events gracefully.

Build docs developers (and LLMs) love

Get started for freeTalk to us