n_gui.h File Reference

GUI system: buttons, sliders, text areas, checkboxes, scrollbars, dropdown menus, windows. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <stdbool.h>
#include <nilorea/n_allegro5.h>
#include <nilorea/n_common.h>
#include <nilorea/n_str.h>
#include <nilorea/n_log.h>
#include <nilorea/n_list.h>
#include <nilorea/n_hash.h>

Include dependency graph for n_gui.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	N_GUI_BUTTON_DATA
	button specific data More...
struct	N_GUI_CHECKBOX_DATA
	checkbox specific data More...
struct	N_GUI_COMBOBOX_DATA
	combo box specific data More...
struct	N_GUI_CTX
	The top-level GUI context that holds all windows. More...
struct	N_GUI_DROPMENU_DATA
	dropdown menu specific data More...
struct	N_GUI_DROPMENU_ENTRY
	A single entry in a dropdown menu (static or dynamic) More...
struct	N_GUI_IMAGE_DATA
	image widget specific data More...
struct	N_GUI_KV_ROW
	a single row in the KV table More...
struct	N_GUI_KVTABLE
	key-value table built from textareas, checkboxes, and buttons More...
struct	N_GUI_LABEL_DATA
	static text label specific data More...
struct	N_GUI_LISTBOX_DATA
	listbox specific data More...
struct	N_GUI_LISTITEM
	a single item in a list/radio/combo widget More...
struct	N_GUI_RADIOLIST_DATA
	radio list specific data More...
struct	N_GUI_SCROLLBAR_DATA
	scrollbar specific data More...
struct	N_GUI_SLIDER_DATA
	slider specific data More...
struct	N_GUI_STYLE
	Global style holding every configurable layout constant. More...
struct	N_GUI_TAB_PANEL
	tab panel built from toggle buttons with content window management More...
struct	N_GUI_TEXT_DIMS
	bounding box dimensions returned by n_gui_get_text_dims() More...
struct	N_GUI_TEXTAREA_DATA
	text area specific data More...
struct	N_GUI_THEME
	Color theme for a widget. More...
struct	N_GUI_TREE
	tree view built from an N_GUI listbox More...
struct	N_GUI_TREE_NODE
	a single node in the tree view More...
struct	N_GUI_WIDGET
	A single GUI widget. More...
struct	N_GUI_WINDOW
	A pseudo window that contains widgets. More...

Macros
#define	N_GUI_ALIGN_CENTER   1
	center aligned text
#define	N_GUI_ALIGN_JUSTIFIED   3
	justified text (spread words to fill width)
#define	N_GUI_ALIGN_LEFT   0
	left aligned text
#define	N_GUI_ALIGN_RIGHT   2
	right aligned text
#define	N_GUI_AUTOFIT_CENTER   16
	center the window on its insertion point after auto-fit (overrides EXPAND_LEFT/EXPAND_UP for centering)
#define	N_GUI_AUTOFIT_EXPAND_LEFT   4
	expand leftward instead of rightward when adjusting width
#define	N_GUI_AUTOFIT_EXPAND_UP   8
	expand upward instead of downward when adjusting height
#define	N_GUI_AUTOFIT_H   2
	auto-adjust window height to content
#define	N_GUI_AUTOFIT_W   1
	auto-adjust window width to content
#define	N_GUI_AUTOFIT_WH   3
	auto-adjust both width and height (convenience: W|H)
#define	N_GUI_COMBOBOX_AUTO_WIDTH   1
	dropdown panel expands to fit the longest item text
#define	N_GUI_ID_MAX   128
	maximum length for widget id/name strings
#define	N_GUI_IMAGE_CENTER   2
	draw at original size, centered
#define	N_GUI_IMAGE_FIT   0
	scale to fit within bounds, keep aspect ratio
#define	N_GUI_IMAGE_STRETCH   1
	stretch to fill bounds
#define	N_GUI_KEY_MOD_MASK   (ALLEGRO_KEYMOD_SHIFT | ALLEGRO_KEYMOD_CTRL | ALLEGRO_KEYMOD_ALT | ALLEGRO_KEYMOD_ALTGR)
	mask of supported modifier flags for button keybind matching
#define	N_GUI_KEY_SOURCES_MAX   8
	maximum number of source widgets for a focused key binding
#define	N_GUI_KV_MAX   128
	maximum number of rows in a KV table
