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 (Lightweight X11 Graphics Library) is a minimal C shared library (libLWXGL.so) that wraps Xlib with a clean procedural API for building X11 GUI desktop applications on Linux. Rather than exposing raw Xlib types, LWXGL gives you a simple set of G-prefixed functions for creating windows, adding UI widgets, drawing primitives, and reacting to input events — all without a toolkit framework or widget hierarchy. Every on-screen element is identified by an integer ID that you assign, making element management predictable and straightforward in both C and C++.

​
How It Works

LWXGL is built around three core concepts: the element ID system, the render loop, and double-buffered rendering.

​
Element ID System

Every widget — buttons, text labels, input fields, checkboxes, rectangles, image canvases, and consoles — is registered under an integer ID that you choose. When you call a creation function such as GCreateButton(1, ...), the 1 is your handle for that element from that point on. You use the same ID to query state (GGetInput(1)), modify bounds (GElemModifyBounds(1, ...)), toggle visibility (GElemSetVisible(1, 0)), or destroy the element (GDeleteElement(1)). You are responsible for keeping IDs unique within a window. There is no global registry — if you assign the same ID twice, the second call will overwrite the first.

​
The Render Loop

Every frame, your application must call two functions in order:
  1. GHandleWindowEvents() — drains the Xlib event queue, dispatches keyboard and mouse events to any registered callbacks, and handles WM close requests.
  2. GRenderWindow() — composites all visible elements onto the backbuffer, then blits it to the screen.
The convenience wrapper GSimpleWindowLoop(int target_fps, void (*on_every)(int tick, float delta)) runs this pair in a capped loop at the requested frame rate, calling your on_every callback once per frame with the tick count and delta time in seconds. The loop exits automatically when GWindowShouldClose() returns non-zero.

​
Double-Buffered Rendering

All drawing happens onto an off-screen Xlib Pixmap (the backbuffer bb) that is the same size as the window. At the end of each GRenderWindow() call, the completed backbuffer is blitted to the visible window in a single XCopyArea operation. This eliminates tearing and partial-frame flicker that would occur with direct on-screen drawing.

​
Key Features

Window Management

Open, title, resize, and close an X11 window with a single call. Supports WM delete-window protocol, optional resizing callbacks, and runtime title changes.

UI Widgets

Built-in support for buttons, text labels, single-line text inputs, checkboxes, filled rectangles, and scrollable consoles — each controlled by a simple integer ID.

Image Canvas & Primitives

Create pixel-addressable image canvases and draw onto them with GPrimitiveRect, GPrimitiveCircle, GPrimitiveLine, and GPrimitiveSprite. Render text into a canvas with GDrawString.

Event Callbacks

Attach callbacks for keyboard events (GEventAttachKey), mouse clicks (GEventAttachClick), and WM close (GEventAttachDelete). Query live mouse state with GQueryMouse and keyboard state with GQueryKeyDown.

16-Color Palette

All colors are palette indices (0–15). The default palette covers black, white, and 14 additional colors. Inspect colors with GPaletteQuery, swap entries at runtime with GPaletteModify, and restore defaults with GPaletteReset.

Virtual Screens

Group elements onto named virtual screens with GScreenApply and switch the active screen with GScreenActive. Only elements assigned to the active screen are rendered, enabling lightweight multi-view UIs.

​
What You Need

LWXGL has minimal dependencies. Before you build or link against it, make sure you have:
  • Linux with a running X11 display server (the DISPLAY environment variable must be set).
  • libx11-dev (Debian/Ubuntu) or libX11-devel (Fedora/RHEL) — the Xlib development headers and shared library.
  • g++ (GCC C++ compiler) to compile the library itself. Your application can be written in C and compiled with gcc.
  • libLWXGL.so installed to a location on the dynamic linker’s search path (typically /usr/local/lib after sudo make install).
LWXGL’s public header libLWXGL.h uses an extern "C" guard, so you can include it from both C and C++ source files without any changes.

​
Next Steps

Quickstart

Build and run your first LWXGL window with a button, text label, and keyboard handler in under five minutes.

Building & Installing

Compile libLWXGL.so from source, install it system-wide, and verify the installation with a smoke test.

Build docs developers (and LLMs) love

Get started for freeTalk to us