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 supports multiple virtual screens within a single window. Each element belongs to one screen (default: screen 0). Only elements whose screen index matches the active screen are rendered and receive input events. This lets you build multi-page UIs — settings panels, wizards, confirmation pages — without managing separate windows or manually hiding and showing dozens of elements.

​
Virtual Screens

int* GScreenActive(void);
void GScreenApply(int s, int ids[], int count);
GScreenActive returns a pointer to the active screen index integer. Dereference it to read the current screen, or assign through it to switch screens immediately: 
int current = *GScreenActive(); /* read active screen */
*GScreenActive() = 2;           /* switch to screen 2 */
GScreenApply assigns screen index s to each element in the ids array. Newly created elements always start on screen 0 — call GScreenApply after creation to move them. Elements with screen index -1 are always visible, regardless of the active screen. Use this for persistent UI chrome such as a top navigation bar or a status footer.

​
Two-Screen UI Example

#include "libLWXGL.h"

/* Screen 0: main menu */
#define ID_TITLE       1
#define ID_BTN_START   2
#define ID_BTN_SETTINGS 3

/* Screen 1: settings page */
#define ID_SETTINGS_TITLE  10
#define ID_CHK_SOUND       11
#define ID_BTN_BACK        12

/* Persistent nav bar (screen -1) */
#define ID_FOOTER 99

void go_to_settings(void) {
    *GScreenActive() = 1;
}

void go_to_main(void) {
    *GScreenActive() = 0;
}

void setup(void) {
    /* --- Screen 0 elements --- */
    GCreateText(ID_TITLE, 80, 40, 15, "Main Menu");
    GCreateButton(ID_BTN_START,    80, 90,  120, 28, 0x78, 0xF7, 0xF0, "Start",    NULL);
    GCreateButton(ID_BTN_SETTINGS, 80, 130, 120, 28, 0x78, 0xF7, 0xF0, "Settings", go_to_settings);

    int screen0_ids[] = {ID_TITLE, ID_BTN_START, ID_BTN_SETTINGS};
    GScreenApply(0, screen0_ids, 3);

    /* --- Screen 1 elements --- */
    GCreateText(ID_SETTINGS_TITLE, 80, 40, 15, "Settings");
    GCreateCheckbox(ID_CHK_SOUND, 80, 90, 14, 0x78, 15, "Enable sound");
    GCreateButton(ID_BTN_BACK, 80, 130, 80, 28, 0x78, 0xF7, 0xF0, "Back", go_to_main);

    int screen1_ids[] = {ID_SETTINGS_TITLE, ID_CHK_SOUND, ID_BTN_BACK};
    GScreenApply(1, screen1_ids, 3);

    /* --- Persistent footer (always visible) --- */
    GCreateText(ID_FOOTER, 5, 580, 8, "LWXGL Demo v1.0");
    int footer_ids[] = {ID_FOOTER};
    GScreenApply(-1, footer_ids, 1);
}
Switching the active screen by writing to *GScreenActive() takes effect immediately — on the next GRenderWindow() call only the elements matching the new screen (and those on screen -1) will be drawn or receive input.
LWXGL provides a built-in blocking modal dialog that overlays the window content and blocks all element interactions while open. 
void GSpawnModal(int type, const char* msg, void (*on_confirm)(void));
int  GQueryModalOpen(void);
ParameterDescription
type0 = OK-only dialog (single “OK” button). 1 = Confirm/Cancel dialog (“Cancel” and “OK” buttons).
msgThe message displayed inside the modal. Supports \n for line breaks. Lines are clipped at approximately 31 characters wide.
on_confirmCallback fired when the user clicks OK (type 0) or Confirm/OK (type 1). Pass NULL for no action on confirm.
GQueryModalOpen returns 1 while the modal is displayed. During this time:
  • All element click and keyboard callbacks are suppressed.
  • Button onclick handlers do not fire.
  • Input elements do not accept typing.
Clicking Cancel (type 1 only) dismisses the modal without calling on_confirm. There is no on_cancel callback.
The modal is rendered at a fixed position centered horizontally at the top of the window (approximately y = 47 to y = 200). It uses the built-in palette — styling is not configurable.

​
Delete Confirmation Example

#define ID_BTN_DELETE 5

void do_delete(void) {
    /* Perform the actual delete action */
}

void on_delete_click(void) {
    GSpawnModal(1,
        "Delete this item?\nThis cannot be undone.",
        do_delete /* called only if user clicks OK */
    );
}

void setup(void) {
    GCreateButton(ID_BTN_DELETE, 200, 300, 100, 28,
        0x48, 0xF4, 0xF0,      /* dark red tones */
        "Delete", on_delete_click);
}

​
Checking Modal State Mid-Frame

void on_frame(int tick, float dt) {
    if (GQueryModalOpen()) {
        /* Optionally dim or pause game logic while modal is open */
        return;
    }

    /* Normal per-frame logic */
    (void)tick; (void)dt;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us