#define	N_GUI_RESIZE_ADAPTIVE   1
	virtual size tracks display; windows adapt per their resize_policy
#define	N_GUI_RESIZE_VIRTUAL   0
	fixed virtual canvas with uniform scaling (default/existing behavior)
#define	N_GUI_SCROLLBAR_H   0
	horizontal scrollbar
#define	N_GUI_SCROLLBAR_V   1
	vertical scrollbar
#define	N_GUI_SELECT_MULTIPLE   2
	multiple item selection
#define	N_GUI_SELECT_NONE   0
	no selection allowed (display only)
#define	N_GUI_SELECT_SINGLE   1
	single item selection
#define	N_GUI_SHAPE_BITMAP   2
	bitmap-based rendering
#define	N_GUI_SHAPE_RECT   0
	rectangle shape (default)
#define	N_GUI_SHAPE_ROUNDED   1
	rounded rectangle shape
#define	N_GUI_SLIDER_H   0
	horizontal slider (default)
#define	N_GUI_SLIDER_PERCENT   1
	slider uses 0-100 percentage
#define	N_GUI_SLIDER_V   1
	vertical slider
#define	N_GUI_SLIDER_VALUE   0
	slider uses raw start/end values
#define	N_GUI_STATE_ACTIVE   2
	widget is being pressed / dragged
#define	N_GUI_STATE_FOCUSED   4
	widget has keyboard focus
#define	N_GUI_STATE_HOVER   1
	mouse is hovering the widget
#define	N_GUI_STATE_IDLE   0
	widget is idle / normal state
#define	N_GUI_STATE_SCROLLBAR_DRAG   8
	widget scrollbar is being dragged
#define	N_GUI_TAB_MAX   16
	maximum number of tabs in a single tab panel
#define	N_GUI_TEXT_MAX   4096
	maximum length for textarea content
#define	N_GUI_TREE_MAX   512
	maximum number of nodes in a tree view
#define	N_GUI_TYPE_BUTTON   1
	widget type: button
#define	N_GUI_TYPE_CHECKBOX   4
	widget type: checkbox
#define	N_GUI_TYPE_COMBOBOX   8
	widget type: combo box (dropdown)
#define	N_GUI_TYPE_DROPMENU   11
	widget type: dropdown menu with static and dynamic entries
#define	N_GUI_TYPE_IMAGE   9
	widget type: image display
#define	N_GUI_TYPE_LABEL   10
	widget type: static text label (with optional hyperlink)
#define	N_GUI_TYPE_LISTBOX   6
	widget type: listbox (selectable list)
#define	N_GUI_TYPE_RADIOLIST   7
	widget type: radio list (single select radio buttons)
#define	N_GUI_TYPE_SCROLLBAR   5
	widget type: scrollbar
#define	N_GUI_TYPE_SLIDER   2
	widget type: slider
#define	N_GUI_TYPE_TEXTAREA   3
	widget type: text area
#define	N_GUI_WIN_AUTO_SCROLLBAR   16
	enable automatic scrollbars when content exceeds window size
#define	N_GUI_WIN_DRAGGING   4
	window is being dragged
#define	N_GUI_WIN_FIXED_POSITION   64
	disable window dragging (default:enable)
#define	N_GUI_WIN_FRAMELESS   128
	frameless window: no title bar drawn, drag via window body unless N_GUI_WIN_FIXED_POSITION is also set
#define	N_GUI_WIN_HSCROLL_DRAG   32
	window horizontal auto-scrollbar is being dragged
#define	N_GUI_WIN_MINIMISED   2
	window is minimised (title bar only)
#define	N_GUI_WIN_OPEN   1
	window is visible
#define	N_GUI_WIN_RESIZABLE   32
	enable user-resizable window with a drag handle at bottom-right
#define	N_GUI_WIN_RESIZE_MOVE   1
	reposition proportionally, keep pixel size
#define	N_GUI_WIN_RESIZE_NONE   0
	no adaptation: absolute position and size unchanged
#define	N_GUI_WIN_RESIZE_SCALE   2
	reposition AND resize proportionally, child widgets scale too
#define	N_GUI_WIN_RESIZING   8
	window is being resized
#define	N_GUI_WIN_VSCROLL_DRAG   16
	window vertical auto-scrollbar is being dragged
#define	N_GUI_ZORDER_ALWAYS_BEHIND   2
	always drawn behind normal windows, cannot be raised above them
