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_CUSTOM_DATA
	Owner-draw custom widget data: a paint callback plus its user pointer. More...
struct	N_GUI_DATAGRID_COL
	one data grid column definition More...
struct	N_GUI_DATAGRID_DATA
	data grid specific data: a sortable column table 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_HEXVIEW_DATA
	hex viewer specific data: a read-only byte dump 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_PENDING_GEOM
	A saved window position retained for a window not yet created at load time (see N_GUI_CTX::pending_layout). More...
struct	N_GUI_PENDING_WIDGET
	Saved user-adjustable state for a keyed widget that did not exist when the layout was loaded (a lazily-created splitpane/datagrid). More...
struct	N_GUI_PROGRESSBAR_DATA
	Progress-bar widget data (display only). More...
struct	N_GUI_RADIOLIST_DATA
	radio list specific data More...
struct	N_GUI_SCROLLBAR_DATA
	scrollbar specific data More...
struct	N_GUI_SECTION
	a single foldable section: a clickable header plus the member widgets it shows/hides More...
struct	N_GUI_SECTIONLIST
	a vertical accordion of foldable sections inside one window; folding hides a section's widgets and re-stacks the rest, leaving the window's N_GUI_WIN_AUTO_SCROLLBAR to absorb any overflow More...
struct	N_GUI_SLIDER_DATA
	slider specific data More...
struct	N_GUI_SPLITPANE_DATA
	split pane specific data: a draggable divider between two regions More...
struct	N_GUI_STYLE
	Global style holding every configurable layout constant. More...
struct	N_GUI_SYNTAXVIEW_DATA
	syntax view specific data: read-only highlighted text More...
struct	N_GUI_TAB_PANEL
	tab panel built from toggle buttons with content window management More...
struct	N_GUI_TB_BUTTONS
	Titlebar button state for a window (minimize, maximize, close) 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_COMBOBOX_EXPAND_UP   2
	dropdown panel opens upward (above the widget) instead of downward.
#define	N_GUI_DETACH_NONE   0
	no option
#define	N_GUI_DETACH_OWN_CHROME   4
	keep N_GUI's own window chrome instead of the window manager's: the native window is created frameless and the window keeps drawing its own title bar, so a detached window looks and skins exactly like the pop-up it came from.
#define	N_GUI_DETACH_RESIZABLE   1
	the native window can be resized by the user through the OS window manager
#define	N_GUI_DETACH_SCALE_CONTENT   2
	scale the window's widgets when the native window is resized by the user.
#define	N_GUI_DROP_AFTER   2
#define	N_GUI_DROP_BEFORE   0
	drop position relative to a tree row (drag-and-drop)
#define	N_GUI_DROP_INTO   1
#define	N_GUI_DROPMENU_EXPAND_UP   1
	dropdown panel opens upward (above the button) instead of downward.
#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_PERSIST_MAX_COLS   64
	Maximum datagrid columns whose layout is persisted per widget.
#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_SECTION_WIDGETS_MAX   48
	maximum number of member widgets per section
#define	N_GUI_SECTIONLIST_MAX   16
	maximum number of foldable sections in a section list
#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_SPLIT_HORIZONTAL   1
	split pane: horizontal divider, regions are top and bottom
#define	N_GUI_SPLIT_VERTICAL   0
	split pane: vertical divider, regions are left and right
#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_SYNTAX_HTTP   1
	syntax view: HTTP message highlighting (request/status line and headers)
#define	N_GUI_SYNTAX_JS   5
	syntax view: JavaScript highlighting (keywords, strings, numbers, comments)
#define	N_GUI_SYNTAX_JSON   2
	syntax view: JSON highlighting (keys, strings, numbers, punctuation)
#define	N_GUI_SYNTAX_PLAIN   0
	syntax view: no highlighting
#define	N_GUI_SYNTAX_XML   3
	syntax view: XML/HTML highlighting (tags, attributes, quoted values, comments)
#define	N_GUI_SYNTAX_YAML   4
	syntax view: YAML highlighting (keys, quoted values, list markers, comments)
#define	N_GUI_TAB_MAX   16
	maximum number of tabs in a single tab panel
#define	N_GUI_TB_BTN_CLOSE   3
	close titlebar button
