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.

This guide walks you through everything you need to get a working LWXGL application on screen. By the end you will have opened a 640×480 window, displayed a text label, added a clickable button, attached a keyboard handler, and learned how to exit cleanly. No prior Xlib experience is required.
1

Install LWXGL

Clone the repository and build the shared library, then install it system-wide:
git clone https://github.com/DRessedAlarm184/LWXGL.git
cd LWXGL
make build
sudo make install
make build runs the following compiler invocation:
g++ -fPIC -shared -O2 -o libLWXGL.so src/main.cc -lX11 -fvisibility=hidden
sudo make install then places the files where the system linker can find them:
cp libLWXGL.so /usr/local/lib
cp src/libLWXGL.h /usr/local/include
ldconfig
You need libx11-dev (Debian/Ubuntu) or libX11-devel (Fedora/RHEL) installed before building. See Building & Installing for the full dependency setup.
2

Create your source file

Create a file called hello.c with the following content:
#include <libLWXGL.h>
#include <stdio.h>

/* Called when the button is clicked */
void on_click(void) {
    printf("Button clicked!\n");
}

/* Called for every key press; key is the ASCII code or an LWXGL_KEY_* constant */
void on_key(int key) {
    printf("Key pressed: %d\n", key);
}

/* Called once per frame by GSimpleWindowLoop.
   tick  - frame counter starting at 0
   dt    - seconds elapsed since the previous frame */
void on_frame(int tick, float dt) {
    /* Per-frame game/app logic goes here */
    (void)tick; (void)dt;
}

int main(void) {
    /* Open a 640x480 window titled "Hello LWXGL".
       The last argument is the background palette index (0 = black). */
    if (GCreateWindow(640, 480, "Hello LWXGL", 0) != 0) {
        fprintf(stderr, "Failed to open window\n");
        return 1;
    }

    /* Add a white text label at (20, 30).
       GCreateText(id, x, y, color_index, text)
       id=0, color index 15 = white */
    GCreateText(0, 20, 30, 15, "Hello from LWXGL!");

    /* Add a button at (20, 60), 120px wide, 28px tall.
       GCreateButton(id, x, y, w, h, normal_color, hover_color, press_color, label, callback)
       Color values pack two palette nibbles: upper nibble = border, lower = fill.
       0x78 -> border=palette[7] (white), fill=palette[8] (dark grey)  - normal
       0x79 -> border=palette[7], fill=palette[9]                       - hover
       0x7A -> border=palette[7], fill=palette[10]                      - pressed */
    GCreateButton(1, 20, 60, 120, 28, 0x78, 0x79, 0x7A, "Click Me", on_click);

    /* Attach a keyboard handler */
    GEventAttachKey(on_key);

    /* Run the event+render loop at 60 fps, calling on_frame each tick.
       The loop blocks until GWindowShouldClose() is true. */
    GSimpleWindowLoop(60, on_frame);

    /* Free all resources and close the X11 connection */
    GTerminateWindow();
    return 0;
}
3

Compile and link

gcc -o hello hello.c -lLWXGL
The system linker will find libLWXGL.so in /usr/local/lib (added to the cache by ldconfig). No -L flag is needed after a system-wide install.
4

Run it

./hello
A 640×480 window appears with the text label and button. Click the button or press any key to see output in your terminal.
5

Stop the window

Close the window using your window manager’s close button (the ✕ title-bar control). This triggers the WM delete-window protocol, which sets the close flag and causes GSimpleWindowLoop to return, at which point GTerminateWindow() cleans up all X11 resources.
Understanding LWXGL colorsLWXGL uses a 16-entry palette for all colors. Index 0 is Black and index 15 is White; indices 1–14 cover a range of standard colors. You can inspect any entry with GPaletteQuery(idx, &r, &g, &b) and override entries at runtime with GPaletteModify.Button state colors (u, hvr, p) pack two palette nibbles into a single byte:
  • Upper nibble — border/outline color index
  • Lower nibble — fill color index
For example, 0x78 means border = palette[7], fill = palette[8]. This applies to the normal (u), hover (hvr), and pressed (p) states independently, so you can change both border and fill on hover or press.

​
What’s Next

UI Elements

Explore every widget type — inputs, checkboxes, image canvases, consoles, primitives, and virtual screens.

Events & Input

Learn how to handle keyboard and mouse events, query live input state, use modal dialogs, and intercept the WM close request.

Build docs developers (and LLMs) love

Get started for freeTalk to us