#define	N_GUI_ZORDER_ALWAYS_ON_TOP   1
	always drawn on top of normal windows, cannot be lowered behind them
#define	N_GUI_ZORDER_FIXED   3
	fixed z-value: window is sorted within a dedicated group between ALWAYS_BEHIND and NORMAL windows.
#define	N_GUI_ZORDER_NORMAL   0
	default z-order: window participates in normal raise/lower ordering

Functions
int	n_gui_add_button (N_GUI_CTX *ctx, int window_id, const char *label, float x, float y, float w, float h, int shape, void(*on_click)(int, void *), void *user_data)
	add a button widget
int	n_gui_add_button_bitmap (N_GUI_CTX *ctx, int window_id, const char *label, float x, float y, float w, float h, ALLEGRO_BITMAP *normal, ALLEGRO_BITMAP *hover, ALLEGRO_BITMAP *active, void(*on_click)(int, void *), void *user_data)
	add a bitmap-based button widget
int	n_gui_add_checkbox (N_GUI_CTX *ctx, int window_id, const char *label, float x, float y, float w, float h, int initial_checked, void(*on_toggle)(int, int, void *), void *user_data)
	add a checkbox widget
int	n_gui_add_combobox (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, void(*on_select)(int, int, void *), void *user_data)
	add a combo box widget
int	n_gui_add_dropmenu (N_GUI_CTX *ctx, int window_id, const char *label, float x, float y, float w, float h, void(*on_open)(int, void *), void *on_open_user_data)
	add a dropdown menu widget (button that opens a menu panel with entries)
int	n_gui_add_image (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, ALLEGRO_BITMAP *bitmap, int scale_mode)
	add an image widget
int	n_gui_add_label (N_GUI_CTX *ctx, int window_id, const char *text, float x, float y, float w, float h, int align)
	add a text label widget
int	n_gui_add_label_link (N_GUI_CTX *ctx, int window_id, const char *text, const char *link, float x, float y, float w, float h, int align, void(*on_link_click)(int, const char *, void *), void *user_data)
	add a text label with hyperlink
int	n_gui_add_listbox (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, int selection_mode, void(*on_select)(int, int, int, void *), void *user_data)
	add a listbox widget
int	n_gui_add_radiolist (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, void(*on_select)(int, int, void *), void *user_data)
	add a radio list widget
int	n_gui_add_scrollbar (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, int orientation, int shape, double content_size, double viewport_size, void(*on_scroll)(int, double, void *), void *user_data)
	add a scrollbar widget
int	n_gui_add_slider (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, double min_val, double max_val, double initial, int mode, void(*on_change)(int, double, void *), void *user_data)
	add a horizontal slider widget
int	n_gui_add_textarea (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, int multiline, size_t char_limit, void(*on_change)(int, const char *, void *), void *user_data)
	add a text area widget
int	n_gui_add_toggle_button (N_GUI_CTX *ctx, int window_id, const char *label, float x, float y, float w, float h, int shape, int initial_state, void(*on_click)(int, void *), void *user_data)
	toggle button creation (returns widget id)
int	n_gui_add_vslider (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, double min_val, double max_val, double initial, int mode, void(*on_change)(int, double, void *), void *user_data)
	add a vertical slider (same as n_gui_add_slider but oriented vertically)
int	n_gui_add_window (N_GUI_CTX *ctx, const char *title, float x, float y, float w, float h)
	add a window to the GUI context
int	n_gui_add_window_auto (N_GUI_CTX *ctx, const char *title, float x, float y)
	add a window that sizes itself automatically to fit its widgets (call n_gui_window_autosize after adding all widgets)
void	n_gui_apply_adaptive_resize (N_GUI_CTX *ctx, float new_w, float new_h)
	apply adaptive resize: reposition/resize all windows according to their policies for the new display dimensions.
int	n_gui_button_is_toggled (N_GUI_CTX *ctx, int widget_id)
	check if button is toggled
void	n_gui_button_set_keycode (N_GUI_CTX *ctx, int widget_id, int keycode, int modifiers)
	bind a keyboard key with optional modifier requirements to a button.
void	n_gui_button_set_keycode_focused (N_GUI_CTX *ctx, int widget_id, int keycode, int modifiers, const int *sources, int source_count)
	bind a keyboard key to a button that fires only when specific widgets have focus.