#define	N_GUI_TB_BTN_MAXIMIZE   2
	maximize/restore titlebar button
#define	N_GUI_TB_BTN_MINIMIZE   1
	minimize titlebar button
#define	N_GUI_TB_BTN_NONE   0
	no titlebar button
#define	N_GUI_TEXT_MAX   4096
	maximum length for textarea content
#define	N_GUI_TREE_MAX   2048
	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_CUSTOM   17
	widget type: owner-draw custom widget (rendering delegated to a callback)
#define	N_GUI_TYPE_DATAGRID   15
	widget type: sortable column data grid
#define	N_GUI_TYPE_DROPMENU   11
	widget type: dropdown menu with static and dynamic entries
#define	N_GUI_TYPE_HEXVIEW   13
	widget type: read-only hexadecimal byte viewer
#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_PROGRESSBAR   16
	widget type: horizontal progress bar (display only)
#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_SPLITPANE   12
	widget type: split pane with a draggable divider between two regions
#define	N_GUI_TYPE_SYNTAXVIEW   14
	widget type: read-only syntax-highlighted text view
#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_BTN_ALL   (N_GUI_WIN_BTN_MINIMIZE | N_GUI_WIN_BTN_MAXIMIZE | N_GUI_WIN_BTN_CLOSE)
	enable all three title bar buttons (minimize + maximize + close)
#define	N_GUI_WIN_BTN_CLOSE   1024
	enable close button on the title bar
#define	N_GUI_WIN_BTN_MAXIMIZE   512
	enable maximize/restore button on the title bar
#define	N_GUI_WIN_BTN_MINIMIZE   256
	enable minimize button on the title bar
#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_MAXIMISED   64
	window is maximised (full display size)
#define	N_GUI_WIN_MINIMISED   2
	window is minimised (title bar only)
#define	N_GUI_WIN_NO_HSCROLL   2048
	with N_GUI_WIN_AUTO_SCROLLBAR, never show the horizontal scrollbar (vertical-only scrolling): content wider than the window is clipped instead of horizontally scrolled
#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
#define	N_GUI_ZORDER_POPUP   4
	popup/modal dialogs: drawn above EVERYTHING including ALWAYS_ON_TOP windows.

Typedefs
typedef void(*	N_GUI_CUSTOM_DRAW) (N_GUI_WIDGET *widget, float x, float y, ALLEGRO_FONT *font, void *user_data)
	Owner-draw callback for a custom widget (N_GUI_TYPE_CUSTOM).
typedef int(*	n_gui_tree_on_drop_t) (int src_node, int dst_node, int position, void *user_data)
	drag-reorder drop callback.

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_custom (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, N_GUI_CUSTOM_DRAW draw, void *user_data)
	Add an owner-draw custom widget to a window.
