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 widgets are identified by a caller-assigned integer id. Every element function either creates, queries, or modifies the element stored at that slot. IDs are zero-based and the element vector grows automatically to accommodate the largest ID you use. Creating a new element at an ID that is already occupied automatically frees the old one first. Element types are encoded internally as integers: 0 = text, 1 = button, 2 = input, 3 = rect, 4 = image, 5 = checkbox, 6 = console.

​
Element Management

​
GDeleteElement

void GDeleteElement(int index);
Frees all memory associated with the element at slot index and sets that slot to NULL. If index is out of bounds or the slot is already NULL, the call is a safe no-op. For image elements, this also calls XDestroyImage and releases the pixel and font buffers. For all other types the typed sub-struct is deleted and the base Element struct is freed.
​
index
int
required
The element slot to delete. Must be a previously allocated ID; out-of-range or already-NULL slots are silently ignored.
Example 
GCreateButton(3, 10, 10, 80, 30, 0xF0, 0xF5, 0xFA, "OK", on_ok);
/* … later … */
GDeleteElement(3);   /* frees the button at slot 3 */

​
GElemModifyBounds

void GElemModifyBounds(int id, int x, int y, int w, int h);
Updates the position and size of element id in place. The element is not recreated — only its x, y, w, and h fields are overwritten. The change takes effect on the next GRenderWindow call.
​
id
int
required
Target element ID.
​
x
int
required
New X position (pixels from the left edge of the window).
​
y
int
required
New Y position (pixels from the top edge of the window).
​
w
int
required
New width in pixels.
​
h
int
required
New height in pixels.
Example 
/* Move and resize an existing button */
GElemModifyBounds(3, 200, 50, 120, 40);

​
GElemSetVisible

void GElemSetVisible(int id, int visible);
Shows or hides element id. Hidden elements (visible = 0) are skipped entirely during rendering and do not receive mouse or keyboard events. The element’s data is preserved; call GElemSetVisible(id, 1) to make it visible again without recreating it.
​
id
int
required
Target element ID.
​
visible
int
required
Pass 1 to show the element or 0 to hide it.
Example 
GElemSetVisible(7, 0);   /* hide */
/* … later … */
GElemSetVisible(7, 1);   /* show again */

​
GElemInside

int GElemInside(int id);
Returns 1 if the mouse cursor is currently inside the element’s bounding box, the element is visible (v = 1), and the element belongs to the active screen (or is screen-independent, i.e., screen == -1). Returns 0 otherwise. For checkbox elements the bounding box is extended to the right to include the label text: the effective right edge is x + size + 6 + strlen(label) * 9.
​
id
int
required
The element to test.
Return value — int: 1 if the cursor is inside, 0 if not. Example 
if (GElemInside(5)) {
    /* highlight or show tooltip */
}

​
Text Label

​
GCreateText

void GCreateText(int id, int x, int y, int color, const char* text);
Creates a static text label at pixel position (x, y). Rendering uses the window’s built-in X11 font (9×15 pixels per character). The string pointer is stored directly — do not free or modify the buffer while the element is alive. Multi-line text is supported: the renderer splits on \n and advances the Y baseline by 15 pixels per line, so lines are rendered with no additional leading beyond the built-in line height.
​
id
int
required
Element slot to create the text label at.
​
x
int
required
X position of the leftmost character (pixels from window left).
​
y
int
required
Y position of the text baseline (pixels from window top). The first line is drawn with the X11 baseline at y + 11.
​
color
int
required
Palette index 0–15 for the text foreground color.
​
text
const char*
required
Null-terminated string to display. Use \n for line breaks. The pointer must remain valid for the lifetime of the element.
Example 
GCreateText(0, 20, 30, 15, "Hello, world!\nSecond line here.");

​
Button

​
GCreateButton

void GCreateButton(int id, int x, int y, int w, int h, int u, int hvr, int p,
                   const char* label, void (*onclick)(void));
Creates a clickable button widget. The button has three visual states — normal, hover, and pressed — each defined by a packed color byte (see Packed Color Reference below). The onclick callback is invoked when the user releases mouse button 1 (left-click) while the cursor is inside the button. The label is rendered centered both horizontally and vertically inside the button bounds using the 9×15 X11 font.
​
id
int
required
Element slot to create the button at.
​
x
int
required
X position of the top-left corner in pixels.
​
y
int
required
Y position of the top-left corner in pixels.
​
w
int
required
Width of the button in pixels.
​
h
int
required
Height of the button in pixels.
​
u
int
required
Packed color byte for the normal (unpressed) state. Upper nibble = border palette index; lower nibble = fill palette index.
​
hvr
int
required
Packed color byte for the hover state (cursor is over the button but not clicking).
​
p
int
required
Packed color byte for the pressed state (mouse button held down over the button).
​
label
const char*
required
Centered text label. The pointer must remain valid for the lifetime of the element.
​
onclick
void (*)(void)
required
Callback function invoked on left-click. Pass NULL to create a button with no action.
Example 
void on_submit(void) {
    /* handle click */
}

/* Dark border / mid-gray fill  →  brightens on hover  →  white fill when pressed */
GCreateButton(1, 50, 100, 120, 35, 0x87, 0x8A, 0x8F, "Submit", on_submit);

​
Input Field

​
GCreateInput