void	n_gui_button_set_toggle_mode (N_GUI_CTX *ctx, int widget_id, int toggle_mode)
	set button toggle mode
void	n_gui_button_set_toggled (N_GUI_CTX *ctx, int widget_id, int toggled)
	set button toggled state
int	n_gui_checkbox_is_checked (N_GUI_CTX *ctx, int widget_id)
	check if checkbox is checked
void	n_gui_checkbox_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *box, ALLEGRO_BITMAP *box_checked, ALLEGRO_BITMAP *box_hover)
	set optional bitmap overlays on a checkbox widget.
void	n_gui_checkbox_set_checked (N_GUI_CTX *ctx, int widget_id, int checked)
	set checkbox checked state
void	n_gui_close_window (N_GUI_CTX *ctx, int window_id)
	close (hide) a window
int	n_gui_combobox_add_item (N_GUI_CTX *ctx, int widget_id, const char *text)
	add an item to a combo box
void	n_gui_combobox_clear (N_GUI_CTX *ctx, int widget_id)
	remove all items from a combobox
int	n_gui_combobox_get_selected (N_GUI_CTX *ctx, int widget_id)
	get the selected item index
void	n_gui_combobox_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *bg, ALLEGRO_BITMAP *item_bg, ALLEGRO_BITMAP *item_selected)
	set optional bitmap overlays on a combobox widget.
void	n_gui_combobox_set_flags (N_GUI_CTX *ctx, int widget_id, int flags)
	set combobox feature flags (bitmask of N_GUI_COMBOBOX_* values)
void	n_gui_combobox_set_selected (N_GUI_CTX *ctx, int widget_id, int index)
	set the selected item index
N_GUI_STYLE	n_gui_default_style (void)
	return the built-in default style
N_GUI_THEME	n_gui_default_theme (void)
	return the built-in default theme
void	n_gui_destroy_ctx (N_GUI_CTX **ctx)
	destroy a GUI context and free all resources
float	n_gui_detect_dpi_scale (N_GUI_CTX *ctx, ALLEGRO_DISPLAY *display)
	detect and apply DPI scale from the given allegro display.
void	n_gui_draw (N_GUI_CTX *ctx)
	draw all visible GUI windows and widgets
int	n_gui_dropmenu_add_dynamic_entry (N_GUI_CTX *ctx, int widget_id, const char *text, int tag, void(*on_click)(int, int, int, void *), void *user_data)
	add a dynamic entry (rebuilt each time menu opens)
int	n_gui_dropmenu_add_entry (N_GUI_CTX *ctx, int widget_id, const char *text, int tag, void(*on_click)(int, int, int, void *), void *user_data)
	add a static entry to a dropdown menu
void	n_gui_dropmenu_clear (N_GUI_CTX *ctx, int widget_id)
	remove all entries
void	n_gui_dropmenu_clear_dynamic (N_GUI_CTX *ctx, int widget_id)
	remove all dynamic entries (call from on_open callback before re-adding)
int	n_gui_dropmenu_get_count (N_GUI_CTX *ctx, int widget_id)
	get number of entries
void	n_gui_dropmenu_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *panel, ALLEGRO_BITMAP *item_hover)
	set optional bitmap overlays on a dropmenu widget.
void	n_gui_dropmenu_set_entry_text (N_GUI_CTX *ctx, int widget_id, int index, const char *text)
	update text of an existing entry by index
float	n_gui_get_dpi_scale (const N_GUI_CTX *ctx)
	get current DPI scale factor
int	n_gui_get_resize_mode (N_GUI_CTX *ctx)
	get current resize mode
N_GUI_TEXT_DIMS	n_gui_get_text_dims (ALLEGRO_FONT *font, const char *text)
	get the bounding box dimensions of text rendered with the given font.
N_GUI_WIDGET *	n_gui_get_widget (N_GUI_CTX *ctx, int widget_id)
	get a widget by id
N_GUI_WINDOW *	n_gui_get_window (N_GUI_CTX *ctx, int window_id)
	get a window by id
void	n_gui_image_set_bitmap (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *bitmap)
	set the bitmap on an image widget
int	n_gui_is_widget_enabled (N_GUI_CTX *ctx, int widget_id)
	check if a widget is enabled
int	n_gui_kvtable_add_row (N_GUI_KVTABLE *table, const char *key, const char *value, const char *description, int enabled)
	add a row to the KV table
