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 C shared library that makes it practical to build native Linux desktop GUI applications without reaching for a full widget toolkit. It wraps Xlib’s verbose, low-level API into a concise flat C interface — no classes, no callbacks to register against objects, no heavyweight framework to link against. You get a single .so and a single header, and you own the event loop.

​
What problem does it solve?

Writing directly against Xlib means managing display connections, graphics contexts, double-buffering, colormap allocation, font loading, and event dispatch yourself — thousands of lines of boilerplate before a window even appears. LWXGL handles all of that internally, exposing only the operations an application actually needs: create a window, place widgets, run the loop. At the same time, LWXGL deliberately avoids the complexity of toolkits like GTK or Qt. There is no object system, no build-time code generation, no mandatory runtime. If your program calls CreateWindow and MainWindowLoop, you are done. The tradeoff is intentional: LWXGL is the right choice for small utilities, game UIs, embedded panels, and learner projects — not for building a web browser.

​
Architecture overview

your application
      │
      │  #include <libLWXGL.h>
      │  -lLWXGL
      ▼
  libLWXGL.so          ← single shared library, flat C API
      │
      ▼
   Xlib (libX11)       ← only external dependency
      │
      ▼
  X11 server / display
LWXGL is distributed as a single compiled shared object (libLWXGL.so) paired with one header (libLWXGL.h). The header is the entire public API — there are no sub-headers, no generated code, and no pkg-config files to manage. The only external dependency is libX11; LWXGL links against it at build time so your application does not need to.

​
Key design decisions

ID-based element system. Every widget — text labels, buttons, input fields, images, rectangles, checkboxes — is identified by an integer id that you assign at creation. There are no handles or pointer types to manage. DeleteElement(id) removes any element regardless of type, and ElemSetVisible(id, 0) hides it without destroying it. 16-color indexed palette. All colors are expressed as 4-bit indices into a fixed 16-entry palette modelled on the classic CGA/VGA palette. The constants CLR_BLACK through CLR_WHITE cover all 16 values. The palette can be queried, modified per-index with PaletteModify, or reset to defaults with PaletteReset. Multi-color widget states (normal, hover, pressed) pack two color indices into one byte — the low nibble is the fill color, the high nibble is the border color. Frame-rate-controlled main loop. MainWindowLoop(target_fps, on_every) drives everything. The loop measures elapsed time with std::chrono::steady_clock, sleeps between frames, and invokes your optional per-frame callback with the current tick counter and delta time in seconds. All Xlib event processing and widget rendering happen inside the loop; you never call XNextEvent yourself. Double-buffered rendering. All drawing goes to an off-screen Pixmap (the back-buffer) and is presented atomically each frame, eliminating flicker without any effort on your part. Canvas mode and scroll. Passing FLAG_CANVAS to CreateWindow allocates a full-window image element at id 0 that you can draw into with primitive operations and pixel manipulation functions. FLAG_RESIZE permits the window to be resized by the user. ReserveScroll (called before CreateWindow) enables a scrollable virtual canvas taller than the window.

​
Platform requirements

RequirementDetails
Operating systemLinux (any distribution with an X11 server)
Display serverX11 (Xorg or XWayland)
Compilerg++ with C++17 support (-std=gnu++17)
Runtime dependencylibX11 (Xlib)
Build dependencylibx11-dev (or distro equivalent)
LWXGL does not support Wayland natively (XWayland compatibility layer works), macOS, or Windows.

​
Where to go next

Installation

Build and install libLWXGL.so from source in under five minutes.

Quickstart

Write your first window, label, and button with a working event loop.

Core Concepts

Learn the ID system, color palette, flags, and the main loop in depth.

API Reference

Complete reference for every function, constant, and macro in the header.

Build docs developers (and LLMs) love

Get started for freeTalk to us