void GCreateInput(int id, int x, int y, int w, int h, int u, int hvr, int max);
Creates a single-line text input field. The field becomes active while the mouse cursor hovers over it; when active it captures keyboard input and renders a trailing _ cursor character. When inactive the cursor is replaced by a space. The internal input buffer is 128 bytes, so the effective maximum value for max is 127 (leaving room for the null terminator).
​
id
int
required
Element slot to create the input field at.
​
x
int
required
X position of the top-left corner in pixels.
​
y
int
required
Y position of the top-left corner in pixels.
​
w
int
required
Width in pixels. Pass -1 to auto-size: the width is computed as (max + 1) * 9 + 10, which is just wide enough to display max characters plus the _ cursor with a small inset.
​
h
int
required
Height in pixels.
​
u
int
required
Packed color byte for the inactive state (upper nibble = border, lower = fill).
​
hvr
int
required
Packed color byte for the hover/active state.
​
max
int
required
Maximum number of characters the user may type. Hard limit: 127 due to the 128-byte internal buffer.
Example 
/* Auto-sized, up to 20 characters, dark-on-light colors */
GCreateInput(2, 30, 60, -1, 24, 0x87, 0x8F, 20);

​
GGetInput

char* GGetInput(int id);
Returns a pointer to the element’s internal null-terminated input buffer. The string reflects the current typed content. Do not free this pointer — it points directly into the element’s heap-allocated InputElement struct and is valid until the element is deleted or recreated.
​
id
int
required
The input element to read.
Return value — char*: pointer to the current text (null-terminated, up to 127 printable characters). Example 
char* username = GGetInput(2);
printf("User entered: %s\n", username);

​
Checkbox

​
GCreateCheckbox

void GCreateCheckbox(int id, int x, int y, int size, int cb_col, int txt_col,
                     const char* label);
Creates a toggle checkbox widget. The checkbox is rendered as a square of size × size pixels with a border and fill drawn from cb_col. When checked, a filled inner rectangle (inset by 4 pixels on each side) is drawn using the border color. Clicking anywhere inside the checkbox bounding box (including the label area) toggles the checked state.
​
id
int
required
Element slot to create the checkbox at.
​
x
int
required
X position of the top-left corner of the checkbox square.
​
y
int
required
Y position of the top-left corner of the checkbox square.
​
size
int
required
Width and height of the checkbox square in pixels.
​
cb_col
int
required
Packed color byte for the checkbox square (upper nibble = border, lower nibble = fill). The border color is also used for the inner check mark fill.
​
txt_col
int
required
Palette index 0–15 for the label text color.
​
label
const char*
required
Text displayed 3 pixels to the right of the checkbox square. Pass NULL to render no label.
Example 
GCreateCheckbox(4, 20, 150, 16, 0xF0, 15, "Enable notifications");

​
GGetCheckbox

int GGetCheckbox(int id);
Returns the current checked state of checkbox element id.
​
id
int
required
The checkbox element to query.
Return value — int: 1 if the checkbox is currently checked, 0 if unchecked. Example 
if (GGetCheckbox(4)) {
    enable_notifications();
}

​
Rectangle

​
GCreateRect

void GCreateRect(int id, int x, int y, int w, int h, int fg, int bg);
Creates a filled rectangle widget, useful as a panel background, divider, or colored container. The border and fill are drawn independently; pass -1 for either to skip that part. Elements are drawn in ascending ID order, so assign lower IDs to background rectangles so they appear behind other widgets.
​
id
int
required
Element slot to create the rectangle at.
​
x
int
required
X position of the top-left corner in pixels.
​
y
int
required
Y position of the top-left corner in pixels.
​
w
int
required
Width in pixels.
​
h
int
required
Height in pixels.
​
fg
int
required
Palette index 0–15 for the 1-pixel outline border. Pass -1 to draw no border.
​
bg
int
required
Palette index 0–15 for the solid fill. Pass -1 to draw no fill (border only).
Example 
/* Solid dark panel with a light border */
GCreateRect(0, 10, 10, 300, 200, 15, 1);

/* Transparent overlay border only */
GCreateRect(10, 50, 50, 100, 60, 12, -1);

​
Packed Color Reference

Many LWXGL widget functions accept a packed color byte (int u, int hvr, int p, etc.) that encodes two palette indices into a single integer using nibble packing: 
packed = (border_palette_index << 4) | fill_palette_index
The upper nibble (bits 7–4) selects the border / outline color; the lower nibble (bits 3–0) selects the fill / background color. Both nibbles are palette indices in the range 0–15. 
/* Example: border = palette[8] (dark gray), fill = palette[7] (light gray) */
int packed = (8 << 4) | 7;   /* = 0x87 */

​
Common Packed Color Values

Packed ByteBorder (upper)Fill (lower)Typical Use
0xFF15 — white15 — whiteBright white button
0x000 — black0 — blackInvisible / black-on-black
0x070 — black7 — light grayDefault inactive input
0x0F0 — black15 — whiteHigh-contrast input (active)
0x787 — light gray8 — dark graySubtle raised panel
0x878 — dark gray7 — light grayNormal button state
0x8A8 — dark gray10 — greenHover accent button
0x8F8 — dark gray15 — whitePressed/active button
0xF015 — white0 — blackDark checkbox with white border
0x808 — dark gray0 — blackDark console background
The exact RGB values for each palette index depend on the current palette; use GPaletteQuery and GPaletteModify to inspect or change them.

Build docs developers (and LLMs) love

Get started for freeTalk to us