N_GUI_KVTABLE *	n_gui_kvtable_create (N_GUI_CTX *ctx, int window_id, float row_height, float padding, void(*on_remove)(int, void *), void *user_data)
	create a KV table in an existing window
void	n_gui_kvtable_free (N_GUI_KVTABLE **table)
	free a KV table (does not destroy the N_GUI widgets)
int	n_gui_kvtable_get_count (N_GUI_KVTABLE *table)
	get the number of active rows
void	n_gui_kvtable_remove_row (N_GUI_KVTABLE *table, int row_index)
	remove a row by index (hides widgets, marks inactive)
void	n_gui_label_set_bitmap (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *bg)
	set optional background bitmap on a label widget.
void	n_gui_label_set_link (N_GUI_CTX *ctx, int widget_id, const char *link)
	set label hyperlink URL
void	n_gui_label_set_text (N_GUI_CTX *ctx, int widget_id, const char *text)
	set label text content
int	n_gui_listbox_add_item (N_GUI_CTX *ctx, int widget_id, const char *text)
	add an item to a listbox
void	n_gui_listbox_clear (N_GUI_CTX *ctx, int widget_id)
	clear all items from a listbox
int	n_gui_listbox_get_count (N_GUI_CTX *ctx, int widget_id)
	get number of items in a listbox
const char *	n_gui_listbox_get_item_text (N_GUI_CTX *ctx, int widget_id, int index)
	get item text by index
int	n_gui_listbox_get_scroll_offset (N_GUI_CTX *ctx, int widget_id)
	get the current scroll offset (in items)
int	n_gui_listbox_get_selected (N_GUI_CTX *ctx, int widget_id)
	get the first selected item index
int	n_gui_listbox_is_selected (N_GUI_CTX *ctx, int widget_id, int index)
	check if an item is selected
int	n_gui_listbox_remove_item (N_GUI_CTX *ctx, int widget_id, int index)
	remove an item from a listbox by index
void	n_gui_listbox_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *bg, ALLEGRO_BITMAP *item_bg, ALLEGRO_BITMAP *item_selected)
	set optional bitmap overlays on a listbox widget.
void	n_gui_listbox_set_scroll_offset (N_GUI_CTX *ctx, int widget_id, int offset)
	set the scroll offset (in items) — clamps to valid range
void	n_gui_listbox_set_selected (N_GUI_CTX *ctx, int widget_id, int index, int selected)
	set item selection state
int	n_gui_load_theme_json (N_GUI_CTX *ctx, const char *filepath)
	Load a JSON theme file and apply it to the context.
void	n_gui_lower_window (N_GUI_CTX *ctx, int window_id)
	lower a window to the bottom of the stack (respects z-order constraints)
N_GUI_THEME	n_gui_make_theme (ALLEGRO_COLOR bg, ALLEGRO_COLOR bg_hover, ALLEGRO_COLOR bg_active, ALLEGRO_COLOR border, ALLEGRO_COLOR border_hover, ALLEGRO_COLOR border_active, ALLEGRO_COLOR text, ALLEGRO_COLOR text_hover, ALLEGRO_COLOR text_active, float border_thickness, float corner_rx, float corner_ry)
	create a custom theme from individual colors and properties
void	n_gui_minimize_window (N_GUI_CTX *ctx, int window_id)
	minimize a window (title bar only)
N_GUI_CTX *	n_gui_new_ctx (ALLEGRO_FONT *default_font)
	create a new GUI context
void	n_gui_open_window (N_GUI_CTX *ctx, int window_id)
	open (show) a window
int	n_gui_process_event (N_GUI_CTX *ctx, ALLEGRO_EVENT event)
	process an allegro event for the GUI
int	n_gui_radiolist_add_item (N_GUI_CTX *ctx, int widget_id, const char *text)
	add an item to a radio list
void	n_gui_radiolist_clear (N_GUI_CTX *ctx, int widget_id)
	remove all items from a radio list
int	n_gui_radiolist_get_selected (N_GUI_CTX *ctx, int widget_id)
	get the selected item index
void	n_gui_radiolist_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *bg, ALLEGRO_BITMAP *item_bg, ALLEGRO_BITMAP *item_selected)
	set optional bitmap overlays on a radiolist widget.
void	n_gui_radiolist_set_selected (N_GUI_CTX *ctx, int widget_id, int index)
	set the selected item index
