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’s virtual screen system lets you assign elements to numbered screens. Only elements on the active screen — or on screen -1, which is always visible regardless of the active screen — are rendered and receive mouse/keyboard events. This lets you build multi-page UIs (wizards, tab views, settings panels) without creating or destroying elements at runtime: simply reassign them to screens and switch the active index.
GScreenActive
Returns a pointer to the internal active screen index. The initial value is 0. Because a pointer is returned, you can both read and write the active screen through the same call — no separate setter function exists.
Screen switching takes effect on the next GRenderWindow() call. Elements on the newly active screen (and on screen -1) become visible and interactive; all others are hidden.
Reading the active screen:
int current = *GScreenActive();
printf("Currently on screen %d\n", current);
*GScreenActive() = 1; /* switch to screen 1 */
GRenderWindow(); /* change becomes visible */
void on_next_clicked(void) {
/* Move from screen 0 to screen 1 when the user clicks "Next". */
*GScreenActive() = 1;
/* GRenderWindow() in the main loop will pick up the change. */
}
/* Somewhere during setup: */
GCreateButton(10, 400, 340, 100, 30, 7, 11, 9, "Next", on_next_clicked);
GScreenApply(0, (int[]){10}, 1); /* "Next" button lives on screen 0 */
GScreenActive returns a raw pointer into LWXGL’s internal state. Write to it only with a valid screen number. There is no upper bound enforced by the library — screens are identified purely by convention; any integer value is accepted.
GScreenApply
void GScreenApply(int s, int ids[], int count);
ids will only be rendered and receive events when the active screen matches s (or s is -1).
Elements that have never been assigned a screen belong to screen 0 by default (the initial active screen), so they are visible from the start without an explicit GScreenApply call.
The screen number to assign the elements to. Use -1 to make elements always visible regardless of the active screen.
Array of element IDs (as passed to GCreate* functions) to assign to screen s.
Number of IDs in the ids array.
/* Elements 0–4 belong to screen 0 (the first page). */
int page0_ids[] = {0, 1, 2, 3, 4};
GScreenApply(0, page0_ids, 5);
/* Elements 5–9 belong to screen 1 (the second page). */
int page1_ids[] = {5, 6, 7, 8, 9};
GScreenApply(1, page1_ids, 5);
You can call GScreenApply at any time — including after the window is already running — to move elements between screens dynamically. The change takes effect on the next GRenderWindow() call.
Screen -1 — Always Visible
Passing s = -1 to GScreenApply makes the listed elements permanently visible regardless of which screen is currently active. These elements are also always interactive — they receive mouse and keyboard events on every screen.
Use screen -1 for UI chrome that should persist across all pages:
- Navigation bars or tab strips
- Status bars or overlays
- “Back” / “Home” buttons shared between all screens
/* A header label and a persistent "Quit" button visible on every screen. */
int always_on[] = {NAV_LABEL_ID, QUIT_BTN_ID};
GScreenApply(-1, always_on, 2);
Elements on screen -1 are rendered on top of every screen. Make sure their positions do not overlap screen-specific content in a way that blocks interaction with elements on the active screen.
Full Multi-Screen Example
The example below creates a two-screen UI with a navigation button that is always visible (screen -1) and distinct content on each screen.
#include "libLWXGL.h"
/* Element ID constants */
#define NAV_BTN 0 /* "Toggle Screen" button — always visible */
#define LBL_SCREEN0 1 /* Label only on screen 0 */
#define BTN_SCREEN0 2 /* Button only on screen 0 */
#define LBL_SCREEN1 3 /* Label only on screen 1 */
#define BTN_SCREEN1 4 /* Button only on screen 1 */
/* Toggle between screen 0 and screen 1 */
void on_nav_clicked(void) {
int current = *GScreenActive();
*GScreenActive() = (current == 0) ? 1 : 0;
}
int main(void) {
GCreateWindow(640, 480, "Multi-Screen Demo", 0);
/* --- Always-visible navigation button (screen -1) --- */
GCreateButton(NAV_BTN, 10, 440, 160, 30, 7, 11, 9,
"Toggle Screen", on_nav_clicked);
/* --- Screen 0 content --- */
GCreateText(LBL_SCREEN0, 100, 80, 15, "Welcome to Screen 0");
GCreateButton(BTN_SCREEN0, 200, 200, 120, 30, 2, 10, 9,
"Screen 0 Action", NULL);
/* --- Screen 1 content --- */
GCreateText(LBL_SCREEN1, 100, 80, 14, "You are on Screen 1");
GCreateButton(BTN_SCREEN1, 200, 200, 120, 30, 1, 9, 9,
"Screen 1 Action", NULL);
/* Assign elements to their screens */
int screen0_ids[] = {LBL_SCREEN0, BTN_SCREEN0};
GScreenApply(0, screen0_ids, 2);
int screen1_ids[] = {LBL_SCREEN1, BTN_SCREEN1};
GScreenApply(1, screen1_ids, 2);
/* Nav button is always visible */
int nav_ids[] = {NAV_BTN};
GScreenApply(-1, nav_ids, 1);
/* Start on screen 0 (this is the default, shown for clarity) */
*GScreenActive() = 0;
/* Run at 60 fps; GRenderWindow is called internally by GSimpleWindowLoop */
GSimpleWindowLoop(60, NULL);
GTerminateWindow();
return 0;
}
GSimpleWindowLoop calls GHandleWindowEvents() and GRenderWindow() on every frame automatically. You do not need to call GRenderWindow() manually when using the simple loop — screen switches initiated in button callbacks will be reflected on the very next frame.
For more than two screens, store the total number of screens as a constant and cycle through them in your navigation callback: *GScreenActive() = (*GScreenActive() + 1) % NUM_SCREENS;