int	n_gui_add_datagrid (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 sortable data grid; returns the widget id or -1
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_hexview (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h)
	add a read-only hex viewer; returns the widget id or -1
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_progressbar (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h)
	add a horizontal progress bar (display only); returns the widget id or -1
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_splitpane (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, int orientation, float ratio, void(*on_change)(int, float, void *), void *user_data)
	add a split pane (draggable divider); returns the widget id or -1
int	n_gui_add_syntaxview (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, int mode)
	add a read-only syntax-highlighted text view; returns the widget id or -1
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_label (N_GUI_CTX *ctx, int widget_id, const char *label)
	replace the label text drawn on a button
void	n_gui_button_set_state_bitmaps (N_GUI_CTX *ctx, int widget_id, ALLEGRO_BITMAP *normal, ALLEGRO_BITMAP *hover, ALLEGRO_BITMAP *active)
	skin a button or toggle button with caller-owned per-state bitmaps (switches its shape to N_GUI_SHAPE_BITMAP; toggled-on renders active)
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
const char *	n_gui_combobox_get_item_text (N_GUI_CTX *ctx, int widget_id, int index)
	get the text of the combobox item at index ("" if out of range / not 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
int	n_gui_count_detached (N_GUI_CTX *ctx)
	count the windows currently detached into native OS windows
int	n_gui_datagrid_add_column (N_GUI_CTX *ctx, int widget_id, const char *title, float width)
	append a column with a header title and pixel width; returns the column index or -1
int	n_gui_datagrid_add_row (N_GUI_CTX *ctx, int widget_id, const char **values)
	append a row of cell strings (values must have one entry per column); returns the row index or -1
void	n_gui_datagrid_clear_row_color (N_GUI_CTX *ctx, int widget_id, int row)
	remove the background tint of data row row (it draws untinted again)
void	n_gui_datagrid_clear_row_colors (N_GUI_CTX *ctx, int widget_id)
	remove every row background tint (the rows and cells are kept)
void	n_gui_datagrid_clear_rows (N_GUI_CTX *ctx, int widget_id)
	remove all rows from a data grid (columns are kept)
void	n_gui_datagrid_clear_selection (N_GUI_CTX *ctx, int widget_id)
	clear the entire selection (no row selected)
int	n_gui_datagrid_display_to_physical (N_GUI_CTX *ctx, int widget_id, int display_pos)
	physical column shown at display position display_pos, or -1 if out of range
const char *	n_gui_datagrid_get_cell (N_GUI_CTX *ctx, int widget_id, int row, int col)
	get a cell string by row and column, or NULL if out of range
size_t	n_gui_datagrid_get_column_count (N_GUI_CTX *ctx, int widget_id)
	number of columns in a data grid (physical), or 0
const char *	n_gui_datagrid_get_column_title (N_GUI_CTX *ctx, int widget_id, int col)
	header title of physical column col, or "" if out of range
int	n_gui_datagrid_get_column_visible (N_GUI_CTX *ctx, int widget_id, int col)
	whether physical column col is visible (1) or hidden (0); 0 if out of range
float	n_gui_datagrid_get_column_width (N_GUI_CTX *ctx, int widget_id, int col)
	current pixel width of physical column col, or 0 if out of range
float	n_gui_datagrid_get_h_scroll (N_GUI_CTX *ctx, int widget_id)
	horizontal scroll offset in pixels (how far the columns are scrolled left when their total width exceeds the widget's pane), or 0.
int	n_gui_datagrid_get_row_color (N_GUI_CTX *ctx, int widget_id, int row, ALLEGRO_COLOR *out)
	report whether data row row carries a background tint (1) or not (0), and copy the tint into out when it does.
int	n_gui_datagrid_get_row_count (N_GUI_CTX *ctx, int widget_id)
	get the number of rows in a data grid
int	n_gui_datagrid_get_scroll_offset (N_GUI_CTX *ctx, int widget_id)
	first visible data row (the vertical scroll position), or 0.
int	n_gui_datagrid_get_selected (N_GUI_CTX *ctx, int widget_id)
	get the selected row index, or -1 if none
size_t	n_gui_datagrid_get_selected_rows (N_GUI_CTX *ctx, int widget_id, int *out, size_t max)
	fill out with the indices of the selected rows (ascending), up to max, and return the total number of selected rows.
int	n_gui_datagrid_is_row_selected (N_GUI_CTX *ctx, int widget_id, int row)
	report whether a given data row is selected (1) or not (0)
void	n_gui_datagrid_move_column (N_GUI_CTX *ctx, int widget_id, int from, int to)
	move the column at display position from to display position to, shifting the columns in between (reorders how columns are laid out; the cells and physical indices are unchanged)
void	n_gui_datagrid_select_row (N_GUI_CTX *ctx, int widget_id, int row, int selected)
	select (1) or deselect (0) a single row in a multi-select grid programmatically (e.g.
void	n_gui_datagrid_set_column_visible (N_GUI_CTX *ctx, int widget_id, int col, int visible)
	show (1) or hide (0) physical column col; hidden columns keep their cells but are skipped in the header and rows and closed up so no gap remains
void	n_gui_datagrid_set_column_width (N_GUI_CTX *ctx, int widget_id, int col, float width)
	set the pixel width of physical column col (clamped to a small minimum)
void	n_gui_datagrid_set_h_scroll (N_GUI_CTX *ctx, int widget_id, float px)
	set the horizontal scroll offset in pixels (clamped to >= 0; the draw path re-clamps to the live content width each frame, so a stale value after a rebuild is harmless).
void	n_gui_datagrid_set_multiselect (N_GUI_CTX *ctx, int widget_id, int enabled)
	enable (1) or disable (0) multi-row selection.
void	n_gui_datagrid_set_on_columns_changed (N_GUI_CTX *ctx, int widget_id, void(*cb)(int, void *))
	set the callback fired after the user drags a column border to resize it, so the host can persist the layout.
void	n_gui_datagrid_set_on_context (N_GUI_CTX *ctx, int widget_id, void(*on_context)(int, int, int, int, void *))
	set the right-click context callback; fired (with the cursor x/y in GUI coordinates) when a data row is right-clicked, after selecting that row.
void	n_gui_datagrid_set_row_color (N_GUI_CTX *ctx, int widget_id, int row, ALLEGRO_COLOR color)
	paint data row row with a background tint (a per-row highlight, e.g.
void	n_gui_datagrid_set_scroll_offset (N_GUI_CTX *ctx, int widget_id, int offset)
	set the first visible data row (clamped to the row count); the draw path re-clamps to the live viewport each frame, so a stale offset after a rebuild is harmless.
void	n_gui_datagrid_set_selected (N_GUI_CTX *ctx, int widget_id, int row)
	set the selected row index (fires the on_select callback)
void	n_gui_datagrid_sort (N_GUI_CTX *ctx, int widget_id, int col, int dir)
	sort the rows by a column (dir 1 ascending, -1 descending)
N_GUI_STYLE	n_gui_default_style (void)
	return the built-in default style
N_GUI_THEME	n_gui_default_tb_btn_theme (void)
	return the built-in default theme for titlebar minimize/maximize buttons
N_GUI_THEME	n_gui_default_tb_close_theme (void)
	return the built-in default theme for the titlebar close button (red hover/active)
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
void	n_gui_draw_detached (N_GUI_CTX *ctx)
	render and flip every detached window, and release the ones whose native window was closed.
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
float	n_gui_dropmenu_panel_width (N_GUI_CTX *ctx, int widget_id)
	width the open panel needs to show its entries without truncation: the larger of the collapsed button width and the widest entry text (plus item padding on both sides and the scrollbar width when the entry count overflows the visible window).
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
void	n_gui_dropmenu_set_flags (N_GUI_CTX *ctx, int widget_id, int flags)
	set dropmenu feature flags (bitmask of N_GUI_DROPMENU_* values)
void	n_gui_dropmenu_set_label (N_GUI_CTX *ctx, int widget_id, const char *label)
	replace the button label shown on a dropmenu (NULL clears it)
void	n_gui_focus_window (N_GUI_CTX *ctx, int window_id)
	give a window keyboard focus: raise it within its z-order group and focus its first focusable widget (clears focus if it has none)
float	n_gui_get_dpi_scale (const N_GUI_CTX *ctx)
	get current DPI scale factor
ALLEGRO_EVENT_QUEUE *	n_gui_get_event_queue (N_GUI_CTX *ctx)
	get the event queue previously given to n_gui_set_event_queue (NULL if none)
int	n_gui_get_resize_mode (N_GUI_CTX *ctx)
	get current resize mode
int	n_gui_get_shape_mode (N_GUI_CTX *ctx)
	get the global widget shape (N_GUI_SHAPE_ROUNDED or N_GUI_SHAPE_RECT)
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.
int	n_gui_get_topmost_open_window (const N_GUI_CTX *ctx)
	get the id of the frontmost open, non-minimized window (the last one in draw order), or -1 if no window is open.
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
size_t	n_gui_hexview_get_length (N_GUI_CTX *ctx, int widget_id)
	get the number of bytes currently held by a hex viewer
void	n_gui_hexview_set_data (N_GUI_CTX *ctx, int widget_id, const unsigned char *data, size_t len)
	set (copy) the bytes shown by a hex viewer; data may be NULL to clear
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
void	n_gui_kvtable_clear (N_GUI_KVTABLE *table)
	remove every row at once.
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 (const N_GUI_KVTABLE *table)
	get the number of active rows
void	n_gui_kvtable_relayout (N_GUI_KVTABLE *table)
	re-apply layout to all KV table widgets (positions, sizes, normalized coords).
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_kvtable_set_columns (N_GUI_KVTABLE *table, int show_value, int show_desc, int show_enabled)
	choose which optional columns are shown: Value, Description, and the enabled checkbox.
void	n_gui_kvtable_set_placeholders (N_GUI_KVTABLE *table, const char *key_hint, const char *value_hint)
	set the placeholder/hint text shown in each row's key (and value) textarea while it is empty.
void	n_gui_kvtable_set_top_offset (N_GUI_KVTABLE *table, float top_offset)
	reserve top_offset unscaled pixels above the header row so other widgets (a toolbar, a heading) can share the table's window without overlapping it.
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_layout_json (N_GUI_CTX *ctx, const char *filepath)
	Load a JSON window layout file and apply it to matching windows in the context.
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_mark_dirty (N_GUI_CTX *ctx)
	Mark the GUI as needing a redraw.
void	n_gui_maximize_window (N_GUI_CTX *ctx, int window_id)
	toggle maximised state (full display or restore to previous size)
void	n_gui_minimize_window (N_GUI_CTX *ctx, int window_id)
	minimize a window (title bar only)
int	n_gui_needs_redraw (N_GUI_CTX *ctx)
	Return non-zero if the GUI must be redrawn this frame, i.e.
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
float	n_gui_progressbar_get_value (N_GUI_CTX *ctx, int widget_id)
	get the current progress fraction (0.0 on an invalid widget)
void	n_gui_progressbar_set_text (N_GUI_CTX *ctx, int widget_id, const char *text)
	set the centered overlay text (NULL or "" clears it)
void	n_gui_progressbar_set_value (N_GUI_CTX *ctx, int widget_id, float value)
	set the progress fraction (clamped to 0.0 .
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)
void	n_gui_reset_all_widget_themes (N_GUI_CTX *ctx)
	reset all widget and window themes to ctx->default_theme
void	n_gui_restore_window (N_GUI_CTX *ctx, int window_id)
	restore a minimised window to its full size
int	n_gui_save_layout_json (N_GUI_CTX *ctx, const char *filepath)
	Save the geometry + persistent state of every window in the context to a JSON file.
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
int	n_gui_sectionlist_add_section (N_GUI_SECTIONLIST *sl, const char *title, float header_y, int folded)
	add a section with a header button at header_y (members added next are captured relative to it); returns the section index or -1
void	n_gui_sectionlist_add_widget (N_GUI_SECTIONLIST *sl, int section_index, int widget_id)
	register an existing widget as a member of a section (captures its current y as the fold offset)
float	n_gui_sectionlist_content_height (const N_GUI_SECTIONLIST *sl)
	total content height in pixels under the current fold state, for sizing/scrolling the host window
N_GUI_SECTIONLIST *	n_gui_sectionlist_create (N_GUI_CTX *ctx, int window_id, float x, float y0, float width, float header_h, float gap, void(*on_toggle)(int, int, void *), void *user_data)
	create an empty section list anchored at (x,y0) in window_id; sections stack downward from y0
void	n_gui_sectionlist_free (N_GUI_SECTIONLIST **sl)
	free the section list (does not destroy the N_GUI widgets or window)
int	n_gui_sectionlist_get_count (const N_GUI_SECTIONLIST *sl)
	number of sections in the list
int	n_gui_sectionlist_is_folded (const N_GUI_SECTIONLIST *sl, int section_index)
	query a section's folded state (1 = folded, 0 = expanded)
void	n_gui_sectionlist_relayout (N_GUI_SECTIONLIST *sl)
	re-stack all sections from y0 by current fold state: hide folded members, show and reposition expanded ones
void	n_gui_sectionlist_set_first_inset (N_GUI_SECTIONLIST *sl, float inset)
	set a left inset applied to the FIRST section's header only, so a caller can place a button before it on the same row; relayout re-applies it
void	n_gui_sectionlist_set_folded (N_GUI_SECTIONLIST *sl, int section_index, int folded)
	set a section's folded state and relayout; does NOT fire on_toggle (for programmatic restore)
void	n_gui_set_default_theme (N_GUI_CTX *ctx, N_GUI_THEME theme)
	Set the default theme on a context and sync scrollbar style colors.
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_event_queue (N_GUI_CTX *ctx, ALLEGRO_EVENT_QUEUE *queue)
	give the context the event queue it registers native window event sources into
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_shape_mode (N_GUI_CTX *ctx, int shape_mode)
	set the global widget shape (N_GUI_SHAPE_ROUNDED for a round GUI, else square)
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_tooltip (N_GUI_CTX *ctx, int widget_id, const char *text)
	set (or clear with "" / NULL) the tooltip text shown after the pointer rests 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
void	n_gui_slider_set_value_format (N_GUI_CTX *ctx, int widget_id, const char *fmt)
	Override the built-in value readout's printf format string.
void	n_gui_slider_set_value_visible (N_GUI_CTX *ctx, int widget_id, int visible)
	Toggle the built-in value label.
float	n_gui_splitpane_get_ratio (N_GUI_CTX *ctx, int widget_id)
	get the current divider ratio (0..1), or 0.5 if the widget is invalid
void	n_gui_splitpane_set_limits (N_GUI_CTX *ctx, int widget_id, float min_ratio, float max_ratio)
	set the minimum and maximum allowed divider ratio
void	n_gui_splitpane_set_ratio (N_GUI_CTX *ctx, int widget_id, float ratio)
	set the divider ratio (clamped to the configured min/max)
int	n_gui_syntaxview_get_line_count (N_GUI_CTX *ctx, int widget_id)
	get the number of text lines in a syntax view
char *	n_gui_syntaxview_get_selected_text (N_GUI_CTX *ctx, int widget_id)
	copy of the currently selected text in a syntax view, or NULL when nothing is selected.
const char *	n_gui_syntaxview_get_text (N_GUI_CTX *ctx, int widget_id)
	get the text shown by a syntax view (borrowed pointer, do not free; NULL if empty)
void	n_gui_syntaxview_scroll_to_offset (N_GUI_CTX *ctx, int widget_id, int byte_offset)
	scroll a syntax view so the line holding the given byte offset is vertically centered
void	n_gui_syntaxview_select_all (N_GUI_CTX *ctx, int widget_id)
	select the entire text of a syntax view
void	n_gui_syntaxview_set_mode (N_GUI_CTX *ctx, int widget_id, int mode)
	set the highlighting mode (N_GUI_SYNTAX_*) of a syntax view
void	n_gui_syntaxview_set_selection (N_GUI_CTX *ctx, int widget_id, int start, int end)
	set the selection range (byte offsets into the text, clamped to its length); pass start == end to clear the selection
void	n_gui_syntaxview_set_text (N_GUI_CTX *ctx, int widget_id, const char *text)
	set (copy) the text shown by a syntax view; text may be NULL to clear
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 (const 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_placeholder (N_GUI_CTX *ctx, int widget_id, const char *text)
	set placeholder/hint text for a textarea, shown dimmed while the field is empty and cleared from view as soon as the user types.
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_tooltip_pending (N_GUI_CTX *ctx)
	tooltip phase: 0 = none (or tooltips disabled via style.tooltip_delay <= 0), 1 = arming (hosts with cached GUI renders must keep redrawing so the bubble can appear on time), 2 = shown (static - re-render once on the transition, then stop)
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
void	n_gui_tree_clear (N_GUI_TREE *tree)
	remove all nodes and clear the backing listbox; tree object remains valid
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_draw_overlay (N_GUI_TREE *tree)
	per-frame overlay drawing: draws the active drop-indicator on top of the listbox.
int	n_gui_tree_find_by_user_data (const N_GUI_TREE *tree, const void *ptr)
	find the first node whose user_data pointer equals ptr, or -1.
void	n_gui_tree_free (N_GUI_TREE **tree)
	free a tree view (does not destroy the N_GUI listbox)
int	n_gui_tree_get_selection (N_GUI_TREE *tree)
	get the index of the currently selected node, or -1 when nothing is selected or the selection points at a hidden row
void	n_gui_tree_rebuild (N_GUI_TREE *tree)
	rebuild the listbox to reflect current tree state
void	n_gui_tree_remove_node (N_GUI_TREE *tree, int node_index)
	remove a node and its entire subtree; remaining node indices are compacted (callers holding indices across the call must discard or re-resolve them)
void	n_gui_tree_set_label (N_GUI_TREE *tree, int node_index, const char *new_label)
	change the display label of a node
void	n_gui_tree_set_on_drop (N_GUI_TREE *tree, n_gui_tree_on_drop_t on_drop, void *user_data)
	install (or clear, with NULL) a drag-reorder drop callback.
void	n_gui_tree_set_selection (N_GUI_TREE *tree, int node_index)
	programmatically select a node; ancestors are expanded so the node is visible, and the listbox scrolls to reveal it.
void	n_gui_tree_tick (N_GUI_TREE *tree)
	per-frame poll: reads ctx->mouse_* to track drag state and fires the on_drop callback on release.
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)
const char *	n_gui_widget_get_persist_key (N_GUI_CTX *ctx, int widget_id)
	Get a widget's persist key ("" when unset), or NULL when the widget is invalid.
void	n_gui_widget_set_persist_key (N_GUI_CTX *ctx, int widget_id, const char *key)
	Give a widget a stable key so its user-adjustable state (a splitpane's divider ratio, or a datagrid's column order/visibility/width) is persisted by n_gui_save_layout_json and restored by n_gui_load_layout_json.
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)
int	n_gui_window_attach (N_GUI_CTX *ctx, int window_id)
	return a detached window to being an in-display pop-up
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_detach (N_GUI_CTX *ctx, int window_id, int detach_flags)
	promote a pop-up window to a native OS window
int	n_gui_window_from_display (N_GUI_CTX *ctx, ALLEGRO_DISPLAY *display)
	find the window detached into a given display
ALLEGRO_DISPLAY *	n_gui_window_get_display (N_GUI_CTX *ctx, int window_id)
	get the native display backing a window, or NULL when it is a pop-up
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_detached (N_GUI_CTX *ctx, int window_id)
	check whether a window currently lives in a native OS window
int	n_gui_window_is_maximised (N_GUI_CTX *ctx, int window_id)
	check if a window is currently maximised
int	n_gui_window_is_minimised (N_GUI_CTX *ctx, int window_id)
	check if a window is currently minimised
int	n_gui_window_is_open (N_GUI_CTX *ctx, int window_id)
	check if window is visible
int	n_gui_window_native_is_hidden (N_GUI_CTX *ctx, int window_id)
	check whether a detached window's drawing is currently halted by the OS (Android surface loss) or the window manager has iconified it.
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_close_callback (N_GUI_CTX *ctx, int window_id, void(*on_close)(int, void *), void *user_data)
	set the close button callback for a window (NULL = default: hide window)
void	n_gui_window_set_content_draw_callback (N_GUI_CTX *ctx, int window_id, void(*on_content_draw)(int, void *), void *user_data)
	set a content-draw callback for a window, invoked during n_gui_draw right after the window's own content is drawn (at the window's z-order)
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_maximize_callback (N_GUI_CTX *ctx, int window_id, void(*on_maximize)(int, void *), void *user_data)
	set the maximize button callback for a window (NULL = default: toggle maximised)
void	n_gui_window_set_minimize_callback (N_GUI_CTX *ctx, int window_id, void(*on_minimize)(int, void *), void *user_data)
	set the minimize button callback for a window (NULL = default: toggle minimised)
int	n_gui_window_set_native_icons (N_GUI_CTX *ctx, int window_id, ALLEGRO_BITMAP **icons, int num_icons)
	give a detached window's OS window a taskbar / title bar icon
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_tb_btn_theme (N_GUI_CTX *ctx, int window_id, N_GUI_THEME theme)
	set the theme for titlebar minimize/maximize buttons on a specific window
void	n_gui_window_set_tb_button_bitmaps (N_GUI_CTX *ctx, int window_id, int btn_type, ALLEGRO_BITMAP *normal, ALLEGRO_BITMAP *hover, ALLEGRO_BITMAP *active)
	set optional bitmap overlays on a titlebar button
void	n_gui_window_set_tb_close_theme (N_GUI_CTX *ctx, int window_id, N_GUI_THEME theme)
	set the theme for the titlebar close button on a specific window
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.