void	n_gui_raise_window (N_GUI_CTX *ctx, int window_id)
	raise a window to the top of the stack (respects z-order constraints)
int	n_gui_save_theme_json (N_GUI_CTX *ctx, const char *filepath)
	Save the full theme (default_theme + style) to a JSON file.
void	n_gui_screen_to_virtual (const N_GUI_CTX *ctx, float sx, float sy, float *vx, float *vy)
	convert physical screen coordinates to virtual canvas coordinates.
double	n_gui_scrollbar_get_pos (N_GUI_CTX *ctx, int widget_id)
	get scrollbar position
void	n_gui_scrollbar_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *track, ALLEGRO_BITMAP *thumb, ALLEGRO_BITMAP *thumb_hover, ALLEGRO_BITMAP *thumb_active)
	set optional bitmap overlays on a scrollbar widget.
void	n_gui_scrollbar_set_pos (N_GUI_CTX *ctx, int widget_id, double pos)
	set scrollbar position
void	n_gui_scrollbar_set_sizes (N_GUI_CTX *ctx, int widget_id, double content_size, double viewport_size)
	set scrollbar content and viewport sizes
void	n_gui_set_display (N_GUI_CTX *ctx, ALLEGRO_DISPLAY *display)
	set the display pointer for clipboard operations (copy/paste)
void	n_gui_set_display_size (N_GUI_CTX *ctx, float w, float h)
	set the display (viewport) size so global scrollbars can be computed.
void	n_gui_set_dpi_scale (N_GUI_CTX *ctx, float scale)
	set DPI scale factor manually (default is 1.0).
void	n_gui_set_focus (N_GUI_CTX *ctx, int widget_id)
	set keyboard focus to a specific widget (-1 to clear focus)
void	n_gui_set_resize_mode (N_GUI_CTX *ctx, int mode)
	set context-level resize mode: N_GUI_RESIZE_VIRTUAL (default) or N_GUI_RESIZE_ADAPTIVE
void	n_gui_set_virtual_size (N_GUI_CTX *ctx, float w, float h)
	set the virtual canvas size for resolution-independent scaling.
void	n_gui_set_widget_enabled (N_GUI_CTX *ctx, int widget_id, int enabled)
	set widget enabled state (0 = disabled: drawn dimmed and ignores all input)
void	n_gui_set_widget_theme (N_GUI_CTX *ctx, int widget_id, N_GUI_THEME theme)
	set the theme on a widget
void	n_gui_set_widget_visible (N_GUI_CTX *ctx, int widget_id, int visible)
	set widget visibility
double	n_gui_slider_get_value (N_GUI_CTX *ctx, int widget_id)
	get slider current value
void	n_gui_slider_set_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *track, ALLEGRO_BITMAP *fill, ALLEGRO_BITMAP *handle, ALLEGRO_BITMAP *handle_hover, ALLEGRO_BITMAP *handle_active)
	set optional bitmap overlays on a slider widget.
void	n_gui_slider_set_range (N_GUI_CTX *ctx, int widget_id, double min_val, double max_val)
	set slider min/max range, clamping the current value if needed
void	n_gui_slider_set_step (N_GUI_CTX *ctx, int widget_id, double step)
	set slider step increment (0 is treated as 1).
void	n_gui_slider_set_value (N_GUI_CTX *ctx, int widget_id, double value)
	set slider value
int	n_gui_tab_add (N_GUI_TAB_PANEL *panel, const char *label)
	add a tab to the panel, returns tab index
N_GUI_TAB_PANEL *	n_gui_tab_create (N_GUI_CTX *ctx, int window_id, float x, float y, float button_w, float button_h, void(*on_tab_change)(int, void *), void *user_data)
	create a tab panel in an existing window
void	n_gui_tab_free (N_GUI_TAB_PANEL **panel)
	free a tab panel (does not destroy the N_GUI widgets)
int	n_gui_tab_get_active (N_GUI_TAB_PANEL *panel)
	get the active tab index
void	n_gui_tab_set_active (N_GUI_TAB_PANEL *panel, int index)
	set the active tab (toggles buttons, opens/closes content windows)
void	n_gui_tab_set_content_window (N_GUI_TAB_PANEL *panel, int tab_index, int window_id)
	associate a content window with a tab
const char *	n_gui_textarea_get_text (N_GUI_CTX *ctx, int widget_id)
	get text area content
