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 provides a built-in modal system that renders a centered dialog over the window contents without requiring any additional elements. While a modal is open, all user callbacks (EventAttachKey, EventAttachClick) are suppressed and button/checkbox elements are not interactive — only the modal’s own OK and Cancel buttons are hit-tested. There is one global modal slot. Calling SpawnModal while another modal is visible replaces it immediately.
ConstantValueDialog layout
MODAL_ALERT0Message text + OK button
MODAL_CONFIRM1Message text + OK button + Cancel button
MODAL_INPUT2Message text + text input field + OK button + Cancel button

​
SpawnModal

void SpawnModal(int type, const char* msg, void (*on_confirm)());
Displays a modal dialog. The dialog is rendered as a black-on-white centered panel. The message string is copied internally with strdup, so passing a stack-allocated string is safe. Clicking OK sets the modal to inactive and calls on_confirm (if non-NULL). Clicking Cancel (on MODAL_CONFIRM or MODAL_INPUT) sets the modal to inactive without calling the callback. There is no cancel callback — use QueryModalOpen() to detect whether the modal was dismissed. The input buffer is zeroed each time SpawnModal is called, so previous input does not persist across modal invocations.
​
type
int
required
Dialog type — MODAL_ALERT (0), MODAL_CONFIRM (1), or MODAL_INPUT (2).
​
msg
const char*
required
Message text to display in the dialog. Copied with strdup — the caller’s string does not need to remain valid after this call. Maximum display width depends on the window width.
​
on_confirm
void (*)()
required
Callback invoked when the user clicks OK. May be NULL for alert dialogs where you only need to notify the user. For MODAL_INPUT dialogs, call GetModalInput() inside this callback to retrieve the user’s text.

​
QueryModalOpen

int QueryModalOpen(void);
Returns 1 if a modal dialog is currently visible, 0 otherwise. Use this to gate game logic or polling that should be paused while the user is interacting with a dialog.

​
GetModalInput

const char* GetModalInput(void);
Returns a pointer to the modal’s internal 151-byte input buffer. The buffer contains the text entered by the user in a MODAL_INPUT dialog, null-terminated. Input is capped at 150 characters. This pointer is only meaningful after the user has clicked OK in a MODAL_INPUT dialog — call it from the on_confirm callback. The buffer is owned by LWXGL; do not free() it. The contents are overwritten the next time SpawnModal is called.
GetModalInput returns a pointer into an internal buffer that is zeroed on every SpawnModal call. Copy the string (e.g. with strncpy) if you need to retain it past the next modal spawn.

​
Scroll Utilities

These two functions relate to the optional window-scroll feature and are documented here alongside ReserveScroll (covered fully in the Events API).

​
QueryScroll

int QueryScroll(void);
Returns the current scroll offset in pixels. The offset is clamped between 0 and max(0, virtual_height - window_height). Returns 0 if scrolling is not enabled.

​
ReserveScroll

void ReserveScroll(int height, int scrollbar_color, void (*Scroll)(int offset));
Enables window scrolling. Must be called before CreateWindow. See the Events API for full documentation.
​
height
int
required
Total virtual canvas height in pixels (must be greater than the window height to be scrollable).
​
scrollbar_color
int
required
Two palette indices packed into one byte: low nibble (L) = track background fill color; high nibble (H) = thumb fill color. Pass CLR_NONE (-1) to hide the scrollbar entirely.
​
Scroll
void (*)(int offset)
required
Callback invoked with the new offset whenever scrolling occurs. May be NULL.

​
Code Example

#include "libLWXGL.h"
#include <stdio.h>
#include <string.h>

static char saved_input[151];

// --- MODAL_INPUT confirm callback ---
void on_name_entered(void) {
    const char* name = GetModalInput();
    strncpy(saved_input, name, 150);
    saved_input[150] = '\0';
    printf("User entered: %s\n", saved_input);
}

// --- MODAL_CONFIRM confirm callback ---
void on_delete_confirmed(void) {
    printf("Deletion confirmed.\n");
    // perform the deletion here
}

void on_click(int x, int y, int btn) {
    if (btn != 1) return;

    // Left-click in left half: show an alert
    if (x < 160) {
        SpawnModal(MODAL_ALERT, "Operation complete!", NULL);
        return;
    }

    // Left-click in right half: ask for a name
    if (x >= 160 && x < 240) {
        SpawnModal(MODAL_INPUT, "Enter your name:", on_name_entered);
        return;
    }

    // Right quarter: confirm before deleting
    SpawnModal(MODAL_CONFIRM, "Delete this item?", on_delete_confirmed);
}

void on_frame(int tick, float dt) {
    if (!QueryModalOpen()) {
        // Only update the canvas when no modal is blocking
        ClearImage(1, CLR_BLACK);
        DrawString(1, 10, 10, "Click to show modals", CLR_WHITE);
        UpdateImage(1);
    }
}

int main(void) {
    CreateWindow(320, 200, "Modals Demo", CLR_BLACK, FLAG_NONE);
    CreateImage(1, 0, 0, 0, 0);

    EventAttachClick(on_click);
    MainWindowLoop(60, on_frame);
    TerminateWindow();
    return 0;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us