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 page you will have a running LWXGL application that opens a 640×400 X11 window, displays a text label, and shows a clickable button — all from a single C source file. The complete example is under 25 lines and requires no build system beyond a single gcc invocation.

​
Build a Hello World Window

1

Include the header and set up your compile command

LWXGL’s entire public API is exposed through one header. Add it to your source file:
#include <libLWXGL.h>
Compile your program by linking against -lLWXGL:
gcc -o hello hello.c -lLWXGL
No additional -I or -L flags are needed when LWXGL is installed to the default system paths via make install.
2

Create the window

Call GCreateWindow before doing anything else. It opens the X11 display connection, allocates the palette colors, and maps a fixed-size window on screen:
if (GCreateWindow(640, 400, "Hello LWXGL", 0) != 0) {
    return 1;
}
The four parameters are:
ParameterTypeDescription
wintWindow width in pixels
hintWindow height in pixels
nameconst char*Window title bar text
bgcolintBackground color palette index (0–15)
GCreateWindow returns 0 on success. Other return values indicate a specific failure:
  • 1 — No X11 display available ($DISPLAY not set or server unreachable)
  • 2 — Required bitmap font (9x15) could not be loaded
  • 3 — A window is already open (only one window is supported at a time)
3

Add UI elements

UI elements are identified by an integer id you assign. Add a text label and a button:
GCreateText(0, 20, 20, 15, "Hello, World!");
GCreateButton(1, 20, 60, 120, 30, 0x70, 0x80, 0x90, "Click Me", on_click);
GCreateText(id, x, y, color, text) — renders a static text string at position (x, y) in the given palette color index.GCreateButton(id, x, y, w, h, u, hvr, p, label, onclick) — creates a labeled button with three packed color bytes for its visual states and a callback function pointer.

​
Packed color byte format

The u, hvr, and p parameters each encode two palette indices in a single byte using the nibble convention used throughout LWXGL:
  • High nibble (>> 4): border / outline color index
  • Low nibble (& 0x0F): fill / background color index
For example:
ValueHigh nibbleLow nibbleMeaning
0x707 = Light Gray0 = BlackLight gray border, black fill
0x808 = Dark Gray0 = BlackDark gray border, black fill (hover)
0x909 = Light Blue0 = BlackLight blue border, black fill (pressed)
The three states map to: u = unpressed/idle, hvr = mouse hover, p = mouse pressed.
4

Run the frame-capped loop

GSimpleWindowLoop drives the entire event-dispatch and render cycle at the requested frame rate. It blocks until the window is closed:
GSimpleWindowLoop(60, NULL);
  • First argument: target frames per second (here, 60 FPS)
  • Second argument: optional void (*on_every)(int tick) callback invoked once per frame. Pass NULL if you have no per-frame logic.
Press F12 at runtime to toggle the debug overlay. It shows the live FPS counter and a rolling 60-frame chart of per-frame work time in microseconds — useful for identifying frame budget problems.
5

Clean up

After GSimpleWindowLoop returns (the user closed the window), release all X11 resources:
GTerminateWindow();
This frees all elements, the graphics context, the double-buffer pixmap, the palette color allocations, and closes the display connection.

​
Complete Example

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

void on_click(void) {
    printf("Button clicked!\n");
}

int main(void) {
    if (GCreateWindow(640, 400, "Hello LWXGL", 0) != 0) {
        return 1;
    }

    GCreateText(0, 20, 20, 15, "Hello, World!");
    GCreateButton(1, 20, 60, 120, 30, 0x70, 0x80, 0x90, "Click Me", on_click);

    GSimpleWindowLoop(60, NULL);
    GTerminateWindow();
    return 0;
}
Compile and run: 
gcc -o hello hello.c -lLWXGL
./hello
You should see a black 640×400 window titled Hello LWXGL with a white “Hello, World!” label and a “Click Me” button. Clicking the button prints Button clicked! to your terminal. Close the window to exit.
Next, read the Core Concepts to understand the window lifecycle, color palette, and element system in depth.

Build docs developers (and LLMs) love

Get started for freeTalk to us