size_t	n_gui_textarea_get_text_length (N_GUI_CTX *ctx, int widget_id)
	return the current text length in bytes (0 if widget is invalid)
void	n_gui_textarea_scroll_to_bottom (N_GUI_CTX *ctx, int widget_id)
	scroll a multiline textarea to the bottom
void	n_gui_textarea_scroll_to_offset (N_GUI_CTX *ctx, int widget_id, size_t byte_offset)
	scroll a multiline textarea so that the given byte offset is vertically centered
void	n_gui_textarea_set_bitmap (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *bg)
	set optional background bitmap on a textarea widget.
void	n_gui_textarea_set_mask_char (N_GUI_CTX *ctx, int widget_id, char mask)
	set a mask character for password-style input (e.g.
void	n_gui_textarea_set_selection (N_GUI_CTX *ctx, int widget_id, size_t start, size_t end)
	set the text selection range (byte offsets into text content)
void	n_gui_textarea_set_text (N_GUI_CTX *ctx, int widget_id, const char *text)
	set text area content
void	n_gui_toggle_window (N_GUI_CTX *ctx, int window_id)
	toggle window visibility (show/hide)
int	n_gui_tree_add_node (N_GUI_TREE *tree, const char *label, int parent_index, void *user_data)
	add a node to the tree
N_GUI_TREE *	n_gui_tree_create (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, void(*on_select)(int, void *), void *user_data)
	create a tree view in an existing window
void	n_gui_tree_free (N_GUI_TREE **tree)
	free a tree view (does not destroy the N_GUI listbox)
void	n_gui_tree_rebuild (N_GUI_TREE *tree)
	rebuild the listbox to reflect current tree state
void	n_gui_tree_toggle_expand (N_GUI_TREE *tree, int node_index)
	toggle expand/collapse of a node
void	n_gui_update_transform (N_GUI_CTX *ctx)
	recalculate scale and offset from virtual canvas to display.
int	n_gui_wants_mouse (N_GUI_CTX *ctx)
	check if the mouse is currently over any open GUI window (use to prevent click-through to the game world)
void	n_gui_window_apply_autofit (N_GUI_CTX *ctx, int window_id)
	trigger auto-fit recalculation for a window (call after adding/removing/resizing widgets)
void	n_gui_window_autosize (N_GUI_CTX *ctx, int window_id)
	recompute and apply minimum-fit size for a window based on its current widgets
int	n_gui_window_get_flags (N_GUI_CTX *ctx, int window_id)
	get feature flags of a window
int	n_gui_window_get_resize_policy (N_GUI_CTX *ctx, int window_id)
	get per-window resize policy
int	n_gui_window_get_zorder (N_GUI_CTX *ctx, int window_id)
	get window z-order mode
int	n_gui_window_get_zvalue (N_GUI_CTX *ctx, int window_id)
	get window z-value (for N_GUI_ZORDER_FIXED mode)
int	n_gui_window_is_open (N_GUI_CTX *ctx, int window_id)
	check if window is visible
void	n_gui_window_set_autofit (N_GUI_CTX *ctx, int window_id, int autofit_flags, float border)
	configure auto-fit behavior for a dialog window
void	n_gui_window_set_bitmaps (N_GUI_CTX *ctx, int window_id, ALLEGRO_BITMAP *bg, ALLEGRO_BITMAP *titlebar, int bg_scale_mode)
	set optional bitmap overlays on a window's body and titlebar.
void	n_gui_window_set_flags (N_GUI_CTX *ctx, int window_id, int flags)
	set feature flags on a window (N_GUI_WIN_AUTO_SCROLLBAR, N_GUI_WIN_RESIZABLE, ...)
void	n_gui_window_set_resize_policy (N_GUI_CTX *ctx, int window_id, int policy)
	set per-window resize policy (N_GUI_WIN_RESIZE_NONE / _MOVE / _SCALE).
void	n_gui_window_set_zorder (N_GUI_CTX *ctx, int window_id, int z_mode, int z_value)
	set window z-order mode and value
void	n_gui_window_update_normalized (N_GUI_CTX *ctx, int window_id)
	recapture normalized coordinates for a window from its current absolute position/size.

Detailed Description

GUI system: buttons, sliders, text areas, checkboxes, scrollbars, dropdown menus, windows.

Author

Castagnier Mickael

Version

3.0

Date

02/03/2026

Definition in file n_gui.h.