gullradriel/nilorea-library
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Module GUI
Pages
Examples Files Home Module AABB3D Module ACCEPT_POOL Module ALLEGRO4 Module ALLEGRO5 Module ANIM_LIB Module ASTAR Module ATLAS_LIB Module AVRO Module CLOCK_SYNC Module COMMONS Module CONFIGFILE Module CYPHER_BASE64 Module CYPHER_VIGENERE Module DEAD_RECKONING Module ENUMS Module EXCEPTIONS Module GAME_ENV Module GIT Module GUI Module HASH_TABLE Module ISOMETRIC_ENGINE Module LIST Module LOG Module LOGNODUP Module LZ4 Module NETWORKING Module NETWORK_MSG Module N_COOKIES Module N_DIFF Module N_DIGEST Module N_DISK_CACHE Module N_DNS Module N_ECC Module N_ENTROPY Module N_FILES Module N_FLUIDS Module N_GUI_COLOR Module N_GUI_COLORWHEEL Module N_GUI_CURVE Module N_GUI_GRID Module N_GUI_POPUP Module N_HEX Module N_HTTP3 Module N_HTTP_COOKIE Module N_HTTP_FORM Module N_HTTP_MIME Module N_HTTP_REQ Module N_HTTP_RESP Module N_HTTP_ROUTER Module N_HTTP_SERVER Module N_ICC Module N_JSON Module N_KAFKA Module N_LINALG Module N_MODULE Module N_OPENSSL_COMPAT Module N_PRETTY Module N_PTH Module N_QUERY Module N_RANDOM Module N_SHA256 Module N_STR Module N_TIFF Module N_TIME Module N_USER Module N_X509 Module N_ZIP Module PARTICLES Module PCRE Module PHYSICS Module SIGNALS Module STACK Module THREADS Module TRAJECTORY Module TREE Module ZLIB Modules Pages Struct A4_BMP Struct A4_TIMER Struct AABB3D Struct ANIM_DATA Struct ANIM_FRAME Struct ANIM_GFX Struct ANIM_LIB Struct ASTAR_BOX Struct ASTAR_CELL Struct ASTAR_GRID Struct ASTAR_HEAP Struct ASTAR_HEAP_NODE Struct ASTAR_NODE Struct ASTAR_PATH Struct AVRO_FIELD Struct AVRO_READER Struct AVRO_SCHEMA Struct BITMAP Struct CALLBACK_DATA Struct CA_CTX Struct CLIENT_JOB Struct CLIENT_STATE Struct CONFIG_FILE Struct CONFIG_FILE_SECTION Struct CYPHER_PARAM Struct DATA Struct DEMO_PANEL Struct DICTIONARY_DEFINITION Struct DICTIONARY_ENTRY Struct DIFF_OUT Struct DIFF_TEXT Struct DRAW_STATE Struct DR_ENTITY Struct DR_STATE Struct DR_VEC3 Struct ExceptionContextList Struct FONT Struct GAME_ENV Struct H2BUF Struct H2_DYN_ENTRY Struct H2_STREAM Struct HASH_NODE Struct HASH_TABLE Struct ISO_DRAW_ENTRY Struct ISO_MAP Struct ISO_PROJECTION Struct ISO_TILE_SEGMENT Struct ISO_TILE_SEGMENTS Struct ISO_VISIBLE_EDGES Struct JS_STATE Struct LEX_ITEM Struct LIST Struct LIST_NODE Struct LOG_LEVELS Struct LexMenu Struct MEMBER Struct MIDI Struct NESTED Struct NETWORK Struct NETWORK_HTTP_INFO Struct NETWORK_POOL Struct NETWORK_SSL_THREAD_PARAMS Struct NETW_ACCEPT_POOL Struct NETW_ACCEPT_POOL_STATS Struct NETW_MSG Struct NETW_SNI_ARG Struct NODE_DATA Struct N_ATLAS Struct N_ATLAS_PAGE Struct N_CLOCK_SYNC Struct N_COOKIE Struct N_COOKIE_JAR Struct N_DIFF_LINE Struct N_DIFF_RESULT Struct N_DISK_CACHE Struct N_ENTROPY_BIT Struct N_ENTROPY_POS Struct N_FILE_INFO Struct N_FLUID Struct N_FLUID_THREAD_PARAMS Struct N_FORM_FIELD Struct N_GIT_COMMIT_INFO Struct N_GIT_REMOTE_AUTH Struct N_GIT_REPO Struct N_GIT_STATUS_ENTRY Struct N_GUI_BUTTON_DATA Struct N_GUI_CHECKBOX_DATA Struct N_GUI_COLOR_PICKER Struct N_GUI_COMBOBOX_DATA Struct N_GUI_CTX Struct N_GUI_CUSTOM_DATA Struct N_GUI_DATAGRID_COL Struct N_GUI_DATAGRID_DATA Struct N_GUI_DROPMENU_DATA Struct N_GUI_DROPMENU_ENTRY Struct N_GUI_GRID_CALLBACKS Struct N_GUI_HEXVIEW_DATA Struct N_GUI_IMAGE_DATA Struct N_GUI_KVTABLE Struct N_GUI_KV_CONTENT Struct N_GUI_KV_ROW Struct N_GUI_LABEL_DATA Struct N_GUI_LISTBOX_DATA Struct N_GUI_LISTITEM Struct N_GUI_MARKDOWNVIEW_DATA Struct N_GUI_MD_FONTS Struct N_GUI_MD_STYLE Struct N_GUI_MEAS_ENTRY Struct N_GUI_MOUSE_EVENT Struct N_GUI_PENDING_GEOM Struct N_GUI_PENDING_WIDGET Struct N_GUI_POPUP Struct N_GUI_PROGRESSBAR_DATA Struct N_GUI_RADIOLIST_DATA Struct N_GUI_SB_TRACK Struct N_GUI_SCROLLBAR_DATA Struct N_GUI_SECTION Struct N_GUI_SECTIONLIST Struct N_GUI_SLIDER_DATA Struct N_GUI_SPLITPANE_DATA Struct N_GUI_STYLE Struct N_GUI_SUGGEST_SINK Struct N_GUI_SYNTAXVIEW_DATA Struct N_GUI_TAB_PANEL Struct N_GUI_TB_BUTTONS Struct N_GUI_TEXTAREA_DATA Struct N_GUI_TEXT_DIMS Struct N_GUI_THEME Struct N_GUI_TREE Struct N_GUI_TREE_NODE Struct N_GUI_TREE_STATE Struct N_GUI_WIDGET Struct N_GUI_WINDOW Struct N_H2_FRAME Struct N_H2_HEADER Struct N_H2_HPACK Struct N_H2_REQUEST Struct N_H2_SERVER Struct N_H2_SETTING Struct N_HTML_ATTR_ Struct N_HTML_FORM Struct N_HTML_TAG_ Struct N_HTTP3_RESPONSE Struct N_HTTP_FIELD Struct N_HTTP_FORM Struct N_HTTP_FORM_MULTIPART Struct N_HTTP_FORM_PART Struct N_HTTP_MULTIPART_PART Struct N_HTTP_REQUEST Struct N_HTTP_RESP Struct N_HTTP_RESPONSE Struct N_HTTP_SERVER Struct N_HTTP_SERVER_CONFIG Struct N_HTTP_SERVER_REQUEST Struct N_HTTP_SERVER_STATS Struct N_HTTP_SET_COOKIE Struct N_HTTP_STREAM Struct N_ISO_CAMERA Struct N_ISO_OBJECT Struct N_KAFKA Struct N_KAFKA_EVENT Struct N_MOCK_SERVER Struct N_MODULE Struct N_PARALLEL_SLICE Struct N_PARALLEL_TEAM Struct N_PARALLEL_WORKER Struct N_PCRE Struct N_PROXY_CFG Struct N_PTH Struct N_PTH_TENSOR Struct N_QUERY Struct N_ROUTE Struct N_ROUTER Struct N_ROUTE_MATCH Struct N_SHA256 Struct N_SOCKET Struct N_SPAWN_PIPE Struct N_SSE_CONN Struct N_SSE_EVENT Struct N_STR Struct N_TIFF Struct N_TIFF_ENTRY Struct N_TIME Struct N_URL Struct N_URL_PARAM Struct N_USER Struct N_USERLIST Struct N_WS_CONN Struct N_WS_FRAME Struct N_WS_MESSAGE Struct N_ZIP_MEMBER Struct OCTREE Struct OCTREE_NODE Struct PARSER Struct PARTICLE Struct PARTICLE_EMITTER Struct PARTICLE_SYSTEM Struct PEER Struct PHYSICS Struct PK_OBJ Struct PK_VM Struct POINT2D Struct POINT3D Struct PRETTY_OUT Struct QNODE Struct QUADTREE Struct QUADTREE_NODE Struct REC Struct RGB Struct SAMPLE Struct SEEN Struct SHARER Struct SRV Struct SRV_ARG Struct STACK Struct STACK_ITEM Struct SYNTAX_RUN Struct THREAD_POOL Struct THREAD_POOL_NODE Struct THREAD_WAITING_PROC Struct TRAJECTORY Struct TRAJECTORY_POINT Struct TREE Struct TREE_NODE Struct TS_LOG Struct WAYPOINT3D Struct WORKER_ARG Struct ZIP_SINK Struct _N_DC_ENTRY Struct _N_DC_GROUP_ENTRY Struct _N_GUI_COLORWHEEL Struct _N_GUI_COLORWHEEL_BLOCK Struct _N_GUI_COLORWHEEL_MOUSE Struct _N_GUI_CURVE Struct _N_GUI_CURVE_BLOCK Struct _N_GUI_CURVE_MOUSE Struct _N_GUI_GRID Struct _N_GUI_POPUP_ENTRY Struct _N_GUI_POPUP_LEVEL Struct _N_GUI_SB_SKIN Struct _N_GUI_TA_STEP Struct _N_GUI_THUMB Struct _N_GUI_WRAP_ACC Struct _compiled Struct _conn Struct _ip_slot Struct _mp_param Struct _n_civil Struct _seg Struct client Struct collector Struct date_vector Struct md_atom Struct md_cells Struct md_hit Struct md_line_ctx Struct mline Struct n_http_req_header Struct n_http_req_limits Struct n_http_request Struct n_markdown_block Struct n_markdown_doc Struct n_markdown_inline Struct n_markdown_span Struct n_reactor_stats Struct n_url_safe Struct n_url_safe_head Struct n_wrap_item Struct producer_state Struct rects Struct reply Struct runner Struct sink Struct tbuf Struct wrap_hit Struct wrap_span Structures Union COORD_VALUE Union HASH_DATA Union NODE_DATA_TYPES Union STACK_DATA dir_310dcdd4703e877a6b99d5dc3fc54d27 dir_68267d1309a1af8e8297ef4c3efbcdba dir_d28a4824dc47e487b107a5db32ef43c4 dir_d44c64559bbebec7f509842c48db8b23 ex__accept__pool__client_8c ex__accept__pool__server_8c ex__allegro__4_8c ex__atlas_8c ex__avro_8c ex__base64_8c ex__bind__exclusive_8c ex__clipboard_8c ex__clock__sync_8c ex__common_8c ex__configfile_8c ex__cookies_8c ex__crypto_8c ex__diff_8c ex__digest_8c ex__disk__cache_8c ex__dns_8c ex__ecc_8c ex__entropy_8c ex__exceptions_8c ex__file_8c ex__file__copy_8c ex__fluid_8c ex__fluid__config_8c ex__fluid__config_8h ex__git_8c ex__gui_8c ex__gui__bench_8c ex__gui__button__keys_8c ex__gui__checkbox__label_8c ex__gui__checkbox__release_8c ex__gui__color__picker_8c ex__gui__colorwheel_8c ex__gui__combobox__items_8c ex__gui__combobox__wheel_8c ex__gui__cursor_8c ex__gui__curve_8c ex__gui__custom_8c ex__gui__custom__mouse_8c ex__gui__datagrid_8c ex__gui__datagrid__keys_8c ex__gui__datagrid__sort_8c ex__gui__detach_8c ex__gui__dictionary_8c ex__gui__display__fallback_8c ex__gui__double__click_8c ex__gui__dropmenu_8c ex__gui__frameless__drag_8c ex__gui__global__scroll_8c ex__gui__glyph_8c ex__gui__grid_8c ex__gui__hexview_8c ex__gui__hover_8c ex__gui__isometric_8c ex__gui__kvtable_8c ex__gui__label__fits_8c ex__gui__label__lines_8c ex__gui__layout__persist_8c ex__gui__listbox_8c ex__gui__md_8c ex__gui__multiwin_8c ex__gui__network_8c ex__gui__particles_8c ex__gui__placeholder_8c ex__gui__popup_8c ex__gui__progressbar_8c ex__gui__reentrant_8c ex__gui__round_8c ex__gui__sectionlist_8c ex__gui__slider__default_8c ex__gui__slider__handle_8c ex__gui__slider__step_8c ex__gui__splitpane_8c ex__gui__suggest_8c ex__gui__syntaxview_8c ex__gui__text__shorten_8c ex__gui__textarea__selection_8c ex__gui__tooltip_8c ex__gui__tree__lazy_8c ex__gui__tree__order_8c ex__gui__tree__state_8c ex__gui__window__rect_8c ex__gui__zorder_8c ex__hash_8c ex__hex_8c ex__html_8c ex__http2_8c ex__http2__server_8c ex__http3_8c ex__http__cookie_8c ex__http__form_8c ex__http__mime_8c ex__http__req_8c ex__http__response_8c ex__http__router_8c ex__http__server_8c ex__icc_8c ex__iso__astar_8c ex__json_8c ex__kafka_8c ex__linalg_8c ex__list_8c ex__log_8c ex__markdown_8c ex__module_8c ex__monolith_8c ex__network_8c ex__network_8h ex__network__accept_8c ex__network__alpn_8c ex__network__connect__abort_8c ex__network__mock_8c ex__network__proxy_8c ex__network__reactor_8c ex__network__sni_8c ex__network__sse_8c ex__network__ssl_8c ex__network__ssl__hardened_8c ex__network__ssl__hostname_8c ex__network__ssl__nonblock_8c ex__network__tls__defaults_8c ex__network__ws_8c ex__network__ws__limits_8c ex__nstr_8c ex__parallel__for_8c ex__parallel__team_8c ex__pcre_8c ex__pretty_8c ex__pth_8c ex__query_8c ex__random_8c ex__sha256_8c ex__signals_8c ex__spawn_8c ex__ssrf_8c ex__stack_8c ex__thread__pool__discard_8c ex__thread__pool__wait_8c ex__threads_8c ex__tiff_8c ex__time__formats_8c ex__trajectory_8c ex__trees_8c ex__url_8c ex__url__safe_8c ex__wrap_8c ex__x509_8c ex__zip_8c ex__zlib_8c ex_accept_pool_client_8c example ex_accept_pool_server_8c example ex_allegro_4_8c example ex_atlas_8c example ex_base64_8c example ex_clock_sync_8c example ex_common_8c example ex_configfile_8c example ex_cookies_8c example ex_crypto_8c example ex_diff_8c example ex_digest_8c example ex_disk_cache_8c example ex_dns_8c example ex_ecc_8c example ex_entropy_8c example ex_exceptions_8c example ex_file_8c example ex_file_copy_8c example ex_fluid_8c example ex_fluid_config_8c example ex_fluid_config_8h example ex_git_8c example ex_gui_8c example ex_gui_bench_8c example ex_gui_button_keys_8c example ex_gui_checkbox_label_8c example ex_gui_checkbox_release_8c example ex_gui_color_picker_8c example ex_gui_colorwheel_8c example ex_gui_combobox_items_8c example ex_gui_combobox_wheel_8c example ex_gui_cursor_8c example ex_gui_curve_8c example ex_gui_custom_8c example ex_gui_custom_mouse_8c example ex_gui_datagrid_8c example ex_gui_datagrid_keys_8c example ex_gui_datagrid_sort_8c example ex_gui_detach_8c example ex_gui_dictionary_8c example ex_gui_display_fallback_8c example ex_gui_double_click_8c example ex_gui_dropmenu_8c example ex_gui_frameless_drag_8c example ex_gui_global_scroll_8c example ex_gui_glyph_8c example ex_gui_grid_8c example ex_gui_hexview_8c example ex_gui_hover_8c example ex_gui_isometric_8c example ex_gui_kvtable_8c example ex_gui_label_fits_8c example ex_gui_label_lines_8c example ex_gui_layout_persist_8c example ex_gui_listbox_8c example ex_gui_md_8c example ex_gui_multiwin_8c example ex_gui_network_8c example ex_gui_particles_8c example ex_gui_placeholder_8c example ex_gui_popup_8c example ex_gui_progressbar_8c example ex_gui_reentrant_8c example ex_gui_round_8c example ex_gui_sectionlist_8c example ex_gui_slider_default_8c example ex_gui_slider_handle_8c example ex_gui_slider_step_8c example ex_gui_splitpane_8c example ex_gui_suggest_8c example ex_gui_syntaxview_8c example ex_gui_text_shorten_8c example ex_gui_textarea_selection_8c example ex_gui_tooltip_8c example ex_gui_tree_lazy_8c example ex_gui_tree_order_8c example ex_gui_tree_state_8c example ex_gui_window_rect_8c example ex_gui_zorder_8c example ex_hash_8c example ex_hex_8c example ex_html_8c example ex_http2_8c example ex_http2_server_8c example ex_http_cookie_8c example ex_http_form_8c example ex_http_mime_8c example ex_http_req_8c example ex_http_response_8c example ex_http_router_8c example ex_http_server_8c example ex_icc_8c example ex_iso_astar_8c example ex_json_8c example ex_kafka_8c example ex_linalg_8c example ex_list_8c example ex_log_8c example ex_markdown_8c example ex_module_8c example ex_monolith_8c example ex_network_8c example ex_network_8h example ex_network_accept_8c example ex_network_alpn_8c example ex_network_connect_abort_8c example ex_network_mock_8c example ex_network_proxy_8c example ex_network_reactor_8c example ex_network_sni_8c example ex_network_sse_8c example ex_network_ssl_8c example ex_network_ssl_hardened_8c example ex_network_ssl_hostname_8c example ex_network_ssl_nonblock_8c example ex_network_tls_defaults_8c example ex_network_ws_8c example ex_network_ws_limits_8c example ex_nstr_8c example ex_parallel_for_8c example ex_parallel_team_8c example ex_pcre_8c example ex_pretty_8c example ex_pth_8c example ex_query_8c example ex_random_8c example ex_sha256_8c example ex_signals_8c example ex_spawn_8c example ex_ssrf_8c example ex_stack_8c example ex_threads_8c example ex_tiff_8c example ex_time_formats_8c example ex_trajectory_8c example ex_trees_8c example ex_url_8c example ex_url_safe_8c example ex_wrap_8c example ex_x509_8c example ex_zip_8c example ex_zlib_8c example mainpage_8dox n__3d_8c n__3d_8h n__aabb_8c n__aabb_8h n__allegro5_8c n__allegro5_8h n__allegro__4_8c n__allegro__4_8h n__anim_8c n__anim_8h n__astar_8c n__astar_8h n__atlas_8c n__atlas_8h n__avro_8c n__avro_8h n__base64_8c n__base64_8h n__clipboard_8c n__clipboard_8h n__clock__sync_8c n__clock__sync_8h n__common_8c n__common_8h n__config__file_8c n__config__file_8h n__cookies_8c n__cookies_8h n__crypto_8c n__crypto_8h n__dead__reckoning_8c n__dead__reckoning_8h n__diff_8c n__diff_8h n__digest_8c n__digest_8h n__disk__cache_8c n__disk__cache_8h n__dns_8c n__dns_8h n__ecc_8c n__ecc_8h n__entropy_8c n__entropy_8h n__enum_8h n__exceptions_8c n__exceptions_8h n__files_8c n__files_8h n__fluids_8c n__fluids_8h n__games_8c n__games_8h n__git_8c n__git_8h n__gui_8c n__gui_8h n__gui__color_8c n__gui__color_8h n__gui__colorwheel_8c n__gui__colorwheel_8h n__gui__curve_8c n__gui__curve_8h n__gui__grid_8c n__gui__grid_8h n__gui__md_8c n__gui__md_8h n__gui__popup_8c n__gui__popup_8h n__hash_8c n__hash_8h n__hex_8c n__hex_8h n__html_8c n__html_8h n__http2_8c n__http2_8h n__http2__server_8c n__http2__server_8h n__http3_8c n__http3_8h n__http__cookie_8c n__http__cookie_8h n__http__form_8c n__http__form_8h n__http__mime_8c n__http__mime_8h n__http__req_8c n__http__req_8h n__http__response_8c n__http__response_8h n__http__router_8c n__http__router_8h n__http__server_8c n__http__server_8h n__icc_8c n__icc_8h n__iso__engine_8c n__iso__engine_8h n__json_8c n__json_8h n__kafka_8c n__kafka_8h n__linalg_8c n__linalg_8h n__list_8c n__list_8h n__log_8c n__log_8h n__lz4_8c n__lz4_8h n__markdown_8c n__markdown_8h n__module_8c n__module_8h n__network_8c n__network_8h n__network__accept__pool_8c n__network__accept__pool_8h n__network__msg_8c n__network__msg_8h n__nodup__log_8c n__nodup__log_8h n__openssl__compat_8h n__particles_8c n__particles_8h n__pcre_8c n__pcre_8h n__pretty_8c n__pretty_8h n__pth_8c n__pth_8h n__query_8c n__query_8h n__random_8c n__random_8h n__reactor_8c n__reactor_8h n__sha256_8c n__sha256_8h n__signals_8c n__signals_8h n__ssrf_8c n__ssrf_8h n__stack_8c n__stack_8h n__str_8c n__str_8h n__thread__pool_8c n__thread__pool_8h n__tiff_8c n__tiff_8h n__time_8c n__time_8h n__trajectory_8c n__trajectory_8h n__trees_8c n__trees_8h n__url__safe_8c n__url__safe_8h n__user_8c n__user_8h n__windows_8h n__wrap_8c n__wrap_8h n__x509_8c n__x509_8h n__zip_8c n__zip_8h n__zlib_8c n__zlib_8h nilorea_8h
8 Module GUI
gullradriel edited this page 2026-10-29 20:54:40 +01:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

GUI: allegro5 widget system with pseudo-windows

More...

Structures

Name
struct N_GUI_WINDOW
A pseudo window that contains widgets.
struct N_GUI_WIDGET
A single GUI widget.
struct N_GUI_TREE_STATE
A tree's view state, captured by path so it survives a rebuild that replaces every node (a reloaded model has new pointers and new indices).
struct N_GUI_TREE_NODE
a single node in the tree view
struct N_GUI_TREE
tree view built from an N_GUI listbox
struct N_GUI_THEME
Color theme for a widget.
struct N_GUI_TEXT_DIMS
bounding box dimensions returned by n_gui_get_text_dims()
struct N_GUI_TEXTAREA_DATA
text area specific data
struct N_GUI_TB_BUTTONS
Titlebar button state for a window (minimize, maximize, close).
struct N_GUI_TAB_PANEL
tab panel built from toggle buttons with content window management
struct N_GUI_SYNTAXVIEW_DATA
syntax view specific data: read-only highlighted text
struct N_GUI_STYLE
Global style holding every configurable layout constant.
struct N_GUI_SPLITPANE_DATA
split pane specific data: a draggable divider between two regions
struct N_GUI_SLIDER_DATA
slider specific data
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
struct N_GUI_SECTION
a single foldable section: a clickable header plus the member widgets it shows/hides
struct N_GUI_SCROLLBAR_DATA
scrollbar specific data
struct N_GUI_SB_TRACK
Where a scrollbar a widget draws inside itself was last painted, and whether the pointer is on it.
struct N_GUI_RADIOLIST_DATA
radio list specific data
struct N_GUI_PROGRESSBAR_DATA
Progress-bar widget data (display only).
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).
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).
struct N_GUI_MOUSE_EVENT
A mouse event handed to a custom widget, in the widget's own coordinates.
struct N_GUI_MARKDOWNVIEW_DATA
markdownview specific data.
struct N_GUI_LISTITEM
a single item in a list/radio/combo widget
struct N_GUI_LISTBOX_DATA
listbox specific data
struct N_GUI_LABEL_DATA
static text label specific data
struct N_GUI_KV_ROW
a single row in the KV table
struct N_GUI_KVTABLE
key-value table built from textareas, checkboxes, and buttons.
struct N_GUI_IMAGE_DATA
image widget specific data
struct N_GUI_HEXVIEW_DATA
hex viewer specific data: a read-only byte dump
struct N_GUI_DROPMENU_ENTRY
A single entry in a dropdown menu (static or dynamic).
struct N_GUI_DROPMENU_DATA
dropdown menu specific data
struct N_GUI_DATAGRID_DATA
data grid specific data: a sortable column table
struct N_GUI_DATAGRID_COL
one data grid column definition
struct N_GUI_CUSTOM_DATA
Owner-draw custom widget data: a paint callback, an optional mouse callback, and their user pointers.
struct N_GUI_CTX
The top-level GUI context that holds all windows.
struct N_GUI_COMBOBOX_DATA
combo box specific data
struct N_GUI_CHECKBOX_DATA
checkbox specific data
struct N_GUI_BUTTON_DATA
button specific data

Types

Name
typedef int(*)(int src_node, int dst_node, int position, void *user_data) n_gui_tree_on_drop_t
drag-reorder drop callback.
typedef void(*)(const char *prefix, N_GUI_SUGGEST_SINK *sink, void *user_data) N_GUI_SUGGEST_FN
asked for the completions of what has been typed so far
typedef int(*)(int widget_id, const N_GUI_MOUSE_EVENT *ev, void *user_data) N_GUI_CUSTOM_MOUSE
Mouse callback for a custom widget, set with n_gui_custom_set_mouse().
typedef void(*)(N_GUI_WIDGET *widget, float x, float y, ALLEGRO_FONT *font, void *user_data) N_GUI_CUSTOM_DRAW
Owner-draw callback for a custom widget (N_GUI_TYPE_CUSTOM).

Functions

Name
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.
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_set_wheel_scrollbar(N_GUI_CTX * ctx, int window_id, int scrollbar_id)
make the wheel anywhere over a window move one of its scrollbars, for a window that scrolls its own rows with a scrollbar widget rather than with N_GUI_WIN_AUTO_SCROLLBAR (a fixed set of rows refilled from an offset).
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_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_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_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_rect_axes(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, int scale_x, int scale_y)
n_gui_window_set_rect with per-axis reflow control.
void n_gui_window_set_rect(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h)
move and resize a window at runtime, rescaling its child widgets from their normalized coordinates (what a split-pane divider drag or a collapsing panel needs, since the adaptive pass only runs on a display resize).
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_minimize_callback(N_GUI_CTX * ctx, int window_id, void(*)(int, void *) on_minimize, void * user_data)
set the minimize button callback for a window (NULL = default: toggle minimised)
void n_gui_window_set_maximize_callback(N_GUI_CTX * ctx, int window_id, void(*)(int, void *) on_maximize, void * user_data)
set the maximize button callback for a window (NULL = default: toggle maximised)
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_content_draw_callback(N_GUI_CTX * ctx, int window_id, void(*)(int, void *) on_content_draw, 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_close_callback(N_GUI_CTX * ctx, int window_id, void(*)(int, void *) on_close, void * user_data)
set the close button callback for a window (NULL = default: hide window)
void n_gui_window_set_caption(N_GUI_CTX * ctx, int window_id, const char * caption)
show a caption in a window's title bar in place of its title, for a title that carries live state ("Export - 3 photographs").
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_autofit(N_GUI_CTX * ctx, int window_id, int autofit_flags, float border)
configure auto-fit behavior for a dialog window
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.
int n_gui_window_is_open(N_GUI_CTX * ctx, int window_id)
check if window is visible
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_maximised(N_GUI_CTX * ctx, int window_id)
check if a window is currently maximised
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_get_zvalue(N_GUI_CTX * ctx, int window_id)
get window z-value (for N_GUI_ZORDER_FIXED mode)
int n_gui_window_get_zorder(N_GUI_CTX * ctx, int window_id)
get window z-order mode
int n_gui_window_get_resize_policy(N_GUI_CTX * ctx, int window_id)
get per-window resize policy
int n_gui_window_get_flags(N_GUI_CTX * ctx, int window_id)
get feature flags of a window
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_from_display(N_GUI_CTX * ctx, ALLEGRO_DISPLAY * display)
find the window detached into a given display
int n_gui_window_find_button(N_GUI_CTX * ctx, int window_id, const char * label)
Find the button in a window whose label is exactly this.
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_button_rect(N_GUI_CTX * ctx, int window_id, int btn_type, float * x, float * y, float * w, float * h)
Where one of a window's title bar buttons is, on screen.
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_attach(N_GUI_CTX * ctx, int window_id)
return a detached window to being an in-display pop-up
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_widget_set_rect(N_GUI_CTX * ctx, int widget_id, float x, float y, float w, float h)
move/resize a widget after creation, refreshing the normalized coordinates the resize passes read.
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.
int n_gui_widget_screen_rect(N_GUI_CTX * ctx, int widget_id, float * x, float * y, float * w, float * h)
Where a widget is on screen, rather than inside its window.
int n_gui_widget_is_visible(N_GUI_CTX * ctx, int widget_id)
Is a widget currently shown.
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.
int n_gui_was_double_click(const N_GUI_CTX * ctx, int widget_id)
whether the press just processed double clicked this particular widget
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_update_transform(N_GUI_CTX * ctx)
recalculate scale and offset from virtual canvas to display.
void n_gui_tree_toggle_expand(N_GUI_TREE * tree, int node_index)
toggle expand/collapse of a node.
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.
int n_gui_tree_state_save(const N_GUI_TREE * tree, N_GUI_TREE_STATE * out)
capture which nodes are expanded, which one is selected, and where the view is scrolled, all by path.
void n_gui_tree_state_free(N_GUI_TREE_STATE * state)
release the strings owned by a saved state (safe on a zeroed struct)
void n_gui_tree_state_apply(N_GUI_TREE * tree, const N_GUI_TREE_STATE * state)
re-expand, re-select and re-scroll a rebuilt tree from a saved state.
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_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_label(N_GUI_TREE * tree, int node_index, const char * new_label)
change the display label of a node
void n_gui_tree_set_expandable(N_GUI_TREE * tree, int node_index, int expandable)
mark a node as openable before it has children, so it shows an expander and the expand callback fills it when it is opened
void n_gui_tree_set_expand_callback(N_GUI_TREE * tree, void(*)(int node_index, void *user_data) on_expand, void * user_data)
set the callback that fills a node the first time it is opened, for a tree too large to build before it is shown: a folder tree reads a directory only when somebody opens it.
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_rebuild(N_GUI_TREE * tree)
rebuild the listbox to reflect current tree state
int n_gui_tree_node_path(const N_GUI_TREE * tree, int node_index, char * buf, size_t bufsz)
write the path of a node (its label and its ancestors', joined by N_GUI_TREE_PATH_SEP) into buf.
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_free(N_GUI_TREE ** tree)
free a tree view (does not destroy the N_GUI 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.
int n_gui_tree_find_by_path(const N_GUI_TREE * tree, const char * path)
index of the first node with the given path, or -1.
void n_gui_tree_expand(N_GUI_TREE * tree, int node_index)
open a node, filling it first through the expand callback if it has not been; a node already open stays open.
void n_gui_tree_draw_overlay(N_GUI_TREE * tree)
per-frame overlay drawing: draws the active drop-indicator on top of the listbox.
N_GUI_TREE * n_gui_tree_create(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, void(*)(int, void *) on_select, void * user_data)
create a tree view in an existing window
void n_gui_tree_clear(N_GUI_TREE * tree)
remove all nodes and clear the backing listbox; tree object remains valid
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
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)
void n_gui_toggle_window(N_GUI_CTX * ctx, int window_id)
toggle window visibility (show/hide)
int n_gui_textarea_suggest_is_open(N_GUI_CTX * ctx, int widget_id)
is a textarea's completion panel up
void n_gui_textarea_suggest_close(N_GUI_CTX * ctx, int widget_id)
put a textarea's completion panel away
void n_gui_textarea_set_text(N_GUI_CTX * ctx, int widget_id, const char * text)
set text area content
void n_gui_textarea_set_suggest(N_GUI_CTX * ctx, int widget_id, N_GUI_SUGGEST_FN fn, const char * separators, void * user_data)
offer completions in a textarea
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_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_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_bitmap(N_GUI_CTX * ctx, int widget_id, ALLEGRO_BITMAP * bg)
set optional background bitmap on a textarea widget.
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_scroll_to_bottom(N_GUI_CTX * ctx, int widget_id)
scroll a multiline textarea to the bottom
int n_gui_textarea_has_selection(N_GUI_CTX * ctx, int widget_id)
is any text selected in a text area (0 for no selection or a bad id)
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)
const char * n_gui_textarea_get_text(N_GUI_CTX * ctx, int widget_id)
get text area content
int n_gui_text_shorten(ALLEGRO_FONT * font, const char * text, float max_w, int mode, char * out, size_t out_len)
shorten text to fit max_w pixels in font, the way a label with truncate mode mode shows it: unchanged when it fits, otherwise with "..." at the end, at the start, or in place of whole leading path components (N_GUI_TRUNCATE_END, _START, _PATH).
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
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_relayout(N_GUI_TAB_PANEL * panel, float x, float y, float button_w, float button_h)
move/resize the button row after creation (a host-owned or resizable layout); pass <= 0 for button_w / button_h to keep the current value.
int n_gui_tab_get_active(const N_GUI_TAB_PANEL * panel)
get the active tab index
void n_gui_tab_free(N_GUI_TAB_PANEL ** panel)
free a tab panel (does not destroy the N_GUI widgets)
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(*)(int, void *) on_tab_change, void * user_data)
create a tab panel in an existing window
int n_gui_tab_add(N_GUI_TAB_PANEL * panel, const char * label)
add a tab to the panel, returns tab index
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
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_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_h_scroll(N_GUI_CTX * ctx, int widget_id, float px)
set the horizontal scroll offset of a syntax view, in pixels (clamped to the content width by the draw path)
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_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, and horizontally so the offset itself is inside the visible width
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)
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.
int n_gui_syntaxview_get_line_count(N_GUI_CTX * ctx, int widget_id)
get the number of text lines in a syntax view
float n_gui_syntaxview_get_h_scroll(N_GUI_CTX * ctx, int widget_id)
current horizontal scroll offset of a syntax view, in pixels.
float n_gui_syntaxview_content_width(N_GUI_CTX * ctx, int widget_id)
pixel width the widest line of a syntax view needs, padding included
int n_gui_suggest_add(N_GUI_SUGGEST_SINK * sink, const char * text)
add one completion to a suggestion sink
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)
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
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
float n_gui_splitpane_band(N_GUI_CTX * ctx, int widget_id)
How far either side of a split pane's divider a press still counts as the divider's.
int n_gui_splitpane_at(N_GUI_CTX * ctx, float x, float y)
report the split pane whose divider band is under a point, or -1.
float n_gui_slider_value_width(N_GUI_CTX * ctx, int widget_id)
width in pixels a slider's built-in readout needs beside it, the gap between track and text included.
void n_gui_slider_set_value_visible(N_GUI_CTX * ctx, int widget_id, int visible)
Toggle the built-in value label.
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(N_GUI_CTX * ctx, int widget_id, double value)
set slider value
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_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_key_step(N_GUI_CTX * ctx, int widget_id, double step)
set how far one arrow key press or wheel notch moves a slider, without snapping its drag
void n_gui_slider_set_default(N_GUI_CTX * ctx, int widget_id, double value)
Give a slider a default value, which a double click on it puts back.
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.
int n_gui_slider_handle_pos(N_GUI_CTX * ctx, int widget_id, float * pos, float * radius)
Where a slider's handle is drawn and how big it is.
double n_gui_slider_get_value(N_GUI_CTX * ctx, int widget_id)
get slider current value
double n_gui_slider_get_key_step(N_GUI_CTX * ctx, int widget_id)
get the arrow key and wheel increment actually in use for a slider
int n_gui_slider_get_default(N_GUI_CTX * ctx, int widget_id, double * value)
A slider's default, as n_gui_slider_set_default() gave it.
void n_gui_set_widget_visible(N_GUI_CTX * ctx, int widget_id, int visible)
set widget visibility
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_theme(N_GUI_CTX * ctx, int widget_id, N_GUI_THEME theme)
set the theme on a widget
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_virtual_size(N_GUI_CTX * ctx, float w, float h)
set the virtual canvas size for resolution-independent scaling.
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_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_focus(N_GUI_CTX * ctx, int widget_id)
set keyboard focus to a specific widget (-1 to clear focus)
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_dpi_scale(N_GUI_CTX * ctx, float scale)
set DPI scale factor manually (default is 1.0).
void n_gui_set_double_click_time(N_GUI_CTX * ctx, double seconds)
how long after a press a second one still counts, in seconds (default 0.4)
void n_gui_set_double_click_radius(N_GUI_CTX * ctx, int pixels)
how far the pointer may move between the two presses, in pixels (default 4)
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_display(N_GUI_CTX * ctx, ALLEGRO_DISPLAY * display)
set the display pointer for clipboard operations (copy/paste)
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.
int n_gui_set_default_font(N_GUI_CTX * ctx, ALLEGRO_FONT * font)
Replace the context's default font, keeping every widget and its state.
void n_gui_set_cursor(N_GUI_CTX * ctx, int system_shape, ALLEGRO_MOUSE_CURSOR * custom)
Say which mouse cursor the application wants.
void n_gui_sectionlist_set_widget_offset(N_GUI_SECTIONLIST * sl, int section_index, int widget_id, float dy)
state a member's y offset from the section's content top, for a caller that computes its own layout and recomputes it when the window is resized.
void n_gui_sectionlist_set_widget_hidden(N_GUI_SECTIONLIST * sl, int section_index, int widget_id, int hidden)
keep a member hidden whatever the fold state, and leave it out of the section's height.
void n_gui_sectionlist_set_section_hidden(N_GUI_SECTIONLIST * sl, int section_index, int hidden)
Leave a whole section out of the stack, header and members, or put it back.
void n_gui_sectionlist_set_order(N_GUI_SECTIONLIST * sl, const int * order, int count)
Stack the sections in another order.
void n_gui_sectionlist_set_geometry(N_GUI_SECTIONLIST * sl, float x, float y0, float width, float header_h, float gap)
restate where the list stacks from, how wide its headers are and the two heights it stacks with, for a caller whose window is resized or whose interface scale changes after the list was made.
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_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_relayout(N_GUI_SECTIONLIST * sl)
re-stack all sections from y0 by current fold state: hide folded members, show and reposition expanded ones
int n_gui_sectionlist_is_section_hidden(const N_GUI_SECTIONLIST * sl, int section_index)
Is a section left out of the stack.
int n_gui_sectionlist_is_folded(const N_GUI_SECTIONLIST * sl, int section_index)
query a section's folded state (1 = folded, 0 = expanded)
int n_gui_sectionlist_get_order(const N_GUI_SECTIONLIST * sl, int position)
The section stacked at a position.
int n_gui_sectionlist_get_count(const N_GUI_SECTIONLIST * sl)
number of sections in the list
void n_gui_sectionlist_free(N_GUI_SECTIONLIST ** sl)
free the section list (does not destroy the N_GUI widgets or 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(*)(int, int, void *) on_toggle, void * user_data)
create an empty section list anchored at (x,y0) in window_id; sections stack downward from y0
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
int 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).
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_scrollbar_set_wheel_step(N_GUI_CTX * ctx, int widget_id, double step)
set how far one wheel notch moves a scrollbar, in its content units: 1 for a list whose content is counted in rows moves it a row a notch.
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_scrollbar_set_pos(N_GUI_CTX * ctx, int widget_id, double pos)
set 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.
double n_gui_scrollbar_get_pos(N_GUI_CTX * ctx, int widget_id)
get scrollbar position
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.
int n_gui_save_theme_json(N_GUI_CTX * ctx, const char * filepath)
Save the full theme (default_theme + style) to a JSON file.
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.
void n_gui_restore_window(N_GUI_CTX * ctx, int window_id)
restore a minimised window to its full size
void n_gui_reset_all_widget_themes(N_GUI_CTX * ctx)
reset all widget and window themes to ctx->default_theme
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_radiolist_set_selected(N_GUI_CTX * ctx, int widget_id, int index)
set 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.
int n_gui_radiolist_get_selected(N_GUI_CTX * ctx, int widget_id)
get the selected item index
void n_gui_radiolist_clear(N_GUI_CTX * ctx, int widget_id)
remove all items from a radio list
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_progressbar_set_value(N_GUI_CTX * ctx, int widget_id, float value)
set the progress fraction (clamped to 0.0 .
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)
float n_gui_progressbar_get_value(N_GUI_CTX * ctx, int widget_id)
get the current progress fraction (0.0 on an invalid widget)
int n_gui_process_event(N_GUI_CTX * ctx, ALLEGRO_EVENT event)
process an allegro event for the GUI
void n_gui_open_window(N_GUI_CTX * ctx, int window_id)
open (show) a window
N_GUI_CTX * n_gui_new_ctx(ALLEGRO_FONT * default_font)
create a new GUI context
int n_gui_needs_redraw(N_GUI_CTX * ctx)
Return non-zero if the GUI must be redrawn this frame, i.e.
void n_gui_minimize_window(N_GUI_CTX * ctx, int window_id)
minimize a window (title bar only)
int n_gui_menu_is_open(const N_GUI_CTX * ctx)
Is a combo box's list or a drop menu's panel currently open.
void n_gui_maximize_window(N_GUI_CTX * ctx, int window_id)
toggle maximised state (full display or restore to previous size)
N_GUI_MD_STYLE * n_gui_markdownview_style(N_GUI_CTX * ctx, int widget_id)
the view's style, to read or to change in place, or NULL if there is no such widget.
void n_gui_markdownview_set_text(N_GUI_CTX * ctx, int widget_id, const char * text)
set the Markdown source (copied; NULL clears it).
void n_gui_markdownview_set_on_link(N_GUI_CTX * ctx, int widget_id, void(*)(int widget_id, const char *url, void *user_data) on_link, void * user_data)
call on_link when a link in the view is clicked (NULL to stop).
void n_gui_markdownview_set_fonts(N_GUI_CTX * ctx, int widget_id, const N_GUI_MD_FONTS * fonts)
replace the faces; the new ones are borrowed on the same terms
void n_gui_markdownview_scroll_to(N_GUI_CTX * ctx, int widget_id, float y)
scroll to y pixels down the content, clamped to what there is
const char * n_gui_markdownview_get_text(N_GUI_CTX * ctx, int widget_id)
the Markdown source, owned by the widget, or NULL
float n_gui_markdownview_get_scroll(N_GUI_CTX * ctx, int widget_id)
how far down the content the view is, in pixels
float n_gui_markdownview_content_height(N_GUI_CTX * ctx, int widget_id)
the height of the whole document at the width it was last drawn at, or 0 before the first draw
void n_gui_mark_dirty(N_GUI_CTX * ctx)
Mark the GUI as needing a redraw.
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_lower_window(N_GUI_CTX * ctx, int window_id)
lower a window to the bottom of the stack (respects z-order constraints)
int n_gui_load_theme_json(N_GUI_CTX * ctx, const char * filepath)
Load a JSON theme file and apply it to the context.
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.
void n_gui_listbox_set_selected(N_GUI_CTX * ctx, int widget_id, int index, int selected)
set item selection state
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_h_scroll(N_GUI_CTX * ctx, int widget_id, float px)
set the horizontal scroll offset in pixels; clamped to >= 0 here and to the live content width by the draw path, so a stale value after a refill is harmless
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.
int n_gui_listbox_remove_item(N_GUI_CTX * ctx, int widget_id, int index)
remove an item from a listbox by 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_get_selected(N_GUI_CTX * ctx, int widget_id)
get the first selected item index
int n_gui_listbox_get_scroll_offset(N_GUI_CTX * ctx, int widget_id)
get the current scroll offset (in items)
const char * n_gui_listbox_get_item_text(N_GUI_CTX * ctx, int widget_id, int index)
get item text by index
float n_gui_listbox_get_h_scroll(N_GUI_CTX * ctx, int widget_id)
current horizontal scroll offset in pixels (0 = leftmost)
int n_gui_listbox_get_count(N_GUI_CTX * ctx, int widget_id)
get number of items in a listbox
float n_gui_listbox_content_width(N_GUI_CTX * ctx, int widget_id)
width in pixels the widest item needs to be drawn in full (text padding included), or 0 for an empty list / non-listbox widget.
void n_gui_listbox_clear(N_GUI_CTX * ctx, int widget_id)
clear all items from a listbox
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_label_set_truncate(N_GUI_CTX * ctx, int widget_id, int mode)
choose where a label's text is shortened when it does not fit: N_GUI_TRUNCATE_END (the default), N_GUI_TRUNCATE_START or N_GUI_TRUNCATE_PATH.
void n_gui_label_set_text(N_GUI_CTX * ctx, int widget_id, const char * text)
set label text content
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_bitmap(N_GUI_CTX * ctx, int widget_id, ALLEGRO_BITMAP * bg)
set optional background bitmap on a label widget.
int n_gui_label_get_truncate(N_GUI_CTX * ctx, int widget_id)
the label's truncate mode, N_GUI_TRUNCATE_END when it is not a label
const char * n_gui_label_get_text(N_GUI_CTX * ctx, int widget_id)
What a label says now.
int n_gui_label_fits(N_GUI_CTX * ctx, int widget_id, float * needed_w, float * needed_h)
report whether a label's text is drawn in full inside its own box, and how big it would have to be to show all of it (out-params may be NULL)
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_kvtable_set_row_actions(N_GUI_KVTABLE * table, int enabled)
show (1) or hide (0, the default) the per-row action buttons: move up, move down and duplicate, drawn as glyphs next to the remove button.
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_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_remove_row(N_GUI_KVTABLE * table, int row_index)
remove a row by index (hides widgets, marks inactive)
void n_gui_kvtable_relayout(N_GUI_KVTABLE * table)
re-apply layout to all KV table widgets (positions, sizes, normalized coords).
int n_gui_kvtable_move_row(N_GUI_KVTABLE * table, int row_index, int direction)
move the row at row_index one position up (direction < 0) or down (direction > 0) among the ACTIVE rows, by swapping their contents.
int n_gui_kvtable_get_count(const N_GUI_KVTABLE * table)
get the number of active rows
void n_gui_kvtable_free(N_GUI_KVTABLE ** table)
free a KV table (does not destroy the N_GUI widgets)
int n_gui_kvtable_duplicate_row(N_GUI_KVTABLE * table, int row_index)
insert a copy of the row at row_index directly after it.
N_GUI_KVTABLE * n_gui_kvtable_create(N_GUI_CTX * ctx, int window_id, float row_height, float padding, void(*)(int, void *) on_remove, void * user_data)
create a KV table in an existing window
void n_gui_kvtable_clear(N_GUI_KVTABLE * table)
remove every row at once.
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
int n_gui_is_widget_enabled(N_GUI_CTX * ctx, int widget_id)
check if a widget is enabled
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_hovered_widget(const N_GUI_CTX * ctx)
id of the widget currently under the mouse pointer (hover/active flag, maintained by n_gui_process_event; front-most open window wins), or -1.
void n_gui_hexview_set_on_change(N_GUI_CTX * ctx, int widget_id, void(*)(int, const unsigned char *, size_t, void *) on_change, void * user_data)
set the callback fired after each edit (NULL to clear)
void n_gui_hexview_set_editable(N_GUI_CTX * ctx, int widget_id, int editable)
make a hex view editable (or read-only again)
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_hexview_set_cursor(N_GUI_CTX * ctx, int widget_id, size_t offset)
move the edit cursor to a byte offset (clamped to the data length)
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
const unsigned char * n_gui_hexview_get_data(N_GUI_CTX * ctx, int widget_id, size_t * len)
borrow the bytes a hex view holds (valid until the next edit or set_data); *len receives the count.
size_t n_gui_hexview_get_cursor(N_GUI_CTX * ctx, int widget_id)
the byte offset the edit cursor sits on
N_GUI_WINDOW * n_gui_get_window(N_GUI_CTX * ctx, int window_id)
get a window by id
N_GUI_WIDGET * n_gui_get_widget(N_GUI_CTX * ctx, int widget_id)
get a widget by id
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_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_shape_mode(N_GUI_CTX * ctx)
get the global widget shape (N_GUI_SHAPE_ROUNDED or N_GUI_SHAPE_RECT)
int n_gui_get_resize_mode(N_GUI_CTX * ctx)
get current resize mode
int n_gui_get_key_modifiers(const N_GUI_CTX * ctx)
the modifier keys held down now, as the GUI has seen them
int n_gui_get_focus(const N_GUI_CTX * ctx)
Which widget has the keyboard, or -1 when none has.
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)
float n_gui_get_dpi_scale(const N_GUI_CTX * ctx)
get current DPI scale factor
int n_gui_get_cursor(N_GUI_CTX * ctx, ALLEGRO_MOUSE_CURSOR ** custom)
The cursor the GUI last applied to the display.
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)
int n_gui_focus_takes_key(const N_GUI_CTX * ctx, int keycode)
Would the focused widget do something with this particular key.
int n_gui_dropmenu_set_open(N_GUI_CTX * ctx, int widget_id, int open)
open or close a dropdown menu without anybody clicking its button.
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_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_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_bitmaps(N_GUI_CTX * ctx, int widget_id, ALLEGRO_BITMAP * panel, ALLEGRO_BITMAP * item_hover)
set optional bitmap overlays on a dropmenu widget.
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).
int n_gui_dropmenu_is_open(N_GUI_CTX * ctx, int widget_id)
is a dropdown menu's panel showing
int n_gui_dropmenu_get_count(N_GUI_CTX * ctx, int widget_id)
get number of 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)
void n_gui_dropmenu_clear(N_GUI_CTX * ctx, int widget_id)
remove all entries
int n_gui_dropmenu_add_entry(N_GUI_CTX * ctx, int widget_id, const char * text, int tag, void(*)(int, int, int, void *) on_click, void * user_data)
add a static entry to a dropdown menu
int n_gui_dropmenu_add_dynamic_entry(N_GUI_CTX * ctx, int widget_id, const char * text, int tag, void(*)(int, int, int, void *) on_click, void * user_data)
add a dynamic entry (rebuilt each time menu opens)
void n_gui_draw_detached(N_GUI_CTX * ctx)
render and flip every detached window, and release the ones whose native window was closed.
void n_gui_draw(N_GUI_CTX * ctx)
draw all visible GUI windows and widgets
int n_gui_double_clicked_widget(const N_GUI_CTX * ctx)
id of the widget the primary press just processed double clicked, or -1.
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_destroy_ctx(N_GUI_CTX ** ctx)
destroy a GUI context and free all resources
N_GUI_THEME n_gui_default_theme(void )
return the built-in default theme
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_tb_btn_theme(void )
return the built-in default theme for titlebar minimize/maximize buttons
N_GUI_STYLE n_gui_default_style(void )
return the built-in default style
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)
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_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_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_on_context(N_GUI_CTX * ctx, int widget_id, void(*)(int, int, int, int, void *) on_context)
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_on_columns_changed(N_GUI_CTX * ctx, int widget_id, void(*)(int, void *) cb)
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_multiselect(N_GUI_CTX * ctx, int widget_id, int enabled)
enable (1) or disable (0) multi-row selection.
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_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_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_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_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)
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)
int n_gui_datagrid_get_sort(N_GUI_CTX * ctx, int widget_id, int * col, int * dir)
read back the sort a datagrid is currently showing.
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_get_selected(N_GUI_CTX * ctx, int widget_id)
get the selected row index, or -1 if none
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_row_count(N_GUI_CTX * ctx, int widget_id)
get the number of rows in a data grid
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.
float n_gui_datagrid_get_h_scroll(N_GUI_CTX * ctx, int widget_id)
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
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
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
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_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
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
float n_gui_datagrid_columns_width(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.
void n_gui_datagrid_clear_selection(N_GUI_CTX * ctx, int widget_id)
clear the entire selection (no row selected)
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_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_row_color(N_GUI_CTX * ctx, int widget_id, int row)
remove the background tint of data row row (it draws untinted again)
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
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
void n_gui_custom_set_mouse(N_GUI_CTX * ctx, int widget_id, N_GUI_CUSTOM_MOUSE on_mouse, void * user_data)
give a custom widget mouse input
void n_gui_custom_set_destroy(N_GUI_CTX * ctx, int widget_id, void(*)(void *user_data) destroy)
hand a custom widget's paint user pointer to the widget
int n_gui_count_detached(N_GUI_CTX * ctx)
count the windows currently detached into native OS windows
void n_gui_combobox_set_selected(N_GUI_CTX * ctx, int widget_id, int index)
set the selected item index
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_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.
int n_gui_combobox_remove_item(N_GUI_CTX * ctx, int widget_id, int index)
remove the item at index from a combobox.
int n_gui_combobox_get_selected(N_GUI_CTX * ctx, int widget_id)
get the selected item index
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_count(N_GUI_CTX * ctx, int widget_id)
get the number of items in a combobox (0 if not a combobox).
void n_gui_combobox_clear(N_GUI_CTX * ctx, int widget_id)
remove all items from a combobox
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_close_window(N_GUI_CTX * ctx, int window_id)
close (hide) a window
void n_gui_close_menus(N_GUI_CTX * ctx)
Put away any open combo box list or drop menu panel.
void n_gui_checkbox_set_label(N_GUI_CTX * ctx, int widget_id, const char * label)
Replace the text drawn beside a checkbox.
void n_gui_checkbox_set_checked(N_GUI_CTX * ctx, int widget_id, int checked)
set checkbox checked state
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.
int n_gui_checkbox_is_checked(N_GUI_CTX * ctx, int widget_id)
check if checkbox is checked
const char * n_gui_checkbox_get_label(N_GUI_CTX * ctx, int widget_id)
What a checkbox says.
void n_gui_button_set_toggled(N_GUI_CTX * ctx, int widget_id, int toggled)
set button toggled state
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_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_label(N_GUI_CTX * ctx, int widget_id, const char * label)
replace the label text drawn on 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_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_glyph(N_GUI_CTX * ctx, int widget_id, int glyph)
draw an N_GUI_GLYPH_* icon (primitives, in the button's text colour) instead of the label; N_GUI_GLYPH_NONE restores the label.
int n_gui_button_is_toggled(N_GUI_CTX * ctx, int widget_id)
check if button is toggled
const char * n_gui_button_get_label(N_GUI_CTX * ctx, int widget_id)
What a button says.
int n_gui_button_get_glyph(N_GUI_CTX * ctx, int widget_id)
current glyph of a button, or N_GUI_GLYPH_NONE when it draws its label (also for a non-button widget)
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_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)
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_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(*)(int, double, void *) on_change, void * user_data)
add a vertical slider (same as n_gui_add_slider but oriented vertically)
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(*)(int, void *) on_click, void * user_data)
toggle button creation (returns widget id)
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(*)(int, const char *, void *) on_change, void * user_data)
add a text area widget
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_splitpane(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, int orientation, float ratio, void(*)(int, float, void *) on_change, void * user_data)
add a split pane (draggable divider); returns the widget id or -1
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(*)(int, double, void *) on_change, void * user_data)
add a horizontal slider 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(*)(int, double, void *) on_scroll, void * user_data)
add a scrollbar widget
int n_gui_add_radiolist(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, void(*)(int, int, void *) on_select, void * user_data)
add a radio list 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_markdownview(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, const N_GUI_MD_FONTS * fonts)
add a read-only scrolling Markdown view.
int n_gui_add_listbox(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, int selection_mode, void(*)(int, int, int, void *) on_select, void * user_data)
add a listbox 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(*)(int, const char *, void *) on_link_click, void * user_data)
add a text label with hyperlink
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_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_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_dropmenu(N_GUI_CTX * ctx, int window_id, const char * label, float x, float y, float w, float h, void(*)(int, void *) on_open, void * on_open_user_data)
add a dropdown menu widget (button that opens a menu panel with entries)
int n_gui_add_datagrid(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, void(*)(int, int, void *) on_select, void * user_data)
add a sortable data grid; returns the widget id or -1
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_combobox(N_GUI_CTX * ctx, int window_id, float x, float y, float w, float h, void(*)(int, int, void *) on_select, void * user_data)
add a combo box 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(*)(int, int, void *) on_toggle, void * user_data)
add a checkbox 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(*)(int, void *) on_click, void * user_data)
add a bitmap-based button widget
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(*)(int, void *) on_click, void * user_data)
add a button widget

Defines

Name
N_GUI_ZORDER_POPUP
popup/modal dialogs: drawn above EVERYTHING including ALWAYS_ON_TOP windows.
N_GUI_ZORDER_NORMAL
default z-order: window participates in normal raise/lower ordering
N_GUI_ZORDER_FIXED
fixed z-value: window is sorted within a dedicated group between ALWAYS_BEHIND and NORMAL windows.
N_GUI_ZORDER_ALWAYS_ON_TOP
always drawn on top of normal windows, cannot be lowered behind them
N_GUI_ZORDER_ALWAYS_BEHIND
always drawn behind normal windows, cannot be raised above them
N_GUI_WIN_VSCROLL_HOVER
pointer is over the window's vertical auto-scrollbar
N_GUI_WIN_VSCROLL_DRAG
window vertical auto-scrollbar is being dragged
N_GUI_WIN_RESIZING
window is being resized
N_GUI_WIN_RESIZE_SCALE
reposition AND resize proportionally, child widgets scale too
N_GUI_WIN_RESIZE_NONE
no adaptation: absolute position and size unchanged
N_GUI_WIN_RESIZE_MOVE
reposition proportionally, keep pixel size
N_GUI_WIN_RESIZABLE
enable user-resizable window with a drag handle at bottom-right
N_GUI_WIN_OPEN
window is visible
N_GUI_WIN_NO_HSCROLL
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
N_GUI_WIN_MINIMISED
window is minimised (title bar only)
N_GUI_WIN_MAXIMISED
window is maximised (full display size)
N_GUI_WIN_HSCROLL_HOVER
pointer is over the window's horizontal auto-scrollbar
N_GUI_WIN_HSCROLL_DRAG
window horizontal auto-scrollbar is being dragged
N_GUI_WIN_FRAMELESS
frameless window: no title bar drawn, drag via window body unless N_GUI_WIN_FIXED_POSITION is also set
N_GUI_WIN_FIXED_POSITION
disable window dragging (default:enable)
N_GUI_WIN_DRAGGING
window is being dragged
N_GUI_WIN_BTN_MINIMIZE
enable minimize button on the title bar
N_GUI_WIN_BTN_MAXIMIZE
enable maximize/restore button on the title bar
N_GUI_WIN_BTN_CLOSE
enable close button on the title bar
N_GUI_WIN_BTN_ALL
enable all three title bar buttons (minimize + maximize + close)
N_GUI_WIN_AUTO_SCROLLBAR
enable automatic scrollbars when content exceeds window size
N_GUI_TYPE_TEXTAREA
widget type: text area
N_GUI_TYPE_SYNTAXVIEW
widget type: read-only syntax-highlighted text view
N_GUI_TYPE_SPLITPANE
widget type: split pane with a draggable divider between two regions
N_GUI_TYPE_SLIDER
widget type: slider
N_GUI_TYPE_SCROLLBAR
widget type: scrollbar
N_GUI_TYPE_RADIOLIST
widget type: radio list (single select radio buttons)
N_GUI_TYPE_PROGRESSBAR
widget type: horizontal progress bar (display only)
N_GUI_TYPE_MARKDOWNVIEW
widget type: read-only scrolling Markdown view
N_GUI_TYPE_LISTBOX
widget type: listbox (selectable list)
N_GUI_TYPE_LABEL
widget type: static text label (with optional hyperlink)
N_GUI_TYPE_IMAGE
widget type: image display
N_GUI_TYPE_HEXVIEW
widget type: read-only hexadecimal byte viewer
N_GUI_TYPE_DROPMENU
widget type: dropdown menu with static and dynamic entries
N_GUI_TYPE_DATAGRID
widget type: sortable column data grid
N_GUI_TYPE_CUSTOM
widget type: owner-draw custom widget (rendering delegated to a callback)
N_GUI_TYPE_COMBOBOX
widget type: combo box (dropdown)
N_GUI_TYPE_CHECKBOX
widget type: checkbox
N_GUI_TYPE_BUTTON
widget type: button
N_GUI_TRUNCATE_START
text too wide for its box is cut at the start, "...ong sentence": for anything whose end is what tells it apart
N_GUI_TRUNCATE_PATH
a path too wide for its box loses whole leading components, ".../photos/IMG_0001.CR3", and the file name only if it is wider than the box on its own; both '/' and '' separate components
N_GUI_TRUNCATE_END
text too wide for its box is cut at the end, "Long senten...": the default, right for a sentence
N_GUI_TREE_STATE_MAX
maximum number of expanded paths remembered by an N_GUI_TREE_STATE
N_GUI_TREE_PATH_SEP
separator joining the labels of a node path.
N_GUI_TREE_PATH_MAX
maximum length of a node path (labels from the root, joined)
N_GUI_TREE_MAX
maximum number of nodes in a tree view
N_GUI_TEXT_MAX
maximum length for textarea content
N_GUI_TB_BTN_NONE
no titlebar button
N_GUI_TB_BTN_MINIMIZE
minimize titlebar button
N_GUI_TB_BTN_MAXIMIZE
maximize/restore titlebar button
N_GUI_TB_BTN_CLOSE
close titlebar button
N_GUI_TAB_MAX
maximum number of tabs in a single tab panel
N_GUI_SYNTAX_YAML
syntax view: YAML highlighting (keys, quoted values, list markers, comments)
N_GUI_SYNTAX_XML
syntax view: XML/HTML highlighting (tags, attributes, quoted values, comments)
N_GUI_SYNTAX_PLAIN
syntax view: no highlighting
N_GUI_SYNTAX_JSON
syntax view: JSON highlighting (keys, strings, numbers, punctuation)
N_GUI_SYNTAX_JS
syntax view: JavaScript highlighting (keywords, strings, numbers, comments)
N_GUI_SYNTAX_HTTP
syntax view: HTTP message highlighting (request/status line and headers)
N_GUI_SYNTAX_DIFF
syntax view: unified diff highlighting (added, removed and hunk header lines, as produced by n_diff_to_unified).
N_GUI_SUGGEST_VISIBLE
most completions a suggestion panel shows at once.
N_GUI_SUGGEST_SEP_MAX
longest separator set a suggestion-aware textarea takes, including the terminator
N_GUI_SUGGEST_MAX
most completions a textarea's suggestion list keeps for one prefix.
N_GUI_STATE_SCROLLBAR_DRAG
widget scrollbar is being dragged
N_GUI_STATE_IDLE
widget is idle / normal state
N_GUI_STATE_HOVER
mouse is hovering the widget
N_GUI_STATE_FOCUSED
widget has keyboard focus
N_GUI_STATE_ACTIVE
widget is being pressed / dragged
N_GUI_SPLIT_VERTICAL
split pane: vertical divider, regions are left and right
N_GUI_SPLIT_HORIZONTAL
split pane: horizontal divider, regions are top and bottom
N_GUI_SLIDER_VALUE
slider uses raw start/end values
N_GUI_SLIDER_V
vertical slider
N_GUI_SLIDER_PERCENT
slider uses 0-100 percentage
N_GUI_SLIDER_H
horizontal slider (default)
N_GUI_SHAPE_ROUNDED
rounded rectangle shape
N_GUI_SHAPE_RECT
rectangle shape (default)
N_GUI_SHAPE_BITMAP
bitmap-based rendering
N_GUI_SELECT_SINGLE
single item selection
N_GUI_SELECT_NONE
no selection allowed (display only)
N_GUI_SELECT_MULTIPLE
multiple item selection
N_GUI_SECTION_WIDGETS_MAX
maximum number of member widgets per section.
N_GUI_SECTIONLIST_MAX
maximum number of foldable sections in a section list
N_GUI_SCROLLBAR_V
vertical scrollbar
N_GUI_SCROLLBAR_H
horizontal scrollbar
N_GUI_RESIZE_VIRTUAL
fixed virtual canvas with uniform scaling (default/existing behavior)
N_GUI_RESIZE_ADAPTIVE
virtual size tracks display; windows adapt per their resize_policy
N_GUI_PERSIST_MAX_COLS
Maximum datagrid columns whose layout is persisted per widget.
N_GUI_MOUSE_WHEEL
custom widget mouse event: the wheel turned over it
N_GUI_MOUSE_UP
custom widget mouse event: the release of a button 1 press that began in it, wherever the pointer is now
N_GUI_MOUSE_MOVE
custom widget mouse event: the pointer moved over it with no button held
N_GUI_MOUSE_DRAG
custom widget mouse event: the pointer moved with button 1 held after a press in it; reported outside the widget too, as a slider's drag is
N_GUI_MOUSE_DOWN
custom widget mouse event: a press inside it, button 1 or 2
N_GUI_KV_MAX
maximum number of rows in a KV table
N_GUI_KEY_SOURCES_MAX
maximum number of source widgets for a focused key binding
N_GUI_KEY_MOD_MASK
mask of supported modifier flags for button keybind matching
N_GUI_IMAGE_STRETCH
stretch to fill bounds
N_GUI_IMAGE_FIT
scale to fit within bounds, keep aspect ratio
N_GUI_IMAGE_CENTER
draw at original size, centered
N_GUI_ID_MAX
maximum length for widget id/name strings
N_GUI_GLYPH_PLUS
plus sign
N_GUI_GLYPH_NONE
no glyph: the button draws its text label (default)
N_GUI_GLYPH_MINUS
minus sign
N_GUI_GLYPH_CROSS
diagonal cross
N_GUI_GLYPH_COUNT
number of defined glyphs, for range checks
N_GUI_GLYPH_COPY
two offset sheets: duplicate / copy
N_GUI_GLYPH_ARROW_UP
filled triangle pointing up
N_GUI_GLYPH_ARROW_RIGHT
filled triangle pointing right
N_GUI_GLYPH_ARROW_LEFT
filled triangle pointing left
N_GUI_GLYPH_ARROW_DOWN
filled triangle pointing down
N_GUI_GLOBAL_SCROLL_SLACK
how far, in pixels, the open windows may reach past the display before the global scrollbars appear: under half a pixel is a rounding error of a layout computed in floats, and hides nothing
N_GUI_DROP_INTO
N_GUI_DROP_BEFORE
drop position relative to a tree row (drag-and-drop)
N_GUI_DROP_AFTER
N_GUI_DROPMENU_EXPAND_UP
dropdown panel opens upward (above the button) instead of downward.
N_GUI_DETACH_SCALE_CONTENT
scale the window's widgets when the native window is resized by the user.
N_GUI_DETACH_RESIZABLE
the native window can be resized by the user through the OS window manager
N_GUI_DETACH_OWN_CHROME
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.
N_GUI_DETACH_NONE
no option
N_GUI_COMBOBOX_EXPAND_UP
dropdown panel opens upward (above the widget) instead of downward.
N_GUI_COMBOBOX_AUTO_WIDTH
dropdown panel expands to fit the longest item text
N_GUI_AUTOFIT_WH
auto-adjust both width and height (convenience: W
N_GUI_AUTOFIT_W
auto-adjust window width to content
N_GUI_AUTOFIT_H
auto-adjust window height to content
N_GUI_AUTOFIT_EXPAND_UP
expand upward instead of downward when adjusting height
N_GUI_AUTOFIT_EXPAND_LEFT
expand leftward instead of rightward when adjusting width
N_GUI_AUTOFIT_CENTER
center the window on its insertion point after auto-fit (overrides EXPAND_LEFT/EXPAND_UP for centering)
N_GUI_ALIGN_RIGHT
right aligned text
N_GUI_ALIGN_LEFT
left aligned text
N_GUI_ALIGN_JUSTIFIED
justified text (spread words to fill width)
N_GUI_ALIGN_CENTER
center aligned text

Detailed Description

Bitmap Skinning

All widgets support optional bitmap overlays for visual customization. By default, every bitmap pointer is NULL and the standard color theme is used. To skin a widget element, call the corresponding _set_bitmaps() function after widget creation.

Bitmaps are NOT owned by N_GUI, the caller is responsible for loading and destroying them. N_GUI only stores the pointer.

Fallback Chain

For widgets with per-state bitmaps (normal/hover/active):

  • If the state-specific bitmap is NULL, the normal bitmap is used.
  • If the normal bitmap is also NULL, the color theme is used.

Supported Widgets

JSON Theme

Bitmap assignments are programmatic (via setter functions), not part of the JSON theme file. The JSON theme remains the color/layout fallback.

Types Documentation

typedef n_gui_tree_on_drop_t

typedef int(* n_gui_tree_on_drop_t) (int src_node, int dst_node, int position, void *user_data);

drag-reorder drop callback.

Called when the user drags node src_node and releases the mouse over dst_node at position (N_GUI_DROP_BEFORE / INTO / AFTER). Return 1 to accept; the caller is responsible for mutating the underlying data model and rebuilding the tree. Return 0 to reject (widget clears its drag state silently).

typedef N_GUI_SUGGEST_FN

typedef void(* N_GUI_SUGGEST_FN) (const char *prefix, N_GUI_SUGGEST_SINK *sink, void *user_data);

asked for the completions of what has been typed so far

Parameters:

  • prefix what has been typed of the word under the cursor. Never NULL and never empty: an empty word closes the list without asking.
  • sink where the answers go, through n_gui_suggest_add()
  • user_data whatever was passed to n_gui_textarea_set_suggest()

Called while the pointer is not in the widget's own code: it runs from the key handler, once per change of the word under the cursor, and must not add, remove or retext any widget.

typedef N_GUI_CUSTOM_MOUSE

typedef int(* N_GUI_CUSTOM_MOUSE) (int widget_id, const N_GUI_MOUSE_EVENT *ev, void *user_data);

Mouse callback for a custom widget, set with n_gui_custom_set_mouse().

Parameters:

  • widget_id the custom widget
  • ev the event, valid during the call only
  • user_data the pointer passed to n_gui_custom_set_mouse

Return: non-zero when the widget used the event. For WHEEL, zero lets the window scroll instead; for DOWN, non-zero marks the event consumed. Ignored for the others.

typedef N_GUI_CUSTOM_DRAW

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).

Parameters:

  • widget the custom widget being drawn (read its w, h, theme, state)
  • x absolute screen x of the widget's top-left corner
  • y absolute screen y of the widget's top-left corner
  • font the effective font (the widget's own font, or the context default)
  • user_data the user pointer passed to n_gui_add_custom

Invoked during n_gui_draw with the widget's absolute top-left screen position. The callback renders anything it likes inside the rectangle [x, y, x + widget->w, y + widget->h] using Allegro drawing primitives.

Functions Documentation

function n_gui_window_update_normalized

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.

Recapture normalized coordinates for a window from its current absolute position/size.

Call after programmatically moving/resizing a window if you want the new position to be the adaptive reference point.

recapture normalized coordinates for a window from its current absolute position/size.

Call after programmatically moving/resizing a window if you want the new position to be the adaptive reference point.

function n_gui_window_set_zorder

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

Parameters:

  • ctx the GUI context
  • window_id the window to configure
  • z_mode one of N_GUI_ZORDER_NORMAL, N_GUI_ZORDER_ALWAYS_ON_TOP, N_GUI_ZORDER_ALWAYS_BEHIND, N_GUI_ZORDER_FIXED, N_GUI_ZORDER_POPUP
  • z_value z-value for N_GUI_ZORDER_FIXED mode (lower = behind, higher = on top), ignored for other modes

Set window z-order mode and value.

set window z-order mode and value

Re-sorts the window list after changing.

function n_gui_window_set_wheel_scrollbar

void n_gui_window_set_wheel_scrollbar(
    N_GUI_CTX * ctx,
    int window_id,
    int scrollbar_id
)

make the wheel anywhere over a window move one of its scrollbars, for a window that scrolls its own rows with a scrollbar widget rather than with N_GUI_WIN_AUTO_SCROLLBAR (a fixed set of rows refilled from an offset).

Parameters:

  • ctx the GUI context
  • window_id the window
  • scrollbar_id a scrollbar widget of that window, or -1 for none

Make the wheel anywhere over a window move one of its scrollbars.

Without it the wheel moves that scrollbar only with the pointer on it. A widget under the pointer that takes the wheel (a list, a slider) still takes it first; the scrollbar moves as if the wheel were turned over it, and its on_scroll callback is called. make the wheel anywhere over a window move one of its scrollbars, for a window that scrolls its own rows with a scrollbar widget rather than with N_GUI_WIN_AUTO_SCROLLBAR (a fixed set of rows refilled from an offset).

function n_gui_window_set_tb_close_theme

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

Set the theme for the titlebar close button on a specific window.

set the theme for the titlebar close button on a specific window

function n_gui_window_set_tb_button_bitmaps

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

Parameters:

  • ctx the GUI context
  • window_id the target window
  • btn_type N_GUI_TB_BTN_MINIMIZE, N_GUI_TB_BTN_MAXIMIZE, or N_GUI_TB_BTN_CLOSE
  • normal bitmap for normal state (NULL = color theme)
  • hover bitmap for hover state (NULL = fallback to normal)
  • active bitmap for active/pressed state (NULL = fallback to normal)

Set optional bitmap overlays on a titlebar button.

set optional bitmap overlays on a titlebar button

function n_gui_window_set_tb_btn_theme

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

Set the theme for titlebar minimize/maximize buttons on a specific window.

set the theme for titlebar minimize/maximize buttons on a specific window

function n_gui_window_set_resize_policy

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).

Set per-window resize policy (N_GUI_WIN_RESIZE_NONE / _MOVE / _SCALE).

Automatically captures normalized coordinates from the window's current position/size relative to the current display size.

set per-window resize policy (N_GUI_WIN_RESIZE_NONE / _MOVE / _SCALE).

Automatically captures normalized coordinates from the window's current position/size relative to the current display size.

function n_gui_window_set_rect_axes

void n_gui_window_set_rect_axes(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    int scale_x,
    int scale_y
)

n_gui_window_set_rect with per-axis reflow control.

Parameters:

  • ctx the GUI context
  • window_id the window to move/resize
  • x new window x
  • y new window y
  • w new window width (clamped to at least 1)
  • h new window height (clamped to at least 1)
  • scale_x non-zero to rescale the widgets horizontally
  • scale_y non-zero to rescale the widgets vertically

n_gui_window_set_rect with per-axis control over the widget reflow.

scale_y = 0 keeps the widgets' vertical layout, so a shorter window shows less of a page of fixed-height rows (and scrolls it, with N_GUI_WIN_AUTO_SCROLLBAR) instead of squeezing the rows; the width still tracks the window. The skipped axis's norms are refreshed from the kept pixel layout.

n_gui_window_set_rect with per-axis reflow control.

Stretching a window's widgets along both axes is right for a canvas or a body of text, and wrong for a stack of fixed-height rows: a settings page squeezed into a short pane ends up with 9-pixel rows instead of a scrollbar. Passing scale_y = 0 keeps the widgets' vertical layout, so a shorter window simply shows less of the page (and scrolls it, with N_GUI_WIN_AUTO_SCROLLBAR) while its width still tracks the window. That is the same rule n_gui_kvtable applies to its rows.

The skipped axis keeps its normalized coordinates as they were, so the widgets stay where the host put them rather than drifting.

function n_gui_window_set_rect

void n_gui_window_set_rect(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h
)

move and resize a window at runtime, rescaling its child widgets from their normalized coordinates (what a split-pane divider drag or a collapsing panel needs, since the adaptive pass only runs on a display resize).

Parameters:

  • ctx the GUI context
  • window_id the window to move/resize
  • x new window x
  • y new window y
  • w new window width (clamped to at least 1)
  • h new window height (clamped to at least 1)

Move and resize a window at runtime, reflowing its widgets.

The window's own norms are recaptured against the current display size. Widget groups that lay themselves out (kvtable, tab panel, section list) cannot see this call: follow it with their own _relayout.

move and resize a window at runtime, rescaling its child widgets from their normalized coordinates (what a split-pane divider drag or a collapsing panel needs, since the adaptive pass only runs on a display resize).

The adaptive pass only runs on a display resize, so a host that resizes a window itself (a split-pane divider drag, a collapsing panel) had no way to make the widgets inside follow. This applies the new rectangle and rescales every child widget from its normalized coordinates, which every widget captures relative to its window when it is added, whatever the window's resize policy.

The window's own normalized geometry is recaptured against the current display size, so a later n_gui_apply_adaptive_resize keeps the proportions the caller just set instead of snapping back to the creation layout. Widget norms are left alone: they already describe the widgets relative to the window and are what this call reads.

Helper-owned widget groups do their own math from the window size and cannot see this call: after resizing a window that hosts one, also call n_gui_kvtable_relayout() / n_gui_tab_relayout() / n_gui_sectionlist_relayout().

function n_gui_window_set_native_icons

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

Parameters:

  • ctx the GUI context
  • window_id a detached window
  • icons array of bitmaps, ideally several sizes so the platform can pick
  • num_icons number of entries in icons (1 is fine)

Return: 0 on success, -1 when the window does not exist or is not detached

Give a detached window's OS window a taskbar / title bar icon.

Only meaningful while the window is detached, a pop-up has no OS window to put an icon on. Like every other bitmap N_GUI is handed, the bitmaps are BORROWED: Allegro copies what it needs at call time, but keep them alive for as long as you may re-apply them and destroy them yourself.

give a detached window's OS window a taskbar / title bar icon

function n_gui_window_set_minimize_callback

void n_gui_window_set_minimize_callback(
    N_GUI_CTX * ctx,
    int window_id,
    void(*)(int, void *) on_minimize,
    void * user_data
)

set the minimize button callback for a window (NULL = default: toggle minimised)

Parameters:

  • ctx the GUI context
  • window_id the target window
  • on_minimize callback receiving (window_id, user_data)
  • user_data user data passed to the callback

Set the minimize button callback for a window.

set the minimize button callback for a window (NULL = default: toggle minimised)

function n_gui_window_set_maximize_callback

void n_gui_window_set_maximize_callback(
    N_GUI_CTX * ctx,
    int window_id,
    void(*)(int, void *) on_maximize,
    void * user_data
)

set the maximize button callback for a window (NULL = default: toggle maximised)

Parameters:

  • ctx the GUI context
  • window_id the target window
  • on_maximize callback receiving (window_id, user_data)
  • user_data user data passed to the callback

Set the maximize button callback for a window.

set the maximize button callback for a window (NULL = default: toggle maximised)

function n_gui_window_set_flags

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, ...)

Parameters:

  • ctx the GUI context
  • window_id id of the target window
  • flags bitmask of N_GUI_WIN_* flags to set

Set feature flags on a window.

set feature flags on a window (N_GUI_WIN_AUTO_SCROLLBAR, N_GUI_WIN_RESIZABLE, ...)

function n_gui_window_set_content_draw_callback

void n_gui_window_set_content_draw_callback(
    N_GUI_CTX * ctx,
    int window_id,
    void(*)(int, void *) on_content_draw,
    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)

Parameters:

  • ctx the GUI context
  • window_id the target window
  • on_content_draw callback receiving (window_id, user_data); NULL clears it
  • user_data user data passed to the callback

Set the content-draw callback for a window.

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)

The callback runs during n_gui_draw immediately after the window's own content is drawn, at the window's z-order, so any custom rendering it performs is occluded by windows that draw on top of this one.

function n_gui_window_set_close_callback

void n_gui_window_set_close_callback(
    N_GUI_CTX * ctx,
    int window_id,
    void(*)(int, void *) on_close,
    void * user_data
)

set the close button callback for a window (NULL = default: hide window)

Parameters:

  • ctx the GUI context
  • window_id the target window
  • on_close callback receiving (window_id, user_data). Must call n_gui_close_window() itself if desired.
  • user_data user data passed to the callback

Set the close button callback for a window.

set the close button callback for a window (NULL = default: hide window)

function n_gui_window_set_caption

void n_gui_window_set_caption(
    N_GUI_CTX * ctx,
    int window_id,
    const char * caption
)

show a caption in a window's title bar in place of its title, for a title that carries live state ("Export - 3 photographs").

Parameters:

  • ctx the GUI context
  • window_id the window
  • caption what to show, copied, cut to N_GUI_ID_MAX - 1 bytes

Show a caption in a window's title bar in place of its title.

The title stays the window's name in a saved layout, which matches windows by it, so a changing caption does not lose the window's saved place. A detached window's native title follows. NULL or "" shows the title again. show a caption in a window's title bar in place of its title, for a title that carries live state ("Export - 3 photographs").

The title is left alone: it is the window's name in a saved layout.

function n_gui_window_set_bitmaps

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.

Parameters:

  • ctx the GUI context
  • window_id id of the target window
  • bg body background bitmap (NULL = color fill)
  • titlebar titlebar background bitmap (NULL = color fill)
  • bg_scale_mode scale mode for bg: N_GUI_IMAGE_FIT, N_GUI_IMAGE_STRETCH, or N_GUI_IMAGE_CENTER

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the window's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the window's lifetime and destroy them after the GUI context is destroyed.

Set optional bitmap overlays on a window's body and titlebar.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a window's body and titlebar.

function n_gui_window_set_autofit

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

Parameters:

  • ctx the GUI context
  • window_id the window to configure
  • autofit_flags bitmask of N_GUI_AUTOFIT_W, N_GUI_AUTOFIT_H, N_GUI_AUTOFIT_EXPAND_LEFT, N_GUI_AUTOFIT_EXPAND_UP
  • border padding in pixels between content bounding box and window edge (on each side)

Configure auto-fit behavior for a dialog window.

configure auto-fit behavior for a dialog window

Store the flags and border value in the window struct.

function n_gui_window_native_is_hidden

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.

Return: 1 when the window is detached and not currently drawable, else 0

Check whether a detached window is currently not drawable.

A halted window is skipped by n_gui_draw_detached. check whether a detached window's drawing is currently halted by the OS (Android surface loss) or the window manager has iconified it.

function n_gui_window_is_open

int n_gui_window_is_open(
    N_GUI_CTX * ctx,
    int window_id
)

check if window is visible

Return: 1 if open, 0 if closed

Check if a window is currently visible.

check if window is visible

function n_gui_window_is_minimised

int n_gui_window_is_minimised(
    N_GUI_CTX * ctx,
    int window_id
)

check if a window is currently minimised

Parameters:

  • ctx the gui context
  • window_id the id of the window to query

Return: 1 if the window is minimised, 0 otherwise (or on a bad id)

Check if a window is currently minimised.

check if a window is currently minimised

function n_gui_window_is_maximised

int n_gui_window_is_maximised(
    N_GUI_CTX * ctx,
    int window_id
)

check if a window is currently maximised

Return: 1 if maximised, 0 if not (or invalid id)

Check if a window is currently maximised.

check if a window is currently maximised

function n_gui_window_is_detached

int n_gui_window_is_detached(
    N_GUI_CTX * ctx,
    int window_id
)

check whether a window currently lives in a native OS window

Check whether a window currently lives in a native OS window.

check whether a window currently lives in a native OS window

function n_gui_window_get_zvalue

int n_gui_window_get_zvalue(
    N_GUI_CTX * ctx,
    int window_id
)

get window z-value (for N_GUI_ZORDER_FIXED mode)

Get window z-value (for N_GUI_ZORDER_FIXED mode).

get window z-value (for N_GUI_ZORDER_FIXED mode)

function n_gui_window_get_zorder

int n_gui_window_get_zorder(
    N_GUI_CTX * ctx,
    int window_id
)

get window z-order mode

Get window z-order mode.

get window z-order mode

function n_gui_window_get_resize_policy

int n_gui_window_get_resize_policy(
    N_GUI_CTX * ctx,
    int window_id
)

get per-window resize policy

Return: N_GUI_WIN_RESIZE_NONE, _MOVE, or _SCALE

Get per-window resize policy.

get per-window resize policy

function n_gui_window_get_flags

int n_gui_window_get_flags(
    N_GUI_CTX * ctx,
    int window_id
)

get feature flags of a window

Return: the flags, or 0

Get feature flags of a window.

get feature flags of a window

function n_gui_window_get_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

Get the native display backing a window, or NULL when it is a pop-up.

get the native display backing a window, or NULL when it is a pop-up

function n_gui_window_from_display

int n_gui_window_from_display(
    N_GUI_CTX * ctx,
    ALLEGRO_DISPLAY * display
)

find the window detached into a given display

Return: the window id, or -1 when no detached window owns display

Find the window detached into a given display.

find the window detached into a given display

function n_gui_window_find_button

int n_gui_window_find_button(
    N_GUI_CTX * ctx,
    int window_id,
    const char * label
)

Find the button in a window whose label is exactly this.

Parameters:

  • ctx the GUI context
  • window_id the window to look in
  • label the label to match, case sensitive

Return: The widget id, or -1 when the window has no such button.

For the case where a window's widgets were built by a helper that did not hand every id back, and for a test that has to press "the Close button" of every window without knowing any of them by number.

function n_gui_window_detach

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

Parameters:

  • ctx the GUI context. An event queue must have been set.
  • window_id the window to detach
  • detach_flags bitmask of N_GUI_DETACH_* options

Return: 0 on success (or if the window was already detached), -1 on error

Promote a pop-up window to a native OS window.

Creates an ALLEGRO_DISPLAY sized to the window's body, registers its event source in the context's event queue, and moves the window to (0,0) inside it. The window is forced frameless: the OS supplies the title bar, so dragging, resizing, minimising and maximising are handled by the window manager and the window's own title bar buttons are no longer drawn. The window's title becomes the OS window title.

The host must call n_gui_draw_detached() once per frame to render and flip the native windows, and keep feeding every event to n_gui_process_event(), which routes each one to the display it came from.

promote a pop-up window to a native OS window

function n_gui_window_button_rect

int n_gui_window_button_rect(
    N_GUI_CTX * ctx,
    int window_id,
    int btn_type,
    float * x,
    float * y,
    float * w,
    float * h
)

Where one of a window's title bar buttons is, on screen.

Parameters:

  • ctx the GUI context
  • window_id the window
  • btn_type N_GUI_TB_BTN_MINIMIZE, _MAXIMIZE or _CLOSE
  • x receives the left edge, may be NULL
  • y receives the top edge, may be NULL
  • w receives the width, may be NULL
  • h receives the height, may be NULL

Return: 1 when that window has that button, 0 otherwise, in which case nothing is written.

The close cross and its neighbours are drawn by the toolkit from the window's flags and the style, so nothing outside can work out where they are. A test that has to press one, or an application that wants to put something beside them, asks here.

function n_gui_window_autosize

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

Recompute and apply minimum-fit size for a window based on its current widgets.

recompute and apply minimum-fit size for a window based on its current widgets

Adds padding around the furthest widget extents.

function n_gui_window_attach

int n_gui_window_attach(
    N_GUI_CTX * ctx,
    int window_id
)

return a detached window to being an in-display pop-up

Parameters:

  • ctx the GUI context
  • window_id the window to re-attach

Return: 0 on success (or if the window was not detached), -1 on error

Return a detached window to being an in-display pop-up.

return a detached window to being an in-display pop-up

function n_gui_window_apply_autofit

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)

Parameters:

  • ctx the GUI context
  • window_id the window to recalculate

Trigger auto-fit recalculation for a window.

trigger auto-fit recalculation for a window (call after adding/removing/resizing widgets)

Computes content bounding box from visible widgets and adjusts window dimensions based on autofit_flags and autofit_border.

function n_gui_widget_set_rect

void n_gui_widget_set_rect(
    N_GUI_CTX * ctx,
    int widget_id,
    float x,
    float y,
    float w,
    float h
)

move/resize a widget after creation, refreshing the normalized coordinates the resize passes read.

Parameters:

  • ctx the GUI context
  • widget_id the widget to place
  • x new x, relative to the window's content area
  • y new y, relative to the window's content area
  • w new width (negative is clamped to 0)
  • h new height (negative is clamped to 0)

Move and resize a widget after creation.

For hosts that compute their own layout; the owning window is found open or closed, so hidden tab pages can be laid out too

move/resize a widget after creation, refreshing the normalized coordinates the resize passes read.

Widgets are placed by the n_gui_add_* call that creates them, which is all a static dialog needs. A host that computes its own layout (a resizable panel, the two sides of a split pane) has to place them again on every relayout, and reaching into N_GUI_WIDGET from application code would skip the normalized coordinates the resize passes read.

The rectangle is applied and the widget's norms are recaptured against its window, so n_gui_apply_adaptive_resize and n_gui_window_set_rect keep scaling it correctly from its new position. The owning window is found whether it is open or closed, so the pages of a tab panel can be laid out while hidden.

function n_gui_widget_set_persist_key

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.

The key is unique within its window (matching is by owning-window title + key). Passing NULL/"" clears the key (stops persisting). If a saved layout was already loaded, the matching pending state is applied to the widget immediately (consume-once). No-op for a widget type that carries no persistable state.

function n_gui_widget_screen_rect

int n_gui_widget_screen_rect(
    N_GUI_CTX * ctx,
    int widget_id,
    float * x,
    float * y,
    float * w,
    float * h
)

Where a widget is on screen, rather than inside its window.

Parameters:

  • ctx the GUI context
  • widget_id the widget
  • x receives the left edge, may be NULL
  • y receives the top edge, may be NULL
  • w receives the width, may be NULL
  • h receives the height, may be NULL

Return: 1 when the widget was found, 0 otherwise, in which case nothing is written.

A widget's own x and y are relative to the window it lives in, and a mouse event's are not, so the two cannot be compared without adding the window's origin, its title bar and its scroll offset. An application that has to decide what a press at a given point is for - or a test that has to aim one - asks here instead of repeating that arithmetic and getting the scrolled or the framed case wrong.

A widget in a detached window answers in that window's own coordinates, which is the space its events arrive in.

function n_gui_widget_is_visible

int n_gui_widget_is_visible(
    N_GUI_CTX * ctx,
    int widget_id
)

Is a widget currently shown.

Parameters:

  • ctx the GUI context
  • widget_id the widget

Return: 1 when it is shown, 0 when it is hidden or unknown.

The other half of n_gui_set_widget_visible(), which had none: an application that shows a control in one state and hides it in another had to keep its own copy of what it had just said, and a second copy of a fact the toolkit already holds is a second place for it to be wrong.

function n_gui_widget_get_persist_key

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.

function n_gui_was_double_click

int n_gui_was_double_click(
    const N_GUI_CTX * ctx,
    int widget_id
)

whether the press just processed double clicked this particular widget

Parameters:

  • ctx GUI context
  • widget_id the widget to ask about

Return: 1 when it did, 0 otherwise

whether the press just processed double clicked this widget

whether the press just processed double clicked this particular widget

function n_gui_wants_mouse

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)

Parameters:

  • ctx the GUI context

Return: 1 if the mouse is over a GUI window, 0 otherwise

Check if the mouse is currently over any open GUI window.

check if the mouse is currently over any open GUI window (use to prevent click-through to the game world)

Use this to prevent mouse clicks from passing through the GUI to the game.

function n_gui_update_transform

void n_gui_update_transform(
    N_GUI_CTX * ctx
)

recalculate scale and offset from virtual canvas to display.

Recalculate scale and offset from virtual canvas to physical display.

Called automatically by n_gui_set_display_size when virtual canvas is set. You should not normally need to call this directly.

recalculate scale and offset from virtual canvas to display.

Uses uniform (aspect-preserving) scaling with centred letterboxing, identical to the approach used by BlockBlaster's update_view_offset(). Called automatically by n_gui_set_display_size() when virtual canvas is set.

function n_gui_tree_toggle_expand

void n_gui_tree_toggle_expand(
    N_GUI_TREE * tree,
    int node_index
)

toggle expand/collapse of a node.

Opening a node the expand callback has not filled yet calls it first.

function n_gui_tree_tick

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.

Call once per frame while the tree is visible, before n_gui_draw(). No-op when on_drop is NULL.

function n_gui_tree_state_save

int n_gui_tree_state_save(
    const N_GUI_TREE * tree,
    N_GUI_TREE_STATE * out
)

capture which nodes are expanded, which one is selected, and where the view is scrolled, all by path.

Call before a rebuild that replaces the nodes (a reloaded model), then n_gui_tree_state_apply after it, so the user does not lose their unfolded branches and their place. Returns 0 on success

function n_gui_tree_state_free

void n_gui_tree_state_free(
    N_GUI_TREE_STATE * state
)

release the strings owned by a saved state (safe on a zeroed struct)

function n_gui_tree_state_apply

void n_gui_tree_state_apply(
    N_GUI_TREE * tree,
    const N_GUI_TREE_STATE * state
)

re-expand, re-select and re-scroll a rebuilt tree from a saved state.

Nodes that no longer exist are skipped; nodes that appeared stay collapsed. On a tree filled on demand, an expanded node is filled through the expand callback as it is reopened, level by level, so a whole unfolded branch comes back, read afresh

function n_gui_tree_set_selection

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.

Does not fire the on_select callback. No-op if node_index is out of range.

function n_gui_tree_set_on_drop

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.

Drag state is only tracked when on_drop is non-NULL.

function n_gui_tree_set_label

void n_gui_tree_set_label(
    N_GUI_TREE * tree,
    int node_index,
    const char * new_label
)

change the display label of a node

function n_gui_tree_set_expandable

void n_gui_tree_set_expandable(
    N_GUI_TREE * tree,
    int node_index,
    int expandable
)

mark a node as openable before it has children, so it shows an expander and the expand callback fills it when it is opened

function n_gui_tree_set_expand_callback

void n_gui_tree_set_expand_callback(
    N_GUI_TREE * tree,
    void(*)(int node_index, void *user_data) on_expand,
    void * user_data
)

set the callback that fills a node the first time it is opened, for a tree too large to build before it is shown: a folder tree reads a directory only when somebody opens it.

Called with the node's index, before the rebuild, so the children it adds with n_gui_tree_add_node() show in the same frame. A node the callback leaves empty loses its expander. NULL removes it.

function n_gui_tree_remove_node

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)

function n_gui_tree_rebuild

void n_gui_tree_rebuild(
    N_GUI_TREE * tree
)

rebuild the listbox to reflect current tree state

function n_gui_tree_node_path

int n_gui_tree_node_path(
    const N_GUI_TREE * tree,
    int node_index,
    char * buf,
    size_t bufsz
)

write the path of a node (its label and its ancestors', joined by N_GUI_TREE_PATH_SEP) into buf.

Parameters:

  • tree the tree
  • node_index the node to describe
  • buf destination buffer
  • bufsz size of buf

Return: 0 on success, -1 on an invalid node or a path that does not fit

Write the path of a node into a buffer.

Returns 0 on success, -1 on a bad node or a path that does not fit

write the path of a node (its label and its ancestors', joined by N_GUI_TREE_PATH_SEP) into buf.

The path is the node's label preceded by its ancestors', joined by N_GUI_TREE_PATH_SEP (a unit separator, which cannot occur inside a label, so the path is unambiguous). It identifies a node across a rebuild, which node indices and user_data pointers do not when the model behind the tree was reloaded from disk.

function n_gui_tree_get_selection

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

function n_gui_tree_free

void n_gui_tree_free(
    N_GUI_TREE ** tree
)

free a tree view (does not destroy the N_GUI listbox)

function n_gui_tree_find_by_user_data

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.

Used to re-resolve a node index after a rebuild compacted the array: the caller stashes the stable user_data pointer before the rebuild, then calls this to find the new index.

function n_gui_tree_find_by_path

int n_gui_tree_find_by_path(
    const N_GUI_TREE * tree,
    const char * path
)

index of the first node with the given path, or -1.

Paths survive a rebuild that replaces every node, which pointers and indices do not

function n_gui_tree_expand

void n_gui_tree_expand(
    N_GUI_TREE * tree,
    int node_index
)

open a node, filling it first through the expand callback if it has not been; a node already open stays open.

For a caller revealing a path one level at a time. No-op for a node that cannot be opened.

function n_gui_tree_draw_overlay

void n_gui_tree_draw_overlay(
    N_GUI_TREE * tree
)

per-frame overlay drawing: draws the active drop-indicator on top of the listbox.

Call after n_gui_draw(). No-op when no drag is in progress.

function n_gui_tree_create

N_GUI_TREE * n_gui_tree_create(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    void(*)(int, void *) on_select,
    void * user_data
)

create a tree view in an existing window

function n_gui_tree_clear

void n_gui_tree_clear(
    N_GUI_TREE * tree
)

remove all nodes and clear the backing listbox; tree object remains valid

function n_gui_tree_add_node

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

function n_gui_tooltip_pending

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)

Parameters:

  • ctx the GUI context

Return: 0 = none/disabled/obscured, 1 = arming, 2 = shown

Report the tooltip phase.

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)

Hosts that cache the GUI render must keep invalidating/redrawing while this returns 1 (arming), or the bubble can never appear - it shows only after the pointer STOPS, when no more input events trigger redraws. A steady 2 (shown) needs one re-render on the transition and none after; re-rendering every tick during 2 would burn the cache for nothing.

Answers 0 while another window covers the pointer, even though a widget is armed underneath it: the bubble is drawn last and over everything, so one armed before a window opened on top of it would be painted over that window. The arming scan already picks the top-most window's widget, but nothing re-runs it when a window opens without the pointer moving – a context menu on a right click is the case this was found in.

function n_gui_toggle_window

void n_gui_toggle_window(
    N_GUI_CTX * ctx,
    int window_id
)

toggle window visibility (show/hide)

Toggle window visibility (show if hidden, hide if shown).

toggle window visibility (show/hide)

function n_gui_textarea_suggest_is_open

int n_gui_textarea_suggest_is_open(
    N_GUI_CTX * ctx,
    int widget_id
)

is a textarea's completion panel up

Parameters:

  • ctx the GUI context
  • widget_id id of the textarea widget

Return: 1 when the panel is open

function n_gui_textarea_suggest_close

void n_gui_textarea_suggest_close(
    N_GUI_CTX * ctx,
    int widget_id
)

put a textarea's completion panel away

Parameters:

  • ctx the GUI context
  • widget_id id of the textarea widget

What ESCAPE does, for a caller that needs to dismiss it for its own reasons: a window closing over it, or a key the application wants back.

function n_gui_textarea_set_text

void n_gui_textarea_set_text(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text
)

set text area content

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget
  • text the text to set, or NULL to clear

set the text content of a textarea widget

set text area content

function n_gui_textarea_set_suggest

void n_gui_textarea_set_suggest(
    N_GUI_CTX * ctx,
    int widget_id,
    N_GUI_SUGGEST_FN fn,
    const char * separators,
    void * user_data
)

offer completions in a textarea

Parameters:

  • ctx the GUI context
  • widget_id id of the textarea widget
  • fn the provider, or NULL to stop offering completions
  • separators characters that end a word, e.g. "," for a comma separated list. NULL or "" makes the whole content one word.
  • user_data handed back to the provider untouched, not owned

While the field has focus, the word under the cursor is handed to fn and what it answers is shown in a panel under the field. Up and Down move through it, ENTER or TAB puts the highlighted one in place of that word, ESCAPE dismisses it, and a click picks one. Typing keeps it in step; a word that nothing matches closes it.

The provider is asked when the word under the cursor changes, and not when a key leaves it as it was: the panel remembers which word its answers are for, so arrow keys and edits elsewhere in the line cost nothing.

What is replaced is exactly the word under the cursor, and nothing is added after it. A field holding a list gets its separator typed by the person using it, because a widget that helpfully appends one is a widget that has to guess whether they wanted another entry.

function n_gui_textarea_set_selection

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)

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget
  • start selection start byte offset
  • end selection end byte offset

function n_gui_textarea_set_placeholder

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.

Parameters:

  • ctx the GUI context
  • widget_id id of the textarea widget
  • text the placeholder text, or NULL to clear

Set placeholder/hint text shown dimmed while a textarea is empty.

Pass NULL or "" to remove the placeholder. The string is copied. set placeholder/hint text for a textarea, shown dimmed while the field is empty and cleared from view as soon as the user types.

function n_gui_textarea_set_mask_char

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.

Parameters:

  • ctx the GUI context
  • widget_id id of the textarea widget
  • mask The character to display instead of actual text (e.g. '*'). Set to '\0' to disable masking.

Set a mask character for password-style input.

'*'). Set to '\0' to disable masking. Only affects single-line textareas. set a mask character for password-style input (e.g.

function n_gui_textarea_set_bitmap

void n_gui_textarea_set_bitmap(
    N_GUI_CTX * ctx,
    int widget_id,
    ALLEGRO_BITMAP * bg
)

set optional background bitmap on a textarea widget.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional background bitmap on a textarea widget.

set optional background bitmap on a textarea widget.

function n_gui_textarea_scroll_to_offset

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

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget
  • byte_offset byte offset in text to center on screen

function n_gui_textarea_scroll_to_bottom

void n_gui_textarea_scroll_to_bottom(
    N_GUI_CTX * ctx,
    int widget_id
)

scroll a multiline textarea to the bottom

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget

function n_gui_textarea_has_selection

int n_gui_textarea_has_selection(
    N_GUI_CTX * ctx,
    int widget_id
)

is any text selected in a text area (0 for no selection or a bad id)

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget

Return: 1 when a non empty range is selected, 0 when none is or the id is not a text area

is any text selected in a text area

is any text selected in a text area (0 for no selection or a bad id)

What Ctrl+C would copy and Ctrl+X would cut: an application that binds those keys to an action of its own can leave them to the field while it has something selected, and take them otherwise, when the field's copy would put nothing on the clipboard.

function n_gui_textarea_get_text_length

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)

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget

Return: text length in bytes, or 0 if widget is invalid

return the current text length in bytes

return the current text length in bytes (0 if widget is invalid)

function n_gui_textarea_get_text

const char * n_gui_textarea_get_text(
    N_GUI_CTX * ctx,
    int widget_id
)

get text area content

Parameters:

  • ctx GUI context
  • widget_id id of the textarea widget

Return: pointer to the text content

get the text content of a textarea widget

get text area content

function n_gui_text_shorten

int n_gui_text_shorten(
    ALLEGRO_FONT * font,
    const char * text,
    float max_w,
    int mode,
    char * out,
    size_t out_len
)

shorten text to fit max_w pixels in font, the way a label with truncate mode mode shows it: unchanged when it fits, otherwise with "..." at the end, at the start, or in place of whole leading path components (N_GUI_TRUNCATE_END, _START, _PATH).

Cuts only between UTF-8 sequences. Returns 1 when out is shorter than text, 0 when it is the whole of it, -1 on a NULL argument or no room. out is always terminated when out_len > 0.

function n_gui_tab_set_content_window

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

function n_gui_tab_set_active

void n_gui_tab_set_active(
    N_GUI_TAB_PANEL * panel,
    int index
)

set the active tab (toggles buttons, opens/closes content windows)

function n_gui_tab_relayout

void n_gui_tab_relayout(
    N_GUI_TAB_PANEL * panel,
    float x,
    float y,
    float button_w,
    float button_h
)

move/resize the button row after creation (a host-owned or resizable layout); pass <= 0 for button_w / button_h to keep the current value.

Parameters:

  • panel the tab panel
  • x new x of the first tab button, in the parent window's coordinates
  • y new y of the button row
  • button_w new per-button width (<= 0 keeps the current one)
  • button_h new button height (<= 0 keeps the current one)

Move/resize a tab panel's button row after creation.

Content windows are separate windows, place them with n_gui_window_set_rect

move/resize the button row after creation (a host-owned or resizable layout); pass <= 0 for button_w / button_h to keep the current value.

The buttons are laid out once, when each tab is added. A host that owns its own layout (a resizable panel, a split-pane pane) needs to re-place the row afterwards; this re-applies the origin and button size to every tab and refreshes their normalized coordinates so they keep following their window. The content windows are not touched: they are ordinary windows, position them with n_gui_window_set_rect().

function n_gui_tab_get_active

int n_gui_tab_get_active(
    const N_GUI_TAB_PANEL * panel
)

get the active tab index

function n_gui_tab_free

void n_gui_tab_free(
    N_GUI_TAB_PANEL ** panel
)

free a tab panel (does not destroy the N_GUI widgets)

function n_gui_tab_create

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(*)(int, void *) on_tab_change,
    void * user_data
)

create a tab panel in an existing window

function n_gui_tab_add

int n_gui_tab_add(
    N_GUI_TAB_PANEL * panel,
    const char * label
)

add a tab to the panel, returns tab index

function n_gui_syntaxview_set_text

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

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget
  • text the text to display, or NULL to clear

set (copy) the text shown by a syntax view

set (copy) the text shown by a syntax view; text may be NULL to clear

function n_gui_syntaxview_set_selection

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

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget
  • start selection start byte offset (clamped to the text length)
  • end selection end byte offset (clamped to the text length); start == end clears

set the selection range of a syntax view (byte offsets into the text)

set the selection range (byte offsets into the text, clamped to its length); pass start == end to clear the selection

function n_gui_syntaxview_set_mode

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

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget
  • mode one of the N_GUI_SYNTAX_* modes (PLAIN, HTTP, JSON, XML, YAML, JS, DIFF)

set the highlighting mode of a syntax view

set the highlighting mode (N_GUI_SYNTAX_*) of a syntax view

function n_gui_syntaxview_set_h_scroll

void n_gui_syntaxview_set_h_scroll(
    N_GUI_CTX * ctx,
    int widget_id,
    float px
)

set the horizontal scroll offset of a syntax view, in pixels (clamped to the content width by the draw path)

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget
  • px the offset in pixels (negative values are clamped to 0, the upper bound is applied by the draw path against the live content width)

set the horizontal scroll offset of a syntax view

set the horizontal scroll offset of a syntax view, in pixels (clamped to the content width by the draw path)

function n_gui_syntaxview_select_all

void n_gui_syntaxview_select_all(
    N_GUI_CTX * ctx,
    int widget_id
)

select the entire text of a syntax view

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget

function n_gui_syntaxview_scroll_to_offset

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, and horizontally so the offset itself is inside the visible width

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget
  • byte_offset byte offset into the text (clamped to the text length)

scroll a syntax view so the line holding a byte offset is vertically centered, and horizontally so the offset itself is inside the visible width

scroll a syntax view so the line holding the given byte offset is vertically centered, and horizontally so the offset itself is inside the visible width

function n_gui_syntaxview_get_text

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)

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget

Return: a borrowed pointer to the text (do not free), or NULL when empty/invalid

get the text currently shown by a syntax view

get the text shown by a syntax view (borrowed pointer, do not free; NULL if empty)

function n_gui_syntaxview_get_selected_text

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.

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget

Return: a newly allocated copy of the selected substring (caller frees with Free()), or NULL when nothing is selected or the widget is invalid

get a copy of the currently selected text in a syntax view

The caller owns the returned buffer and must Free() it.

copy of the currently selected text in a syntax view, or NULL when nothing is selected.

function n_gui_syntaxview_get_line_count

int n_gui_syntaxview_get_line_count(
    N_GUI_CTX * ctx,
    int widget_id
)

get the number of text lines in a syntax view

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget

Return: the line count, or 0 if the widget is invalid

function n_gui_syntaxview_get_h_scroll

float n_gui_syntaxview_get_h_scroll(
    N_GUI_CTX * ctx,
    int widget_id
)

current horizontal scroll offset of a syntax view, in pixels.

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget

Return: the offset in pixels, or 0 if the widget is invalid

get the horizontal scroll offset of a syntax view

Pair with n_gui_syntaxview_set_h_scroll to preserve the horizontal view across a set_text.

current horizontal scroll offset of a syntax view, in pixels.

function n_gui_syntaxview_content_width

float n_gui_syntaxview_content_width(
    N_GUI_CTX * ctx,
    int widget_id
)

pixel width the widest line of a syntax view needs, padding included

Parameters:

  • ctx GUI context
  • widget_id id of the syntax view widget

Return: the content width in pixels, or 0 if the widget is invalid or empty

function n_gui_suggest_add

int n_gui_suggest_add(
    N_GUI_SUGGEST_SINK * sink,
    const char * text
)

add one completion to a suggestion sink

Parameters:

  • sink the sink handed to the provider
  • text the completion to offer

Return: 1 when it was taken, 0 when it was refused

Called from a N_GUI_SUGGEST_FN and nowhere else. The text is copied, so the provider's own buffer can be reused or go out of scope immediately. An empty text, a duplicate of one already added, and anything past N_GUI_SUGGEST_MAX are all refused rather than stored.

function n_gui_splitpane_set_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)

Parameters:

  • ctx GUI context
  • widget_id id of the split pane widget
  • ratio the requested divider ratio (0..1)

set the divider ratio of a split pane (clamped to its min/max)

set the divider ratio (clamped to the configured min/max)

function n_gui_splitpane_set_limits

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

Parameters:

  • ctx GUI context
  • widget_id id of the split pane widget
  • min_ratio lower clamp (0..1)
  • max_ratio upper clamp (0..1)

set the minimum and maximum allowed divider ratio of a split pane

set the minimum and maximum allowed divider ratio

function n_gui_splitpane_get_ratio

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

Parameters:

  • ctx GUI context
  • widget_id id of the split pane widget

Return: the divider ratio (0..1), or 0.5 if the widget is invalid

get the current divider ratio of a split pane

get the current divider ratio (0..1), or 0.5 if the widget is invalid

function n_gui_splitpane_band

float n_gui_splitpane_band(
    N_GUI_CTX * ctx,
    int widget_id
)

How far either side of a split pane's divider a press still counts as the divider's.

Parameters:

  • ctx the GUI context
  • widget_id the split pane

Return: The band in pixels, measured from the divider's centre, or 0 when the widget is not a split pane.

Wider than the bar that is drawn, so the divider can be grabbed without taking aim. An application that puts its own controls next to a divider has to know how much room the divider is really taking, or those controls can be seen and not touched: a scrollbar along a column's edge was unreachable for exactly that reason, because the application had assumed the band was the width of the bar.

function n_gui_splitpane_at

int n_gui_splitpane_at(
    N_GUI_CTX * ctx,
    float x,
    float y
)

report the split pane whose divider band is under a point, or -1.

Parameters:

  • ctx the GUI context
  • x screen x
  • y screen y

Return: the split pane's widget id, or -1 when the point is not on a divider band

For an application that looks at raw mouse events before handing them to n_gui_process_event(): a split pane is click-through everywhere except its divider band, so an application that claims a press by rectangle alone swallows the drag the divider was about to start. The pointer turns into a resize cursor and nothing moves, which is how the problem shows up.

Windows are walked back to front and widgets bottom to top, so the topmost claimant wins, and any other widget over the point clears the answer.

function n_gui_slider_value_width

float n_gui_slider_value_width(
    N_GUI_CTX * ctx,
    int widget_id
)

width in pixels a slider's built-in readout needs beside it, the gap between track and text included.

Parameters:

  • ctx the GUI context
  • widget_id the slider

Return: the width, or 0 for a slider with no readout, a vertical one being irrelevant here, or a bad id

A horizontal slider draws its value past its own right edge, so a caller that sizes the track to the room available leaves none for the number and the window clips it. Subtract this from the width before setting the track's rectangle.

Measured at both ends of the slider's range and the wider taken, not at the current value: a layout sized from the value on show would change every time the handle moved.

function n_gui_slider_set_value_visible

void n_gui_slider_set_value_visible(
    N_GUI_CTX * ctx,
    int widget_id,
    int visible
)

Toggle the built-in value label.

Default 1 (visible). Set to 0 when the caller is already painting the value elsewhere so the slider doesn't double-render it.

function n_gui_slider_set_value_format

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.

Pass NULL or "" to restore the default ("%.1f" in VALUE mode, "%.0f%%" in PERCENT mode). Format must consume the slider's double value (use f/g/e or cast with a precision width, a single d works too via stringification fallbacks). Buffer cap is 32 bytes.

function n_gui_slider_set_value

void n_gui_slider_set_value(
    N_GUI_CTX * ctx,
    int widget_id,
    double value
)

set slider value

Parameters:

  • ctx GUI context
  • widget_id id of the slider widget
  • value new value to set

set the value of a slider widget

set slider value

function n_gui_slider_set_step

void n_gui_slider_set_step(
    N_GUI_CTX * ctx,
    int widget_id,
    double step
)

set slider step increment (0 is treated as 1).

Parameters:

  • ctx GUI context
  • widget_id id of the slider widget
  • step step increment (0 = continuous)

set slider step increment.

Value is re-snapped.

set slider step increment (0 is treated as 1).

0 means continuous (no snapping). When step > 0, the current value is immediately snapped.

function n_gui_slider_set_range

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

Parameters:

  • ctx GUI context
  • widget_id id of the slider widget
  • min_val new minimum value
  • max_val new maximum value

function n_gui_slider_set_key_step

void n_gui_slider_set_key_step(
    N_GUI_CTX * ctx,
    int widget_id,
    double step
)

set how far one arrow key press or wheel notch moves a slider, without snapping its drag

Parameters:

  • ctx GUI context
  • widget_id id of the slider widget
  • step increment (0 falls back to the snapping step, then to a twentieth of the range)

set how far one arrow key press or wheel notch moves a slider

set how far one arrow key press or wheel notch moves a slider, without snapping its drag

Separate from n_gui_slider_set_step() because the two answer different questions. step decides which values are legal and snaps every input to them, the drag included; this decides only how far a key or a notch moves, and leaves a drag continuous. A program wanting "an arrow press moves exposure by a third of a stop" while a drag stays smooth needs this one.

The value is not snapped and the current value is not changed.

function n_gui_slider_set_default

void n_gui_slider_set_default(
    N_GUI_CTX * ctx,
    int widget_id,
    double value
)

Give a slider a default value, which a double click on it puts back.

Parameters:

  • ctx the GUI context
  • widget_id the slider
  • value the default, inside the slider's range
  • ctx GUI context
  • widget_id id of the slider widget
  • value the default

give a slider the value a double click on it puts back

The double click sets the value (snapped and clamped as any other), calls the slider's on_change callback with it, as a drag would, and ends the drag the second press started, so the handle stays at the default when the pointer moves before the button is released. The first press of the pair has already moved the handle to the pointer and called on_change once; a host that merges consecutive changes of one control into one undo step gets the whole gesture as one.

A slider with no default ignores the gesture, as every slider did before this existed; n_gui_double_clicked_widget() still reports it either way.

Give a slider a default value, which a double click on it puts back.

function n_gui_slider_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a slider widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a slider widget.

function n_gui_slider_handle_pos

int n_gui_slider_handle_pos(
    N_GUI_CTX * ctx,
    int widget_id,
    float * pos,
    float * radius
)

Where a slider's handle is drawn and how big it is.

Return: 1 when the widget is a slider, 0 otherwise, in which case nothing is written.

pos receives the centre of the handle measured along the slider's own axis from its left edge, or from its top edge for a vertical one, and radius receives half the handle's width. Both may be NULL.

The handle's centre travels along a strip inset by the radius at each end, so that the circle is drawn whole at every value rather than being cut in half by the widget's edge at the extremes. A caller that wants to put something beside the handle, or to check where it landed, asks here rather than repeating that arithmetic.

function n_gui_slider_get_value

double n_gui_slider_get_value(
    N_GUI_CTX * ctx,
    int widget_id
)

get slider current value

Parameters:

  • ctx GUI context
  • widget_id id of the slider widget

Return: current slider value

get the current value of a slider widget

get slider current value

function n_gui_slider_get_key_step

double n_gui_slider_get_key_step(
    N_GUI_CTX * ctx,
    int widget_id
)

get the arrow key and wheel increment actually in use for a slider

Parameters:

  • ctx GUI context
  • widget_id id of the slider widget

Return: the increment, or 0.0 when the widget is not a slider

get the arrow key and wheel increment a slider actually uses

get the arrow key and wheel increment actually in use for a slider

function n_gui_slider_get_default

int n_gui_slider_get_default(
    N_GUI_CTX * ctx,
    int widget_id,
    double * value
)

A slider's default, as n_gui_slider_set_default() gave it.

Parameters:

  • ctx the GUI context
  • widget_id the slider
  • value receives the default when there is one; may be NULL
  • ctx GUI context
  • widget_id id of the slider widget
  • value receives the default, may be NULL

Return:

  • 1 when the slider has a default, 0 otherwise
  • 1 when the slider has one, 0 otherwise

read a slider's default

A slider's default, as n_gui_slider_set_default() gave it.

function n_gui_set_widget_visible

void n_gui_set_widget_visible(
    N_GUI_CTX * ctx,
    int widget_id,
    int visible
)

set widget visibility

Show or hide a widget.

set widget visibility

function n_gui_set_widget_tooltip

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.

Parameters:

  • ctx the GUI context
  • widget_id id of the target widget
  • text tooltip text; NULL or "" clears it

Set (or clear) the tooltip text of any widget.

On a split pane only the divider band arms it, not the whole region the pane spans

set (or clear with "" / NULL) the tooltip text shown after the pointer rests on a widget.

The tooltip appears after the pointer rests on the widget for style.tooltip_delay seconds and hides on movement, click, or leave.

On a split pane only the divider band arms it, not the whole region the pane spans, so the text describes the divider the user is pointing at.

function n_gui_set_widget_theme

void n_gui_set_widget_theme(
    N_GUI_CTX * ctx,
    int widget_id,
    N_GUI_THEME theme
)

set the theme on a widget

Override the theme of a specific widget.

set the theme on a widget

function n_gui_set_widget_enabled

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)

Enable or disable a widget.

set widget enabled state (0 = disabled: drawn dimmed and ignores all input)

Disabled widgets are drawn dimmed and ignore all mouse/keyboard input.

function n_gui_set_virtual_size

void n_gui_set_virtual_size(
    N_GUI_CTX * ctx,
    float w,
    float h
)

set the virtual canvas size for resolution-independent scaling.

Set the virtual canvas size for resolution-independent scaling.

When set (w > 0 && h > 0), all widget coordinates are in virtual space. An ALLEGRO_TRANSFORM is applied during draw and mouse input is reverse- transformed automatically. Pass (0, 0) to disable (identity transform). This is opt-in: the virtual canvas is enabled only when both w and h are > 0, and disabled when both are 0 (legacy behaviour).

set the virtual canvas size for resolution-independent scaling.

When enabled (w > 0 && h > 0), all widget coordinates are treated as virtual pixels. An ALLEGRO_TRANSFORM is applied in n_gui_draw() and mouse input is reverse-transformed in n_gui_process_event(). Pass (0, 0) to disable (identity transform, legacy behaviour).

function n_gui_set_shape_mode

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)

Parameters:

  • ctx GUI context. Ignored when NULL.
  • shape_mode N_GUI_SHAPE_ROUNDED for a rounded look, anything else for rectangular. Shape-aware widgets (the dropmenu button + panel, and the buttons/comboboxes that consult it) redraw accordingly on the next frame.

Set the global widget shape (round or square GUI).

set the global widget shape (N_GUI_SHAPE_ROUNDED for a round GUI, else square)

function n_gui_set_resize_mode

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

Set context-level resize mode: N_GUI_RESIZE_VIRTUAL (default) or N_GUI_RESIZE_ADAPTIVE.

set context-level resize mode: N_GUI_RESIZE_VIRTUAL (default) or N_GUI_RESIZE_ADAPTIVE

When switching to ADAPTIVE, the virtual canvas is disabled and normalized coordinates are captured for all existing windows.

function n_gui_set_focus

void n_gui_set_focus(
    N_GUI_CTX * ctx,
    int widget_id
)

set keyboard focus to a specific widget (-1 to clear focus)

Parameters:

  • ctx the GUI context
  • widget_id the widget to focus (-1 to clear focus)

Set keyboard focus to a specific widget.

set keyboard focus to a specific widget (-1 to clear focus)

Pass widget_id = -1 to clear focus. If the widget is a textarea, resets cursor blink timer. Raises the parent window if it exists and is open.

function n_gui_set_event_queue

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

Parameters:

  • ctx the GUI context
  • queue the host's event queue, or NULL to forget it. Must be set before n_gui_window_detach, and must outlive every detached window.

Set the event queue used to register native window event sources.

give the context the event queue it registers native window event sources into

function n_gui_set_dpi_scale

void n_gui_set_dpi_scale(
    N_GUI_CTX * ctx,
    float scale
)

set DPI scale factor manually (default is 1.0).

Set DPI scale factor manually (default 1.0).

Affects global scrollbar rendering and can be queried by the application.

set DPI scale factor manually (default is 1.0).

function n_gui_set_double_click_time

void n_gui_set_double_click_time(
    N_GUI_CTX * ctx,
    double seconds
)

how long after a press a second one still counts, in seconds (default 0.4)

Parameters:

  • ctx GUI context
  • seconds the interval; 0 or less disables double click reporting

set how long after a press a second one still counts as a double click

how long after a press a second one still counts, in seconds (default 0.4)

function n_gui_set_double_click_radius

void n_gui_set_double_click_radius(
    N_GUI_CTX * ctx,
    int pixels
)

how far the pointer may move between the two presses, in pixels (default 4)

Parameters:

  • ctx GUI context
  • pixels the radius; negative is read as 0, which requires the two presses to land on exactly the same pixel

set how far the pointer may move between the two presses

how far the pointer may move between the two presses, in pixels (default 4)

function n_gui_set_display_size

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.

Call this on startup and whenever the display is resized. When virtual canvas is enabled, also updates the virtual-to-display transform. A context that is never given a size takes it from n_gui_draw()'s target bitmap on every pass, and logs once that it did; once this is called, the size given here is used and the target is not looked at again.

function n_gui_set_display

void n_gui_set_display(
    N_GUI_CTX * ctx,
    ALLEGRO_DISPLAY * display
)

set the display pointer for clipboard operations (copy/paste)

Set the display pointer for clipboard operations (copy/paste).

set the display pointer for clipboard operations (copy/paste)

function n_gui_set_default_theme

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.

Parameters:

  • ctx N_GUI context. Must not be NULL.
  • theme Theme to apply as the new default.

Sets ctx->default_theme and derives scrollbar track/thumb colors from the theme's bg_normal and border_normal fields so scrollbars match the active theme automatically.

function n_gui_set_default_font

int n_gui_set_default_font(
    N_GUI_CTX * ctx,
    ALLEGRO_FONT * font
)

Replace the context's default font, keeping every widget and its state.

Parameters:

  • ctx the context
  • font the new default font, not NULL

Return: TRUE on success, FALSE on a bad argument

Widgets resolve their font when they are DRAWN (wgt->font ? wgt->font : ctx->default_font) and the text-measurement cache is keyed on the font, so swapping it here re-fonts every widget that has not been given a font of its own. Window content sizes are recomputed from the new metrics so scrollbars and extents stay right.

This exists so a host does not have to destroy and rebuild its context when the UI scale changes (a phone rotating, a window resized). A rebuild loses everything the widgets hold - for the user that means half-typed text vanishing mid-edit.

The caller owns both fonts: keep the old one alive until this returns, and destroy it afterwards.

function n_gui_set_cursor

void n_gui_set_cursor(
    N_GUI_CTX * ctx,
    int system_shape,
    ALLEGRO_MOUSE_CURSOR * custom
)

Say which mouse cursor the application wants.

Parameters:

  • ctx the GUI context
  • system_shape an ALLEGRO_SYSTEM_MOUSE_CURSOR_* value; ALLEGRO_SYSTEM_MOUSE_CURSOR_DEFAULT with a NULL custom goes back to the GUI's own behaviour
  • custom a cursor from al_create_mouse_cursor(), or NULL. Borrowed: the caller keeps it alive while it is set, and sets another before destroying it. Wins over system_shape when not NULL.

The GUI sets the display's cursor itself: a resize cursor over a split pane divider or a datagrid column border, and the default everywhere else. An application that set a cursor of its own with Allegro, a crosshair for a picking tool, had it put back to the default by the GUI on the next pointer move, or kept it past the point where it applied. This makes the application's cursor the GUI's "everywhere else": the resize cursors still show where a drag would resize something, and this one shows the rest of the time. It is applied at once when the display is known, and the call is cheap when nothing changes, so an application can call it on every pointer move with what the pointer is over.

function n_gui_sectionlist_set_widget_offset

void n_gui_sectionlist_set_widget_offset(
    N_GUI_SECTIONLIST * sl,
    int section_index,
    int widget_id,
    float dy
)

state a member's y offset from the section's content top, for a caller that computes its own layout and recomputes it when the window is resized.

The offset captured by n_gui_sectionlist_add_widget() is only right while the layout it was captured from is; this is how it is corrected. Does nothing when the widget is not a member of that section.

function n_gui_sectionlist_set_widget_hidden

void n_gui_sectionlist_set_widget_hidden(
    N_GUI_SECTIONLIST * sl,
    int section_index,
    int widget_id,
    int hidden
)

keep a member hidden whatever the fold state, and leave it out of the section's height.

For a section whose contents vary at run time: a plugin's unused sliders, a list's empty rows. Unhiding puts it back under the fold state like every other member.

function n_gui_sectionlist_set_section_hidden

void n_gui_sectionlist_set_section_hidden(
    N_GUI_SECTIONLIST * sl,
    int section_index,
    int hidden
)

Leave a whole section out of the stack, header and members, or put it back.

Parameters:

  • sl the list
  • section_index the section
  • hidden 1 to leave it out

Its fold state is kept for when it returns. Relayouts.

function n_gui_sectionlist_set_order

void n_gui_sectionlist_set_order(
    N_GUI_SECTIONLIST * sl,
    const int * order,
    int count
)

Stack the sections in another order.

Parameters:

  • sl the list
  • order section indices, top to bottom
  • count how many entries order has

Section indices do not change - every call that takes an index still means the same section - only where each is drawn. order lists indices top to bottom; an index missing from it keeps its place after the listed ones, in index order, and an index out of range or given twice is ignored, so a saved order that predates a new section, or names one that has gone, still gives a complete stack. Relayouts.

function n_gui_sectionlist_set_geometry

void n_gui_sectionlist_set_geometry(
    N_GUI_SECTIONLIST * sl,
    float x,
    float y0,
    float width,
    float header_h,
    float gap
)

restate where the list stacks from, how wide its headers are and the two heights it stacks with, for a caller whose window is resized or whose interface scale changes after the list was made.

Takes effect at the next n_gui_sectionlist_relayout().

function n_gui_sectionlist_set_folded

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)

function n_gui_sectionlist_set_first_inset

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

function n_gui_sectionlist_relayout

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

function n_gui_sectionlist_is_section_hidden

int n_gui_sectionlist_is_section_hidden(
    const N_GUI_SECTIONLIST * sl,
    int section_index
)

Is a section left out of the stack.

Parameters:

  • sl the list
  • section_index the section

Return: 1 when hidden, 0 otherwise or out of range

function n_gui_sectionlist_is_folded

int n_gui_sectionlist_is_folded(
    const N_GUI_SECTIONLIST * sl,
    int section_index
)

query a section's folded state (1 = folded, 0 = expanded)

function n_gui_sectionlist_get_order

int n_gui_sectionlist_get_order(
    const N_GUI_SECTIONLIST * sl,
    int position
)

The section stacked at a position.

Parameters:

  • sl the list
  • position 0 for the top

Return: its index, or -1 for a position out of range

function n_gui_sectionlist_get_count

int n_gui_sectionlist_get_count(
    const N_GUI_SECTIONLIST * sl
)

number of sections in the list

function n_gui_sectionlist_free

void n_gui_sectionlist_free(
    N_GUI_SECTIONLIST ** sl
)

free the section list (does not destroy the N_GUI widgets or window)

function n_gui_sectionlist_create

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(*)(int, int, void *) on_toggle,
    void * user_data
)

create an empty section list anchored at (x,y0) in window_id; sections stack downward from y0

function n_gui_sectionlist_content_height

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

function n_gui_sectionlist_add_widget

int 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).

Returns 0, or -1 when the section is full (N_GUI_SECTION_WIDGETS_MAX, logged) or an argument is not usable; a member refused is left where it was created and nothing lays it out

function n_gui_sectionlist_add_section

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

function n_gui_scrollbar_set_wheel_step

void n_gui_scrollbar_set_wheel_step(
    N_GUI_CTX * ctx,
    int widget_id,
    double step
)

set how far one wheel notch moves a scrollbar, in its content units: 1 for a list whose content is counted in rows moves it a row a notch.

Parameters:

  • ctx GUI context
  • widget_id id of the scrollbar widget
  • step content units per notch; 0 or less for a twentieth of the range

set how far one wheel notch moves a scrollbar

0 or less puts back the default, a twentieth of the range, which on a short list takes several notches to move one row.

set how far one wheel notch moves a scrollbar, in its content units: 1 for a list whose content is counted in rows moves it a row a notch.

function n_gui_scrollbar_set_sizes

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

Parameters:

  • ctx GUI context
  • widget_id id of the scrollbar widget
  • content_size total size of the content
  • viewport_size visible viewport size

set the content and viewport sizes of a scrollbar widget

set scrollbar content and viewport sizes

function n_gui_scrollbar_set_pos

void n_gui_scrollbar_set_pos(
    N_GUI_CTX * ctx,
    int widget_id,
    double pos
)

set scrollbar position

Parameters:

  • ctx GUI context
  • widget_id id of the scrollbar widget
  • pos new scroll position

set the scroll position of a scrollbar widget

set scrollbar position

function n_gui_scrollbar_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a scrollbar widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a scrollbar widget.

function n_gui_scrollbar_get_pos

double n_gui_scrollbar_get_pos(
    N_GUI_CTX * ctx,
    int widget_id
)

get scrollbar position

Parameters:

  • ctx GUI context
  • widget_id id of the scrollbar widget

Return: current scroll position

get the current scroll position of a scrollbar widget

get scrollbar position

function n_gui_screen_to_virtual

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.

Parameters:

  • ctx GUI context
  • sx screen X (physical pixels)
  • sy screen Y (physical pixels)
  • vx output virtual X (may be NULL)
  • vy output virtual Y (may be NULL)

Convert physical screen coordinates to virtual canvas coordinates.

If virtual canvas is disabled, outputs equal inputs. convert physical screen coordinates to virtual canvas coordinates.

If virtual canvas is disabled (virtual_w/virtual_h == 0), outputs equal inputs.

function n_gui_save_theme_json

int n_gui_save_theme_json(
    N_GUI_CTX * ctx,
    const char * filepath
)

Save the full theme (default_theme + style) to a JSON file.

Parameters:

  • ctx GUI context
  • filepath path to the output JSON file

Return: 0 on success, -1 on error

save the current theme and style to a JSON file

Returns 0 on success, -1 on error.

Save the full theme (default_theme + style) to a JSON file.

function n_gui_save_layout_json

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.

Parameters:

  • ctx GUI context
  • filepath path to the output JSON file

Return: 0 on success, -1 on error

save the geometry + persistent state of every window to a JSON file

Persists per-window: title, x, y, w, h, state (persistent bits only), z_order, z_value, flags, norm_x/y/w/h, autofit_flags, autofit_border, resize_policy. Widget content and callbacks are NOT saved, they are domain data owned by the calling program, EXCEPT the user-adjustable state of widgets that were given a persist key (n_gui_widget_set_persist_key): each such widget's splitpane divider ratio, or datagrid column order/visibility/width, is saved under a per-window "widgets" array so the layout survives a restart. Returns 0 on success, -1 on error.

Save the geometry + persistent state of every window in the context to a JSON file.

function n_gui_restore_window

void n_gui_restore_window(
    N_GUI_CTX * ctx,
    int window_id
)

restore a minimised window to its full size

Parameters:

  • ctx the gui context
  • window_id the id of the window to restore

Restore a minimised window to its full size.

restore a minimised window to its full size

Unlike n_gui_minimize_window, which toggles, this always clears the minimised state, so a caller that is about to show a window (an "open this dialog" action) can guarantee the content is visible without knowing the current state. A window that is not minimised is left untouched, and the maximised state is not affected.

function n_gui_reset_all_widget_themes

void n_gui_reset_all_widget_themes(
    N_GUI_CTX * ctx
)

reset all widget and window themes to ctx->default_theme

Reset all widget and window themes to ctx->default_theme.

reset all widget and window themes to ctx->default_theme

Iterates every window and every widget, setting their theme to the context default. Call this after changing ctx->default_theme so that all existing widgets pick up the new palette. Widgets that need a custom theme (accent buttons, status labels, etc.) must be re-themed individually after this call.

function n_gui_raise_window

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)

Bring a window to the front (top of draw order).

raise a window to the top of the stack (respects z-order constraints)

Respects z-order constraints: ALWAYS_BEHIND, FIXED and ALWAYS_ON_TOP windows are not moved. NORMAL and POPUP windows are raised WITHIN their own z-group (the stable re-sort keeps group boundaries). After raising, the window list is re-sorted.

function n_gui_radiolist_set_selected

void n_gui_radiolist_set_selected(
    N_GUI_CTX * ctx,
    int widget_id,
    int index
)

set the selected item index

Parameters:

  • ctx GUI context
  • widget_id id of the radiolist widget
  • index index of the item to select, or -1 for none

set the selected item in a radiolist widget

set the selected item index

function n_gui_radiolist_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a radiolist widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a radiolist widget.

function n_gui_radiolist_get_selected

int n_gui_radiolist_get_selected(
    N_GUI_CTX * ctx,
    int widget_id
)

get the selected item index

Parameters:

  • ctx GUI context
  • widget_id id of the radiolist widget

Return: index of the selected item, or -1 if none

get the selected item index in a radiolist widget

get the selected item index

function n_gui_radiolist_clear

void n_gui_radiolist_clear(
    N_GUI_CTX * ctx,
    int widget_id
)

remove all items from a radio list

Parameters:

  • ctx GUI context
  • widget_id id of the radiolist widget

remove all items from a radiolist widget

remove all items from a radio list

function n_gui_radiolist_add_item

int n_gui_radiolist_add_item(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text
)

add an item to a radio list

Parameters:

  • ctx GUI context
  • widget_id id of the radiolist widget
  • text text of the item to add

Return: index of the new item or -1 on error

add an item to a radiolist widget

add an item to a radio list

function n_gui_progressbar_set_value

void n_gui_progressbar_set_value(
    N_GUI_CTX * ctx,
    int widget_id,
    float value
)

set the progress fraction (clamped to 0.0 .

. 1.0)

function n_gui_progressbar_set_text

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)

function n_gui_progressbar_get_value

float n_gui_progressbar_get_value(
    N_GUI_CTX * ctx,
    int widget_id
)

get the current progress fraction (0.0 on an invalid widget)

function n_gui_process_event

int n_gui_process_event(
    N_GUI_CTX * ctx,
    ALLEGRO_EVENT event
)

process an allegro event for the GUI

Parameters:

  • ctx the GUI context
  • event the allegro event to process

Return: 1 if the event was consumed by the GUI (mouse over a window/widget, active capture operation, keyboard input to focused widget, etc.), 0 if the event was not handled by the GUI and can be processed by the application (e.g. game logic).

Process an allegro event through the GUI system.

process an allegro event for the GUI

function n_gui_open_window

void n_gui_open_window(
    N_GUI_CTX * ctx,
    int window_id
)

open (show) a window

Open (show) a window.

open (show) a window

function n_gui_new_ctx

N_GUI_CTX * n_gui_new_ctx(
    ALLEGRO_FONT * default_font
)

create a new GUI context

Parameters:

  • default_font the default ALLEGRO_FONT to use

Return: a new N_GUI_CTX or NULL on error

Create a new GUI context.

create a new GUI context

function n_gui_needs_redraw

int n_gui_needs_redraw(
    N_GUI_CTX * ctx
)

Return non-zero if the GUI must be redrawn this frame, i.e.

something changed since the last n_gui_draw OR a time-based animation is in progress (focused text-area cursor blink, tooltip reveal, button key-press flash). Lets an event-driven host skip n_gui_draw + al_flip_display while the GUI is idle and unchanged: while (running) { while (al_get_next_event(q, &ev)) n_gui_process_event(ctx, &ev); if (n_gui_needs_redraw(ctx)) { clear; n_gui_draw(ctx); flip; } } Hosts that redraw every frame regardless (a GUI composited over a live game scene) can ignore this. Optional and additive: the dirty bit is maintained whether or not it is queried, so calling n_gui_draw unconditionally is unchanged. Detached native windows still need n_gui_draw_detached each frame.

function n_gui_minimize_window

void n_gui_minimize_window(
    N_GUI_CTX * ctx,
    int window_id
)

minimize a window (title bar only)

Minimise a window (show title bar only).

minimize a window (title bar only)

function n_gui_menu_is_open

int n_gui_menu_is_open(
    const N_GUI_CTX * ctx
)

Is a combo box's list or a drop menu's panel currently open.

Parameters:

  • ctx the GUI context

Return: 1 when one is open, 0 otherwise.

Either one is drawn over whatever it happens to cover, and the press that chooses an item lands there rather than on the widget that opened it. An application that routes presses by position of its own - a canvas, a viewport, anything that claims the mouse inside its own rectangle - has to ask this first and let the toolkit have the press, or the thing underneath takes it and the list can neither be chosen from nor closed.

function n_gui_maximize_window

void n_gui_maximize_window(
    N_GUI_CTX * ctx,
    int window_id
)

toggle maximised state (full display or restore to previous size)

Toggle maximised state (full display or restore to previous size).

toggle maximised state (full display or restore to previous size)

When maximising: saves current position/size, expands to fill the display (or virtual canvas if enabled), and clears minimised state. When restoring: returns to the saved position/size.

function n_gui_markdownview_style

N_GUI_MD_STYLE * n_gui_markdownview_style(
    N_GUI_CTX * ctx,
    int widget_id
)

the view's style, to read or to change in place, or NULL if there is no such widget.

Asking for it stops the style following the widget's theme, because there is no way to tell afterwards which of the two set a colour.

function n_gui_markdownview_set_text

void n_gui_markdownview_set_text(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text
)

set the Markdown source (copied; NULL clears it).

Resets the scroll.

function n_gui_markdownview_set_on_link

void n_gui_markdownview_set_on_link(
    N_GUI_CTX * ctx,
    int widget_id,
    void(*)(int widget_id, const char *url, void *user_data) on_link,
    void * user_data
)

call on_link when a link in the view is clicked (NULL to stop).

The url it is handed is valid for the duration of the call and no longer.

function n_gui_markdownview_set_fonts

void n_gui_markdownview_set_fonts(
    N_GUI_CTX * ctx,
    int widget_id,
    const N_GUI_MD_FONTS * fonts
)

replace the faces; the new ones are borrowed on the same terms

function n_gui_markdownview_scroll_to

void n_gui_markdownview_scroll_to(
    N_GUI_CTX * ctx,
    int widget_id,
    float y
)

scroll to y pixels down the content, clamped to what there is

function n_gui_markdownview_get_text

const char * n_gui_markdownview_get_text(
    N_GUI_CTX * ctx,
    int widget_id
)

the Markdown source, owned by the widget, or NULL

function n_gui_markdownview_get_scroll

float n_gui_markdownview_get_scroll(
    N_GUI_CTX * ctx,
    int widget_id
)

how far down the content the view is, in pixels

function n_gui_markdownview_content_height

float n_gui_markdownview_content_height(
    N_GUI_CTX * ctx,
    int widget_id
)

the height of the whole document at the width it was last drawn at, or 0 before the first draw

function n_gui_mark_dirty

void n_gui_mark_dirty(
    N_GUI_CTX * ctx
)

Mark the GUI as needing a redraw.

Call after changing widget or window state from outside n_gui_process_event (for example a host timer that updates a label or progress bar); state changed inside an event callback is already covered because the event itself marks the GUI dirty. Cheap and idempotent.

function n_gui_make_theme

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

Parameters:

  • bg background colour
  • bg_hover background colour on hover
  • bg_active background colour when active
  • border border colour
  • border_hover border colour on hover
  • border_active border colour when active
  • text text colour
  • text_hover text colour on hover
  • text_active text colour when active
  • border_thickness border thickness in pixels
  • corner_rx horizontal corner radius
  • corner_ry vertical corner radius

Return: configured N_GUI_THEME

Create a custom theme with explicit colours.

create a custom theme from individual colors and properties

function n_gui_lower_window

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)

Lower a window to the bottom of the draw order.

lower a window to the bottom of the stack (respects z-order constraints)

Only NORMAL windows can be lowered.

function n_gui_load_theme_json

int n_gui_load_theme_json(
    N_GUI_CTX * ctx,
    const char * filepath
)

Load a JSON theme file and apply it to the context.

Parameters:

  • ctx GUI context
  • filepath path to the input JSON file

Return: 0 on success, -1 on error

load a theme and style from a JSON file

Returns 0 on success, -1 on error.

Load a JSON theme file and apply it to the context.

function n_gui_load_layout_json

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.

Parameters:

  • ctx GUI context
  • filepath path to the input JSON file

Return: 0 on success, -1 on error

load a JSON window layout file and apply it to matching windows

Matching is by window title (IDs are not stable across runs). If multiple windows share a title, they are matched in creation order (first-seen-first-match). Unknown titles in the file are ignored (defensive for versions). Missing titles in the context are ignored (no-op for windows not yet created). A missing file is treated as a successful no-op (returns -1 with LOG_DEBUG). Saved per-window widget state (see n_gui_save_layout_json) is stashed as pending and applied to each keyed widget when n_gui_widget_set_persist_key is next called with a matching window title + key (so lazily-created widgets restore too). Returns 0 on success, -1 on error.

Load a JSON window layout file and apply it to matching windows in the context.

function n_gui_listbox_set_selected

void n_gui_listbox_set_selected(
    N_GUI_CTX * ctx,
    int widget_id,
    int index,
    int selected
)

set item selection state

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget
  • index index of the item
  • selected 1 to select, 0 to deselect

set the selection state of a listbox item

set item selection state

function n_gui_listbox_set_scroll_offset

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

function n_gui_listbox_set_h_scroll

void n_gui_listbox_set_h_scroll(
    N_GUI_CTX * ctx,
    int widget_id,
    float px
)

set the horizontal scroll offset in pixels; clamped to >= 0 here and to the live content width by the draw path, so a stale value after a refill is harmless

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget
  • px the offset in pixels

set a listbox's horizontal scroll offset in pixels

set the horizontal scroll offset in pixels; clamped to >= 0 here and to the live content width by the draw path, so a stale value after a refill is harmless

Clamped to >= 0 here; the draw path re-clamps to the live content width every frame, so a value left over from a wider list is harmless.

function n_gui_listbox_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a listbox widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a listbox widget.

function n_gui_listbox_remove_item

int n_gui_listbox_remove_item(
    N_GUI_CTX * ctx,
    int widget_id,
    int index
)

remove an item from a listbox by index

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget
  • index index of the item to remove

Return: 0 on success, -1 on error

remove an item from a listbox widget

remove an item from a listbox by index

function n_gui_listbox_is_selected

int n_gui_listbox_is_selected(
    N_GUI_CTX * ctx,
    int widget_id,
    int index
)

check if an item is selected

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget
  • index index of the item to check

Return: 1 if selected, 0 otherwise

check if a listbox item is selected

check if an item is selected

function n_gui_listbox_get_selected

int n_gui_listbox_get_selected(
    N_GUI_CTX * ctx,
    int widget_id
)

get the first selected item index

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget

Return: index of the first selected item, or -1 if none

get the index of the first selected item in a listbox

get the first selected item index

function n_gui_listbox_get_scroll_offset

int n_gui_listbox_get_scroll_offset(
    N_GUI_CTX * ctx,
    int widget_id
)

get the current scroll offset (in items)

function n_gui_listbox_get_item_text

const char * n_gui_listbox_get_item_text(
    N_GUI_CTX * ctx,
    int widget_id,
    int index
)

get item text by index

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget
  • index index of the item

Return: pointer to the item text, or empty string on error

get the text of a listbox item

get item text by index

function n_gui_listbox_get_h_scroll

float n_gui_listbox_get_h_scroll(
    N_GUI_CTX * ctx,
    int widget_id
)

current horizontal scroll offset in pixels (0 = leftmost)

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget

Return: the offset, or 0 when the widget is not a listbox

get a listbox's horizontal scroll offset in pixels (0 = leftmost)

current horizontal scroll offset in pixels (0 = leftmost)

function n_gui_listbox_get_count

int n_gui_listbox_get_count(
    N_GUI_CTX * ctx,
    int widget_id
)

get number of items in a listbox

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget

Return: number of items

get the number of items in a listbox widget

get number of items in a listbox

function n_gui_listbox_content_width

float n_gui_listbox_content_width(
    N_GUI_CTX * ctx,
    int widget_id
)

width in pixels the widest item needs to be drawn in full (text padding included), or 0 for an empty list / non-listbox widget.

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget

Return: the content width in pixels, or 0 for an empty list, a listbox with no usable font, or a widget that is not a listbox

width the widest item of a listbox needs to be drawn in full

When this exceeds the room left for the items, the listbox scrolls horizontally instead of truncating the text

width in pixels the widest item needs to be drawn in full (text padding included), or 0 for an empty list / non-listbox widget.

Text padding included, so it can be compared directly with the room left for the items. Past that width the listbox scrolls horizontally rather than cutting the text short with an ellipsis.

function n_gui_listbox_clear

void n_gui_listbox_clear(
    N_GUI_CTX * ctx,
    int widget_id
)

clear all items from a listbox

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget

remove all items from a listbox widget

clear all items from a listbox

function n_gui_listbox_add_item

int n_gui_listbox_add_item(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text
)

add an item to a listbox

Parameters:

  • ctx GUI context
  • widget_id id of the listbox widget
  • text text of the item to add

Return: index of the new item or -1 on error

add an item to a listbox widget

add an item to a listbox

function n_gui_label_set_truncate

void n_gui_label_set_truncate(
    N_GUI_CTX * ctx,
    int widget_id,
    int mode
)

choose where a label's text is shortened when it does not fit: N_GUI_TRUNCATE_END (the default), N_GUI_TRUNCATE_START or N_GUI_TRUNCATE_PATH.

Parameters:

  • ctx GUI context
  • widget_id id of the label widget
  • text the text to set, or NULL to clear
  • ctx GUI context
  • widget_id id of the label widget
  • mode N_GUI_TRUNCATE_END, N_GUI_TRUNCATE_START or N_GUI_TRUNCATE_PATH; anything else is taken as N_GUI_TRUNCATE_END

set the text of a label widget

A path shown with the default loses its file name, the one part that says which file it is. Ignored for a justified label.

choose where a label's text is shortened when it does not fit: N_GUI_TRUNCATE_END (the default), N_GUI_TRUNCATE_START or N_GUI_TRUNCATE_PATH.

choose where a label's text is shortened when it does not fit

function n_gui_label_set_text

void n_gui_label_set_text(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text
)

set label text content

function n_gui_label_set_link

void n_gui_label_set_link(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * link
)

set label hyperlink URL

Parameters:

  • ctx GUI context
  • widget_id id of the label widget
  • link the URL to set, or NULL to clear

set the link URL of a label widget

set label hyperlink URL

function n_gui_label_set_bitmap

void n_gui_label_set_bitmap(
    N_GUI_CTX * ctx,
    int widget_id,
    ALLEGRO_BITMAP * bg
)

set optional background bitmap on a label widget.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional background bitmap on a label widget.

set optional background bitmap on a label widget.

function n_gui_label_get_truncate

int n_gui_label_get_truncate(
    N_GUI_CTX * ctx,
    int widget_id
)

the label's truncate mode, N_GUI_TRUNCATE_END when it is not a label

Parameters:

  • ctx GUI context
  • widget_id id of the label widget

Return: the mode, N_GUI_TRUNCATE_END when it is not a label

a label's truncate mode

the label's truncate mode, N_GUI_TRUNCATE_END when it is not a label

function n_gui_label_get_text

const char * n_gui_label_get_text(
    N_GUI_CTX * ctx,
    int widget_id
)

What a label says now.

Parameters:

  • ctx the GUI context
  • widget_id a label

Return: The text, or NULL when the widget is not a label. Borrowed, and valid until the text is set again or the widget is destroyed.

The counterpart of n_gui_label_set_text(), as n_gui_button_get_label() and n_gui_checkbox_get_label() are of theirs: for a test that checks the words a dialog was given without keeping its own copy of them.

function n_gui_label_fits

int n_gui_label_fits(
    N_GUI_CTX * ctx,
    int widget_id,
    float * needed_w,
    float * needed_h
)

report whether a label's text is drawn in full inside its own box, and how big it would have to be to show all of it (out-params may be NULL)

Parameters:

  • ctx the gui context
  • widget_id id of the label widget
  • needed_w receives the width the text needs (0 when not applicable, may be NULL)
  • needed_h receives the height the text needs (0 when not applicable, may be NULL)

Return: 1 when the text fits (or the widget is not a label with text), 0 when n_gui truncates it horizontally or clips it vertically as drawn

Report whether a label's text is drawn in full inside its own widget box.

report whether a label's text is drawn in full inside its own box, and how big it would have to be to show all of it (out-params may be NULL)

A label is drawn one of two ways, and both can silently lose text. A single-line label (N_GUI_ALIGN_LEFT, _CENTER, _RIGHT) whose text is wider than its box is drawn truncated; a wrapped one (N_GUI_ALIGN_JUSTIFIED) taller than its box is clipped and grows an inner scrollbar. Neither reports anything, so a layout that under-sizes a label just quietly shows less text. This measures the text the way the draw path does, against the widget's own rectangle, and hands back the size that would show all of it: a layout can size a label from it, and a layout audit can fail on it.

function n_gui_kvtable_set_top_offset

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.

The offset scales with the window like the rest of the table. Default 0.

function n_gui_kvtable_set_row_actions

void n_gui_kvtable_set_row_actions(
    N_GUI_KVTABLE * table,
    int enabled
)

show (1) or hide (0, the default) the per-row action buttons: move up, move down and duplicate, drawn as glyphs next to the remove button.

Parameters:

  • table the KV table
  • enabled 1 to show the actions, 0 to hide them

Show or hide the per-row move-up / move-down / duplicate buttons.

Use for tables whose row ORDER is meaningful (query parameters, headers) and where copying a row is common; leave off for unordered tables. The text columns reflow to make room, and the remove button switches to a matching cross glyph. Moving swaps a row with its neighbour; duplicating inserts the copy right after the source.

show (1) or hide (0, the default) the per-row action buttons: move up, move down and duplicate, drawn as glyphs next to the remove button.

Off by default, so existing tables are unchanged. Turn it on for tables whose row ORDER carries meaning (query parameters, request headers) or where copying a row is a common edit. The buttons exist on every row from creation and are only revealed here, so a table can gain or lose them at any time without rebuilding its rows. The text columns reflow to make room, and the remove button switches to a cross glyph so the trailing cluster reads as one set of icons.

function n_gui_kvtable_set_placeholders

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.

Applies to existing rows and to rows added afterwards. Either argument may be NULL to clear that hint.

function n_gui_kvtable_set_columns

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.

The key column and the remove ("x") button are always shown. Defaults to all shown (a full three-column table, backward compatible). Pass 0 to hide a column for a simpler table, e.g. a single-value list (0,0,0). Hidden columns' widgets are hidden and the visible columns reflow to fill the width.

function n_gui_kvtable_remove_row

void n_gui_kvtable_remove_row(
    N_GUI_KVTABLE * table,
    int row_index
)

remove a row by index (hides widgets, marks inactive)

function n_gui_kvtable_relayout

void n_gui_kvtable_relayout(
    N_GUI_KVTABLE * table
)

re-apply layout to all KV table widgets (positions, sizes, normalized coords).

Called automatically on create/add/remove; callers should invoke it after any manual window size change the kvtable cannot see.

function n_gui_kvtable_move_row

int n_gui_kvtable_move_row(
    N_GUI_KVTABLE * table,
    int row_index,
    int direction
)

move the row at row_index one position up (direction < 0) or down (direction > 0) among the ACTIVE rows, by swapping their contents.

Parameters:

  • table the KV table
  • row_index the row to move
  • direction negative to move up, positive to move down

Return:

  • the row index the contents landed on, or -1 when the row is invalid or already at that end
  • the row index the contents landed on, or -1 when the row is invalid, inactive, or already at that end of the table

Move a row one position up or down among the active rows.

move the row at row_index one position up (direction < 0) or down (direction > 0) among the ACTIVE rows, by swapping their contents.

Row slots are stable (widgets are bound to them and freed slots are reused), so the CONTENTS are swapped with the neighbouring active row rather than the slots themselves. Everything that reads the table by walking the rows in slot order therefore sees the new order with no extra bookkeeping.

function n_gui_kvtable_get_count

int n_gui_kvtable_get_count(
    const N_GUI_KVTABLE * table
)

get the number of active rows

function n_gui_kvtable_free

void n_gui_kvtable_free(
    N_GUI_KVTABLE ** table
)

free a KV table (does not destroy the N_GUI widgets)

function n_gui_kvtable_duplicate_row

int n_gui_kvtable_duplicate_row(
    N_GUI_KVTABLE * table,
    int row_index
)

insert a copy of the row at row_index directly after it.

Parameters:

  • table the KV table
  • row_index the row to copy

Return:

  • the row index holding the copy, or -1 when the row is invalid or the table is full (N_GUI_KV_MAX)
  • the row index holding the copy, or -1 when the row is invalid or the table is full (N_GUI_KV_MAX rows)

Insert a copy of a row directly after it.

insert a copy of the row at row_index directly after it.

A new row is appended (reusing a freed slot when there is one, which may sit anywhere in the array), then every active row's content is rewritten in the wanted order. Going through detached copies of the text keeps the rewrite correct whatever slot the new row landed in, instead of depending on the freed-slot order.

function n_gui_kvtable_create

N_GUI_KVTABLE * n_gui_kvtable_create(
    N_GUI_CTX * ctx,
    int window_id,
    float row_height,
    float padding,
    void(*)(int, void *) on_remove,
    void * user_data
)

create a KV table in an existing window

function n_gui_kvtable_clear

void n_gui_kvtable_clear(
    N_GUI_KVTABLE * table
)

remove every row at once.

The key column and remove button are always kept; the freed row slots (and their widgets) are reused by the next add_row calls, so repeated clear+repopulate cycles do not grow the widget count toward N_GUI_KV_MAX. Use before reloading a table's contents.

function n_gui_kvtable_add_row

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

function n_gui_is_widget_enabled

int n_gui_is_widget_enabled(
    N_GUI_CTX * ctx,
    int widget_id
)

check if a widget is enabled

Return: 1 if enabled, 0 if disabled

Check if a widget is enabled.

check if a widget is enabled

function n_gui_image_set_bitmap

void n_gui_image_set_bitmap(
    N_GUI_CTX * ctx,
    int widget_id,
    ALLEGRO_BITMAP * bitmap
)

set the bitmap on an image widget

Parameters:

  • ctx GUI context
  • widget_id id of the image widget
  • bitmap pointer to the ALLEGRO_BITMAP to set

set the bitmap of an image widget

set the bitmap on an image widget

function n_gui_hovered_widget

int n_gui_hovered_widget(
    const N_GUI_CTX * ctx
)

id of the widget currently under the mouse pointer (hover/active flag, maintained by n_gui_process_event; front-most open window wins), or -1.

Id of the widget currently under the mouse pointer, or -1.

Lets a host pick a system mouse cursor from the hovered widget's type.

id of the widget currently under the mouse pointer (hover/active flag, maintained by n_gui_process_event; front-most open window wins), or -1.

Returns the widget whose HOVER (or ACTIVE, during a press) state flag is set, n_gui_process_event maintains that flag exclusively on the topmost visible widget under the pointer on every mouse event, so this is a cheap per-frame query. Windows are scanned front-to-back; closed windows and invisible or disabled widgets are skipped. Typical use: pick a system mouse cursor (hand over a button, I-beam over a textarea) from n_gui_get_widget(ctx, id)->type.

function n_gui_hexview_set_on_change

void n_gui_hexview_set_on_change(
    N_GUI_CTX * ctx,
    int widget_id,
    void(*)(int, const unsigned char *, size_t, void *) on_change,
    void * user_data
)

set the callback fired after each edit (NULL to clear)

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget
  • on_change the callback, or NULL to clear it
  • user_data opaque pointer handed back to the callback

set the callback fired after each edit

set the callback fired after each edit (NULL to clear)

function n_gui_hexview_set_editable

void n_gui_hexview_set_editable(
    N_GUI_CTX * ctx,
    int widget_id,
    int editable
)

make a hex view editable (or read-only again)

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget
  • editable non-zero to allow editing

make a hex view editable, or read-only again

An editable hex view is the only widget here that can hold and edit arbitrary bytes: a textarea normalizes CRLF and refuses any character below 32, so a caller that must author exact bytes (a protocol message, a malformed request, a binary body) cannot use one. Typing a hex digit overwrites the nibble under the cursor; Insert adds a zero byte, Delete and Backspace remove one; the arrows, Home, End, PageUp and PageDown move; a click places the cursor.

make a hex view editable (or read-only again)

function n_gui_hexview_set_data

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

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget
  • data the bytes to display, or NULL to clear
  • len number of bytes in data

set (copy) the bytes shown by a hex viewer

set (copy) the bytes shown by a hex viewer; data may be NULL to clear

function n_gui_hexview_set_cursor

void n_gui_hexview_set_cursor(
    N_GUI_CTX * ctx,
    int widget_id,
    size_t offset
)

move the edit cursor to a byte offset (clamped to the data length)

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget
  • offset the byte offset, clamped to the data length

move the edit cursor to a byte offset

move the edit cursor to a byte offset (clamped to the data length)

function n_gui_hexview_get_length

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

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget

Return: the byte count, or 0 if the widget is invalid

function n_gui_hexview_get_data

const unsigned char * n_gui_hexview_get_data(
    N_GUI_CTX * ctx,
    int widget_id,
    size_t * len
)

borrow the bytes a hex view holds (valid until the next edit or set_data); *len receives the count.

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget
  • len receives the byte count (may be NULL)

Return: the bytes, valid until the next edit or set_data, or NULL when empty

borrow the bytes a hex view holds

Returns NULL when there are none.

borrow the bytes a hex view holds (valid until the next edit or set_data); *len receives the count.

function n_gui_hexview_get_cursor

size_t n_gui_hexview_get_cursor(
    N_GUI_CTX * ctx,
    int widget_id
)

the byte offset the edit cursor sits on

Parameters:

  • ctx GUI context
  • widget_id id of the hex viewer widget

Return: the offset, or 0 when the widget is invalid

function n_gui_get_window

N_GUI_WINDOW * n_gui_get_window(
    N_GUI_CTX * ctx,
    int window_id
)

get a window by id

Get a window pointer by id.

get a window by id

function n_gui_get_widget

N_GUI_WIDGET * n_gui_get_widget(
    N_GUI_CTX * ctx,
    int widget_id
)

get a widget by id

Get a widget pointer by id.

get a widget by id

function n_gui_get_topmost_open_window

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.

Get the id of the frontmost open, non-minimized window.

Because the window list is kept sorted by z-order group, this is the topmost window currently on screen.

get the id of the frontmost open, non-minimized window (the last one in draw order), or -1 if no window is open.

The window list is kept sorted by z-order group with the topmost group last, so the last open window in list order is the one drawn on top. Returns -1 when no window is open.

function n_gui_get_text_dims

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.

Uses al_get_text_dimensions for accurate measurement including glyph overhangs.

function n_gui_get_shape_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)

Parameters:

  • ctx GUI context.

Return: N_GUI_SHAPE_ROUNDED or N_GUI_SHAPE_RECT (rounded when ctx is NULL).

Get the global widget shape.

get the global widget shape (N_GUI_SHAPE_ROUNDED or N_GUI_SHAPE_RECT)

function n_gui_get_resize_mode

int n_gui_get_resize_mode(
    N_GUI_CTX * ctx
)

get current resize mode

Return: N_GUI_RESIZE_VIRTUAL or N_GUI_RESIZE_ADAPTIVE

Get current resize mode.

get current resize mode

function n_gui_get_key_modifiers

int n_gui_get_key_modifiers(
    const N_GUI_CTX * ctx
)

the modifier keys held down now, as the GUI has seen them

Parameters:

  • ctx the GUI context

Return: ALLEGRO_KEYMOD_SHIFT, _CTRL, _ALT and _ALTGR ORed, 0 for none or a NULL ctx

Allegro's mouse events do not say whether Ctrl or Shift is held, and asking the keyboard state reads the real keyboard, which an event a program made up itself (a test, a replay) never touched. The context follows instead the KEY_DOWN and KEY_UP events given to n_gui_process_event(), resyncs on each KEY_CHAR, which carries the modifiers, and forgets every key when the display loses the focus, since the key up of a key let go elsewhere is never seen.

A key event the program keeps from n_gui_process_event() is not seen; a program that handles some keys itself should still pass the modifier keys' own events through.

function n_gui_get_focus

int n_gui_get_focus(
    const N_GUI_CTX * ctx
)

Which widget has the keyboard, or -1 when none has.

Parameters:

  • ctx the GUI context

Return: The widget id, or -1.

The counterpart n_gui_set_focus() has never had. An application with key bindings of its own has to know whether a key is meant for a widget before it acts on it: a digit typed into a search box is text, and the same digit with nothing focused is whatever the application says it is.

function n_gui_get_event_queue

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)

Get the event queue previously given to n_gui_set_event_queue.

get the event queue previously given to n_gui_set_event_queue (NULL if none)

function n_gui_get_dpi_scale

float n_gui_get_dpi_scale(
    const N_GUI_CTX * ctx
)

get current DPI scale factor

Get current DPI scale factor.

get current DPI scale factor

function n_gui_get_cursor

int n_gui_get_cursor(
    N_GUI_CTX * ctx,
    ALLEGRO_MOUSE_CURSOR ** custom
)

The cursor the GUI last applied to the display.

Parameters:

  • ctx the GUI context
  • custom receives the custom cursor showing, or NULL when a system cursor is. May be NULL.

Return: the ALLEGRO_SYSTEM_MOUSE_CURSOR_* value showing, meaningful when *custom is NULL; ALLEGRO_SYSTEM_MOUSE_CURSOR_DEFAULT for a NULL context

What is showing, which is the application's cursor from n_gui_set_cursor() except where the GUI shows a resize cursor of its own. Recorded even without a display, so a headless test can read it.

function n_gui_focus_window

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)

Give a window keyboard focus and bring it to the front.

give a window keyboard focus: raise it within its z-order group and focus its first focusable widget (clears focus if it has none)

Raises the window within its z-order group (so it is drawn on top of its peers) and moves keyboard focus to its first focusable, visible, enabled widget. If the window has no focusable widget, focus is cleared so global key bindings still fire. Does nothing if the window id is unknown.

function n_gui_focus_takes_key

int n_gui_focus_takes_key(
    const N_GUI_CTX * ctx,
    int keycode
)

Would the focused widget do something with this particular key.

Parameters:

  • ctx the GUI context
  • keycode the ALLEGRO_KEY_* code of the press

Return: 1 when the key belongs to the focused widget.

A text area takes every key, because every key is a character or an edit. A slider, a scrollbar, a list, a grid and an open menu take the keys that move through them - the arrows, Home, End, the page keys and Enter - and no others: a digit typed at a focused slider is not the slider's, and an application that binds digits should still get it.

A button, which has focus only from Tab, Shift+Tab, an arrow or n_gui_set_focus(), takes Enter and Space, which press it, and the four arrows, which move to the next or previous button of its window in reading order.

The key rather than the widget alone, because an application asking "does the focus want keys" has to answer "which key" to be useful. False when nothing is focused, or when what is focused is a label.

function n_gui_dropmenu_set_open

int n_gui_dropmenu_set_open(
    N_GUI_CTX * ctx,
    int widget_id,
    int open
)

open or close a dropdown menu without anybody clicking its button.

Parameters:

  • ctx the GUI context
  • widget_id a dropmenu widget
  • open non-zero to open, zero to close

Return: 1 when the menu is open afterwards, 0 when it is not

Open or close a dropdown menu without a click on its button.

The panel is positioned from the button's rectangle, so a caller wanting a menu somewhere else - a context menu at the pointer, say - moves the widget there with n_gui_widget_set_rect() first and may hide the button with n_gui_set_widget_visible(): the panel is drawn and hit tested from ctx->open_dropmenu_id rather than from the button's own visibility, so a hidden button still gives a working menu.

Opening does what a click on the button does: it closes any other open dropmenu or combobox, clears the highlight so nothing is pre-selected, and calls the on_open callback so dynamic entries are rebuilt. Closing a menu that is not the open one does nothing.

open or close a dropdown menu without anybody clicking its button.

The same sequence the button's own press runs, so a menu opened this way behaves like one opened by hand: any other open dropmenu or combobox is closed first, nothing is pre-highlighted, and the on_open callback rebuilds the dynamic entries.

The panel is positioned from the button's rectangle and drawn from ctx->open_dropmenu_id, not from the button's visibility, so a caller that wants a context menu at the pointer can move the widget there and hide the button. The parameters are documented once, in n_gui.h.

function n_gui_dropmenu_set_label

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)

Parameters:

  • ctx the GUI context
  • widget_id the dropmenu widget id
  • label new button label, or NULL to clear

Replace the button label shown on a dropmenu.

replace the button label shown on a dropmenu (NULL clears it)

The label is the text drawn on the collapsed dropmenu button (before the arrow). Useful when a single dropmenu widget is reused to present different menus (a pooled toolbar category button, for instance). A NULL label clears it. The text is truncated to N_GUI_ID_MAX-1 bytes.

function n_gui_dropmenu_set_flags

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)

Set dropmenu feature flags (bitmask of N_GUI_DROPMENU_* values).

set dropmenu feature flags (bitmask of N_GUI_DROPMENU_* values)

function n_gui_dropmenu_set_entry_text

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

Update text of an existing entry.

update text of an existing entry by index

function n_gui_dropmenu_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a dropmenu widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a dropmenu widget.

function n_gui_dropmenu_panel_width

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).

Parameters:

  • ctx the GUI context
  • widget_id the dropmenu widget id

Return: the panel width in pixels, or 0 for a non-dropmenu widget

Width the open drop-down panel needs to show its entries.

Returns 0 for a non-dropmenu widget.

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).

The collapsed dropmenu button is often narrow (it only shows a short category label), but the floating panel must be wide enough that its entries read in full. This returns the larger of the button width and the widest entry text, padded by the item text padding on both sides and, when the entry count overflows the visible window, the scrollbar width. The draw and hit-test paths share it so the panel background, the clickable item area, and the scrollbar all use one width.

function n_gui_dropmenu_is_open

int n_gui_dropmenu_is_open(
    N_GUI_CTX * ctx,
    int widget_id
)

is a dropdown menu's panel showing

Parameters:

  • ctx the GUI context
  • widget_id a dropmenu widget

Return: 1 when its panel is open

Is a dropdown menu's panel showing.

is a dropdown menu's panel showing

function n_gui_dropmenu_get_count

int n_gui_dropmenu_get_count(
    N_GUI_CTX * ctx,
    int widget_id
)

get number of entries

Get number of entries in a dropdown menu.

get number of entries

function n_gui_dropmenu_clear_dynamic

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)

Remove all dynamic entries (keep static ones).

remove all dynamic entries (call from on_open callback before re-adding)

function n_gui_dropmenu_clear

void n_gui_dropmenu_clear(
    N_GUI_CTX * ctx,
    int widget_id
)

remove all entries

Remove all entries from a dropdown menu.

remove all entries

function n_gui_dropmenu_add_entry

int n_gui_dropmenu_add_entry(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text,
    int tag,
    void(*)(int, int, int, void *) on_click,
    void * user_data
)

add a static entry to a dropdown menu

Return: entry index, or -1 on error

Add a static entry to a dropdown menu.

add a static entry to a dropdown menu

function n_gui_dropmenu_add_dynamic_entry

int n_gui_dropmenu_add_dynamic_entry(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text,
    int tag,
    void(*)(int, int, int, void *) on_click,
    void * user_data
)

add a dynamic entry (rebuilt each time menu opens)

Return: entry index, or -1 on error

Add a dynamic entry (rebuilt each time menu opens).

add a dynamic entry (rebuilt each time menu opens)

function n_gui_draw_detached

void n_gui_draw_detached(
    N_GUI_CTX * ctx
)

render and flip every detached window, and release the ones whose native window was closed.

Render and flip every detached window, and release the ones whose native window was closed.

Call once per frame, after the event queue has been drained. Restores the caller's target bitmap before returning, and does not touch the main display's backbuffer.

render and flip every detached window, and release the ones whose native window was closed.

Call once per frame, after the event queue has been drained: this is the safe point where a display whose close was requested is actually destroyed, so no already-queued event can name a freed display.

Each native window is drawn with an identity transform, the virtual canvas, global scroll and global scrollbars belong to the main display only. The caller's target bitmap is restored before returning.

function n_gui_draw

void n_gui_draw(
    N_GUI_CTX * ctx
)

draw all visible GUI windows and widgets

function n_gui_double_clicked_widget

int n_gui_double_clicked_widget(
    const N_GUI_CTX * ctx
)

id of the widget the primary press just processed double clicked, or -1.

Parameters:

  • ctx GUI context

Return: the widget id, or -1 when the last event was not a double click

id of the widget the primary press just processed double clicked

Valid until the next event is processed. Two presses count when they land on the same widget inside n_gui_set_double_click_time() of each other and within n_gui_set_double_click_radius() pixels.

id of the widget the primary press just processed double clicked, or -1.

Valid until the next event goes through n_gui_process_event(). Two presses count as a double click when they land on the same widget, inside n_gui_set_double_click_time() of each other, and within n_gui_set_double_click_radius() pixels.

The radius matters as much as the interval. Without it a drag that happens to pause reads as a double click, which is the part hosts rolling their own leave out and then wonder why the gesture fires when it should not.

function n_gui_detect_dpi_scale

float n_gui_detect_dpi_scale(
    N_GUI_CTX * ctx,
    ALLEGRO_DISPLAY * display
)

detect and apply DPI scale from the given allegro display.

Return: the detected scale factor (also stored in ctx->dpi_scale)

Detect and apply DPI scale from an Allegro display.

Works on Linux (X11/Wayland), Windows, and Android. Returns the detected scale factor.

detect and apply DPI scale from the given allegro display.

Detection strategy (cross-platform):

  • Compare the physical pixel size (framebuffer) to the logical window size. On HiDPI displays these differ (e.g. a 1920-logical window may have a 3840-pixel framebuffer on a 2x Retina display).
  • On Android, al_get_display_option(ALLEGRO_DEFAULT_DISPLAY_ADAPTER) and the framebuffer/window ratio gives the density scale.
  • On Windows with per-monitor DPI awareness, the ratio reflects the OS scaling percentage (125% = 1.25, 150% = 1.5, etc.).
  • On Linux/X11/Wayland, the ratio picks up Xft.dpi or Wayland scale factor if Allegro was built with the appropriate backend.

If the framebuffer and window sizes are both reported identically (no HiDPI support from the Allegro build), the function falls back to 1.0.

function n_gui_destroy_ctx

void n_gui_destroy_ctx(
    N_GUI_CTX ** ctx
)

destroy a GUI context and free all resources

Parameters:

  • ctx pointer to the context pointer (set to NULL)

Destroy a GUI context and all its windows/widgets.

destroy a GUI context and free all resources

function n_gui_default_theme

N_GUI_THEME n_gui_default_theme(
    void 
)

return the built-in default theme

Return: a N_GUI_THEME with dark-ish colours

Build a sensible default colour theme.

return the built-in default theme

function n_gui_default_tb_close_theme

N_GUI_THEME n_gui_default_tb_close_theme(
    void 
)

return the built-in default theme for the titlebar close button (red hover/active)

Build a default theme for the titlebar close button.

return the built-in default theme for the titlebar close button (red hover/active)

Same as the btn theme but with red hover/active backgrounds.

function n_gui_default_tb_btn_theme

N_GUI_THEME n_gui_default_tb_btn_theme(
    void 
)

return the built-in default theme for titlebar minimize/maximize buttons

Build a default theme for titlebar minimize/maximize buttons.

return the built-in default theme for titlebar minimize/maximize buttons

Semi-transparent, blends with the titlebar background.

function n_gui_default_style

N_GUI_STYLE n_gui_default_style(
    void 
)

return the built-in default style

Build sensible default style (all configurable sizes, colours, paddings).

return the built-in default style

function n_gui_datagrid_sort

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)

function n_gui_datagrid_set_selected

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).

-1 clears the selection and fires nothing; a row past the end is ignored.

function n_gui_datagrid_set_scroll_offset

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.

Pairs with n_gui_datagrid_get_scroll_offset to preserve the scroll position across a clear/refill.

function n_gui_datagrid_set_row_color

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.

a rule engine coloring matching entries). The tint is drawn under the cell text and follows the row through a sort; the selection is drawn over it as a darkening wash plus an active border so a tinted row still reads as selected. Cell text switches to black or white per the tint luminance so it stays legible. Row colors are dropped by n_gui_datagrid_clear_rows() along with the rows they belong to.

function n_gui_datagrid_set_on_context

void n_gui_datagrid_set_on_context(
    N_GUI_CTX * ctx,
    int widget_id,
    void(*)(int, int, int, int, void *) on_context
)

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.

The callback shares the data grid's user_data. Pass NULL to disable.

function n_gui_datagrid_set_on_columns_changed

void n_gui_datagrid_set_on_columns_changed(
    N_GUI_CTX * ctx,
    int widget_id,
    void(*)(int, void *) cb
)

set the callback fired after the user drags a column border to resize it, so the host can persist the layout.

Pass NULL to disable.

function n_gui_datagrid_set_multiselect

void n_gui_datagrid_set_multiselect(
    N_GUI_CTX * ctx,
    int widget_id,
    int enabled
)

enable (1) or disable (0) multi-row selection.

When enabled, a plain click selects one row, Ctrl-click toggles a row, and Shift-click selects the range from the anchor; all selected rows are highlighted. Single-select consumers are unaffected (the default is disabled).

function n_gui_datagrid_set_h_scroll

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).

Pairs with n_gui_datagrid_get_h_scroll.

function n_gui_datagrid_set_column_width

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)

function n_gui_datagrid_set_column_visible

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

function n_gui_datagrid_select_row

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.

a select-all action); selecting also makes it the primary selected row

function n_gui_datagrid_move_column

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)

function n_gui_datagrid_is_row_selected

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)

function n_gui_datagrid_get_sort

int n_gui_datagrid_get_sort(
    N_GUI_CTX * ctx,
    int widget_id,
    int * col,
    int * dir
)

read back the sort a datagrid is currently showing.

Parameters:

  • ctx The GUI context.
  • widget_id The datagrid.
  • col Receives the sorted column, or -1 when the grid is unsorted. May be NULL.
  • dir Receives 1 for ascending or -1 for descending. May be NULL.

Return: TRUE when the widget is a datagrid, FALSE otherwise.

n_gui_datagrid_clear_rows does NOT reset sort_col / sort_dir, and the header indicator is drawn from them, so a caller that rebuilds its rows leaves the header claiming an order the rows are no longer in. Without an accessor there was nothing to re-apply after the rebuild. Read the sort before clearing, re-apply it with n_gui_datagrid_sort after the rows are back, and the header stops lying.

function n_gui_datagrid_get_selected_rows

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.

With multi-select disabled this reports the single selected row. out may be NULL to just count.

function n_gui_datagrid_get_selected

int n_gui_datagrid_get_selected(
    N_GUI_CTX * ctx,
    int widget_id
)

get the selected row index, or -1 if none

function n_gui_datagrid_get_scroll_offset

int n_gui_datagrid_get_scroll_offset(
    N_GUI_CTX * ctx,
    int widget_id
)

first visible data row (the vertical scroll position), or 0.

Read it before a rebuild and pass it back to n_gui_datagrid_set_scroll_offset so an in-place edit that clears and refills the grid does not jump the view back to the top.

function n_gui_datagrid_get_row_count

int n_gui_datagrid_get_row_count(
    N_GUI_CTX * ctx,
    int widget_id
)

get the number of rows in a data grid

function n_gui_datagrid_get_row_color

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.

out may be NULL to just test.

function n_gui_datagrid_get_h_scroll

float n_gui_datagrid_get_h_scroll(
    N_GUI_CTX * ctx,
    int widget_id
)

function n_gui_datagrid_get_column_width

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

function n_gui_datagrid_get_column_visible

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

function n_gui_datagrid_get_column_title

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

function n_gui_datagrid_get_column_count

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

function n_gui_datagrid_get_cell

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

function n_gui_datagrid_display_to_physical

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

function n_gui_datagrid_columns_width

float n_gui_datagrid_columns_width(
    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.

Read it before a rebuild and pass it back to n_gui_datagrid_set_h_scroll to preserve the horizontal view across a clear/refill.

Total width the grid's VISIBLE columns need, including the left text padding the draw path adds — i.e. the width below which the grid grows a horizontal scrollbar. A host sizing a dialog from its own columns wants this plus style.scrollbar_size (the vertical scrollbar the grid shows once the rows overflow) plus its own margins; hardcoding a width narrower than the columns is what makes a dialog open already scrolled sideways. Returns 0 for a missing or non-datagrid widget.

function n_gui_datagrid_clear_selection

void n_gui_datagrid_clear_selection(
    N_GUI_CTX * ctx,
    int widget_id
)

clear the entire selection (no row selected)

function n_gui_datagrid_clear_rows

void n_gui_datagrid_clear_rows(
    N_GUI_CTX * ctx,
    int widget_id
)

remove all rows from a data grid (columns are kept)

function n_gui_datagrid_clear_row_colors

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)

function n_gui_datagrid_clear_row_color

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)

function n_gui_datagrid_add_row

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

function n_gui_datagrid_add_column

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

function n_gui_custom_set_mouse

void n_gui_custom_set_mouse(
    N_GUI_CTX * ctx,
    int widget_id,
    N_GUI_CUSTOM_MOUSE on_mouse,
    void * user_data
)

give a custom widget mouse input

Parameters:

  • ctx the GUI context
  • widget_id a widget made by n_gui_add_custom()
  • on_mouse the callback; NULL takes the input away again
  • user_data opaque pointer handed back to it (not owned by n_gui)
  • ctx the GUI context
  • widget_id a widget made by n_gui_add_custom()
  • on_mouse the callback; NULL takes the input away again
  • user_data opaque pointer handed back to it (not owned by n_gui)

Without it a custom widget only paints. With it the widget is handed, in its own coordinates: a press inside it (DOWN, button 1 or 2), the pointer moving while button 1 is held after that press (DRAG, reported even when the pointer has left the widget, so a drag does not stop at its edge), the release that ends it (UP), the pointer moving over it with no button held (MOVE), and the wheel over it (WHEEL). A widget under another one, or in a window that is closed or not on the event's display, is not told.

function n_gui_custom_set_destroy

void n_gui_custom_set_destroy(
    N_GUI_CTX * ctx,
    int widget_id,
    void(*)(void *user_data) destroy
)

hand a custom widget's paint user pointer to the widget

Parameters:

  • ctx the GUI context
  • widget_id a widget made by n_gui_add_custom()
  • destroy called with the paint user pointer; NULL gives up ownership
  • ctx the GUI context
  • widget_id a widget made by n_gui_add_custom()
  • destroy called with the paint user pointer; NULL gives up ownership

By default n_gui does not own the pointer given to n_gui_add_custom(). A caller building a widget of its own on a custom widget, with state on the heap, sets a destroy function here and the state then lives exactly as long as the widget: it is called once, with that pointer, when the widget is destroyed, by n_gui_destroy_ctx() or otherwise.

function n_gui_count_detached

int n_gui_count_detached(
    N_GUI_CTX * ctx
)

count the windows currently detached into native OS windows

Count the windows currently detached into native OS windows.

count the windows currently detached into native OS windows

function n_gui_combobox_set_selected

void n_gui_combobox_set_selected(
    N_GUI_CTX * ctx,
    int widget_id,
    int index
)

set the selected item index

Parameters:

  • ctx GUI context
  • widget_id id of the combobox widget
  • index index of the item to select, or -1 for none

set the selected item in a combobox widget

set the selected item index

function n_gui_combobox_set_flags

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)

Parameters:

  • ctx GUI context. Must not be NULL.
  • widget_id Combobox widget id.
  • flags Bitmask of N_GUI_COMBOBOX_* values.

Set combobox feature flags.

set combobox feature flags (bitmask of N_GUI_COMBOBOX_* values)

function n_gui_combobox_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a combobox widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a combobox widget.

function n_gui_combobox_remove_item

int n_gui_combobox_remove_item(
    N_GUI_CTX * ctx,
    int widget_id,
    int index
)

remove the item at index from a combobox.

Parameters:

  • ctx GUI context
  • widget_id id of the combobox widget
  • index index of the item to remove

Return: 0 on success, -1 on error

remove an item from a combobox widget

The selection and the open panel's highlight follow their item: one after it moves up with it, and one on the removed item is cleared (-1) rather than landing on its neighbour. Returns 0 on success, -1 on a bad index or widget.

remove the item at index from a combobox.

function n_gui_combobox_get_selected

int n_gui_combobox_get_selected(
    N_GUI_CTX * ctx,
    int widget_id
)

get the selected item index

Parameters:

  • ctx GUI context
  • widget_id id of the combobox widget

Return: index of the selected item, or -1 if none

get the selected item index in a combobox widget

get the selected item index

function n_gui_combobox_get_item_text

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)

function n_gui_combobox_get_count

int n_gui_combobox_get_count(
    N_GUI_CTX * ctx,
    int widget_id
)

get the number of items in a combobox (0 if not a combobox).

Parameters:

  • ctx GUI context
  • widget_id id of the combobox widget

Return: number of items, 0 when it is not a combobox

get the number of items in a combobox widget

With n_gui_combobox_get_item_text() a caller can walk the list it filled instead of keeping its own copy of it.

get the number of items in a combobox (0 if not a combobox).

function n_gui_combobox_clear

void n_gui_combobox_clear(
    N_GUI_CTX * ctx,
    int widget_id
)

remove all items from a combobox

Parameters:

  • ctx GUI context
  • widget_id id of the combobox widget

remove all items from a combobox widget

remove all items from a combobox

function n_gui_combobox_add_item

int n_gui_combobox_add_item(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * text
)

add an item to a combo box

function n_gui_close_window

void n_gui_close_window(
    N_GUI_CTX * ctx,
    int window_id
)

close (hide) a window

Close (hide) a window.

close (hide) a window

function n_gui_close_menus

void n_gui_close_menus(
    N_GUI_CTX * ctx
)

Put away any open combo box list or drop menu panel.

Parameters:

  • ctx the GUI context

An open list is drawn over whatever it covers and is dismissed by a press. An application that changes what is on screen without one - switching screens, closing a panel, reacting to a key - has to say so, or the list goes on painting over the thing that replaced it.

function n_gui_checkbox_set_label

void n_gui_checkbox_set_label(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * label
)

Replace the text drawn beside a checkbox.

Parameters:

  • ctx the GUI context
  • widget_id the checkbox
  • label the new text; NULL is ignored

For a pool of checkboxes shown for one thing at a time - the settings of whichever entry a list has selected - relabelled rather than destroyed and made again. Truncated to what the label holds.

function n_gui_checkbox_set_checked

void n_gui_checkbox_set_checked(
    N_GUI_CTX * ctx,
    int widget_id,
    int checked
)

set checkbox checked state

Parameters:

  • ctx GUI context
  • widget_id id of the checkbox widget
  • checked 1 to check, 0 to uncheck

set the checked state of a checkbox widget

set checkbox checked state

function n_gui_checkbox_set_bitmaps

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.

Note:

  • Bitmaps are NOT owned by N_GUI. The caller must keep them alive for the widget's lifetime and destroy them after the GUI context is destroyed.
  • Bitmaps are NOT owned by N_GUI.

Set optional bitmap overlays on a checkbox widget.

Pass NULL for any bitmap you don't want to set. set optional bitmap overlays on a checkbox widget.

function n_gui_checkbox_is_checked

int n_gui_checkbox_is_checked(
    N_GUI_CTX * ctx,
    int widget_id
)

check if checkbox is checked

Parameters:

  • ctx GUI context
  • widget_id id of the checkbox widget

Return: 1 if checked, 0 otherwise

check if a checkbox widget is checked

check if checkbox is checked

function n_gui_checkbox_get_label

const char * n_gui_checkbox_get_label(
    N_GUI_CTX * ctx,
    int widget_id
)

What a checkbox says.

Parameters:

  • ctx the GUI context
  • widget_id the checkbox

Return: The label, or NULL when the widget is not a checkbox. Borrowed, valid until the label is set again or the widget is destroyed.

function n_gui_button_set_toggled

void n_gui_button_set_toggled(
    N_GUI_CTX * ctx,
    int widget_id,
    int toggled
)

set button toggled state

Set the toggle state of a button.

set button toggled state

function n_gui_button_set_toggle_mode

void n_gui_button_set_toggle_mode(
    N_GUI_CTX * ctx,
    int widget_id,
    int toggle_mode
)

set button toggle mode

Parameters:

  • ctx the GUI context
  • widget_id id of the target button widget
  • toggle_mode 0 = momentary, 1 = toggle

Enable or disable toggle mode on a button.

set button toggle mode

function n_gui_button_set_state_bitmaps

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)

Parameters:

  • ctx the GUI context
  • widget_id id of the target button widget
  • normal bitmap for the idle state
  • hover bitmap for the hover state (NULL = normal)
  • active bitmap for the pressed / toggled-on state (NULL = normal)

Skin a button (or toggle button) with per-state bitmaps.

skin a button or toggle button with caller-owned per-state bitmaps (switches its shape to N_GUI_SHAPE_BITMAP; toggled-on renders active)

Switches the button shape to N_GUI_SHAPE_BITMAP and assigns the three state bitmaps; a toggled-on toggle button renders active persistently (the draw path already maps toggled to the ACTIVE visual state). The bitmaps stay owned by the caller, exactly like n_gui_add_button_bitmap; the label keeps drawing on top, so pass "" at creation for icon-only buttons. No-op on non-button widgets.

function n_gui_button_set_label

void n_gui_button_set_label(
    N_GUI_CTX * ctx,
    int widget_id,
    const char * label
)

replace the label text drawn on a button

Replace the label text drawn on a button.

replace the label text drawn on a button

No-op on non-button widgets or NULL label.

function n_gui_button_set_keycode_focused

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.

Parameters:

  • ctx GUI context
  • widget_id button widget id
  • keycode ALLEGRO_KEY_* constant, or 0 to unbind
  • modifiers ALLEGRO_KEYMOD_* flags ORed together, or 0 for no requirement
  • sources array of widget IDs whose focus can trigger this binding
  • source_count number of entries in sources (max N_GUI_KEY_SOURCES_MAX)

Set a focused key binding on a button.

Unlike n_gui_button_set_keycode (global), this binding triggers only when the button itself or one of the listed source widgets currently has focus. This allows e.g. ENTER in a URL textarea to trigger a Send button without interfering with ENTER in other textareas. bind a keyboard key to a button that fires only when specific widgets have focus.

function n_gui_button_set_keycode

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.

Parameters:

  • ctx GUI context
  • widget_id button widget id
  • keycode ALLEGRO_KEY_* constant, or 0 to unbind
  • modifiers ALLEGRO_KEYMOD_* flags ORed together, or 0 for no requirement

Bind a keyboard key with optional modifier requirements to a button.

When the key is pressed (with matching modifiers) and no text input widget has focus, the button's on_click callback is triggered. Pass keycode 0 to unbind. Use ALLEGRO_KEY_* constants for the keycode. When modifiers is 0, any modifier state matches (no modifier requirement). When modifiers is non-zero, only an exact match of the specified modifiers (masked by N_GUI_KEY_MOD_MASK) triggers the keybind. Example: n_gui_button_set_keycode(ctx, id, ALLEGRO_KEY_A, ALLEGRO_KEYMOD_SHIFT | ALLEGRO_KEYMOD_CTRL) bind a keyboard key with optional modifier requirements to a button.

When the key is pressed (with matching modifiers) and no text input widget has focus, the button's on_click callback is triggered (and toggle state flipped for toggle buttons). Pass keycode 0 to unbind. When modifiers is 0, any modifier state matches (no modifier requirement). When modifiers is non-zero, only an exact match triggers the keybind. Example: ALLEGRO_KEY_A with ALLEGRO_KEYMOD_SHIFT | ALLEGRO_KEYMOD_CTRL

function n_gui_button_set_glyph

void n_gui_button_set_glyph(
    N_GUI_CTX * ctx,
    int widget_id,
    int glyph
)

draw an N_GUI_GLYPH_* icon (primitives, in the button's text colour) instead of the label; N_GUI_GLYPH_NONE restores the label.

Parameters:

  • ctx the GUI context
  • widget_id the button widget
  • glyph one of the N_GUI_GLYPH_* values

Draw a glyph on a button instead of its text label.

Out-of-range values and non-button widgets are ignored

draw an N_GUI_GLYPH_* icon (primitives, in the button's text colour) instead of the label; N_GUI_GLYPH_NONE restores the label.

The glyph is built from primitives in the button's text colour, so it needs no bitmap, follows the active theme, and stays crisp at any button size. Meant for the small square buttons where a label does not fit: a row of move-up / move-down / duplicate actions, arrow toolbars, close buttons.

The label is kept, so a caller can set both and switch back with N_GUI_GLYPH_NONE. Out-of-range glyph values and non-button widgets are ignored.

function n_gui_button_is_toggled

int n_gui_button_is_toggled(
    N_GUI_CTX * ctx,
    int widget_id
)

check if button is toggled

Return: 1 if toggled on, 0 if off or not a toggle button

Check if a toggle button is currently in the "on" state.

check if button is toggled

function n_gui_button_get_label

const char * n_gui_button_get_label(
    N_GUI_CTX * ctx,
    int widget_id
)

What a button says.

Parameters:

  • ctx the GUI context
  • widget_id the button

Return: The label, or NULL when the widget is not a button. Borrowed, and valid until the label is set again or the widget is destroyed.

The counterpart n_gui_button_set_label() has never had. An application that sizes a row from its buttons' labels, or that wants to say in a log which button was pressed, had to keep its own copy of every label, which is a second place for them to go out of step with the widgets.

function n_gui_button_get_glyph

int n_gui_button_get_glyph(
    N_GUI_CTX * ctx,
    int widget_id
)

current glyph of a button, or N_GUI_GLYPH_NONE when it draws its label (also for a non-button widget)

Parameters:

  • ctx the GUI context
  • widget_id the button widget

Return: the N_GUI_GLYPH_* value, or N_GUI_GLYPH_NONE when the button draws its label or the widget is not a button

Get the glyph currently drawn on a button.

current glyph of a button, or N_GUI_GLYPH_NONE when it draws its label (also for a non-button widget)

function n_gui_apply_adaptive_resize

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.

Apply adaptive resize: reposition/resize all windows according to their policies for the new display dimensions.

Called automatically from n_gui_set_display_size() when in ADAPTIVE mode, but can also be called manually.

apply adaptive resize: reposition/resize all windows according to their policies for the new display dimensions.

Called automatically from n_gui_set_display_size() when in ADAPTIVE mode, but can also be called manually.

function n_gui_add_window_auto

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)

Return: the window id, or -1 on error

Add a window with automatic sizing (use n_gui_window_autosize after adding widgets).

add a window that sizes itself automatically to fit its widgets (call n_gui_window_autosize after adding all widgets)

function n_gui_add_window

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

Return: the window id, or -1 on error

Add a new pseudo-window to the context.

add a window to the GUI context

function n_gui_add_vslider

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(*)(int, double, void *) on_change,
    void * user_data
)

add a vertical slider (same as n_gui_add_slider but oriented vertically)

Return: widget id, or -1 on error

Add a vertical slider widget.

add a vertical slider (same as n_gui_add_slider but oriented vertically)

function n_gui_add_toggle_button

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(*)(int, void *) on_click,
    void * user_data
)

toggle button creation (returns widget id)

Parameters:

  • ctx the GUI context
  • window_id id of the parent window
  • label button label text
  • x horizontal position
  • y vertical position
  • w widget width
  • h widget height
  • shape button shape (N_GUI_SHAPE_*)
  • initial_state 0 = off, 1 = on
  • on_click callback invoked on click (or NULL)
  • user_data user data passed to on_click callback

Return: widget id, or -1 on error

Add a toggle button widget (stays clicked/unclicked on single click).

toggle button creation (returns widget id)

function n_gui_add_textarea

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(*)(int, const char *, void *) on_change,
    void * user_data
)

add a text area widget

Return: widget id, or -1 on error

Add a text area widget.

add a text area widget

function n_gui_add_syntaxview

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

Parameters:

  • ctx the GUI context
  • window_id the parent window id
  • x widget x within the window content area
  • y widget y within the window content area
  • w widget width
  • h widget height
  • mode highlighting mode (N_GUI_SYNTAX_PLAIN, _HTTP, _JSON, _XML, _YAML, _JS or _DIFF)

Return: widget id, or -1 on error

Add a read-only syntax-highlighted text view.

add a read-only syntax-highlighted text view; returns the widget id or -1

function n_gui_add_splitpane

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(*)(int, float, void *) on_change,
    void * user_data
)

add a split pane (draggable divider); returns the widget id or -1

Parameters:

  • ctx the GUI context
  • window_id the parent window id
  • x widget x within the window content area
  • y widget y within the window content area
  • w widget width
  • h widget height
  • orientation N_GUI_SPLIT_VERTICAL or N_GUI_SPLIT_HORIZONTAL
  • ratio initial divider position as a fraction (0..1)
  • on_change callback fired while the divider is dragged, or NULL
  • user_data user data passed to on_change

Return: widget id, or -1 on error

Add a split pane widget: a draggable divider between two regions.

add a split pane (draggable divider); returns the widget id or -1

function n_gui_add_slider

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(*)(int, double, void *) on_change,
    void * user_data
)

add a horizontal slider widget

Return: widget id, or -1 on error

Add a slider widget.

add a horizontal slider widget

function n_gui_add_scrollbar

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(*)(int, double, void *) on_scroll,
    void * user_data
)

add a scrollbar widget

Return: widget id, or -1 on error

Add a scrollbar widget.

add a scrollbar widget

function n_gui_add_radiolist

int n_gui_add_radiolist(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    void(*)(int, int, void *) on_select,
    void * user_data
)

add a radio list widget

Return: widget id, or -1 on error

Add a radio list widget (single selection with radio bullets).

add a radio list widget

function n_gui_add_progressbar

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

function n_gui_add_markdownview

int n_gui_add_markdownview(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    const N_GUI_MD_FONTS * fonts
)

add a read-only scrolling Markdown view.

Return: the widget id, or -1

fonts is copied into the widget but the faces themselves are borrowed: the caller owns them, must keep them alive while the widget is, and destroys them after n_gui_destroy_ctx(), exactly as it does for a bitmap. Only fonts->regular has to be set; the rest fall back towards it.

The style starts derived from the widget's theme and keeps following it until the caller asks for it with n_gui_markdownview_style().

function n_gui_add_listbox

int n_gui_add_listbox(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    int selection_mode,
    void(*)(int, int, int, void *) on_select,
    void * user_data
)

add a listbox widget

Parameters:

  • ctx the GUI context
  • window_id id of the parent window
  • x horizontal position
  • y vertical position
  • w widget width
  • h widget height
  • selection_mode N_GUI_SELECT_NONE, N_GUI_SELECT_SINGLE, or N_GUI_SELECT_MULTIPLE
  • on_select callback invoked when an item is selected (or NULL)
  • user_data user data passed to on_select callback

Return: widget id, or -1 on error

Add a listbox widget.

add a listbox widget

function n_gui_add_label_link

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(*)(int, const char *, void *) on_link_click,
    void * user_data
)

add a text label with hyperlink

Return: widget id, or -1 on error

Add a static text label with hyperlink.

add a text label with hyperlink

function n_gui_add_label

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

Return: widget id, or -1 on error

Add a static text label.

add a text label widget

function n_gui_add_image

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

Parameters:

  • ctx the GUI context
  • window_id id of the parent window
  • x horizontal position
  • y vertical position
  • w widget width
  • h widget height
  • bitmap the bitmap to display (not owned by the widget)
  • scale_mode N_GUI_IMAGE_FIT, N_GUI_IMAGE_STRETCH, or N_GUI_IMAGE_CENTER

Return: widget id, or -1 on error

Add an image display widget.

add an image widget

function n_gui_add_hexview

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

Parameters:

  • ctx the GUI context
  • window_id the parent window id
  • x widget x within the window content area
  • y widget y within the window content area
  • w widget width
  • h widget height

Return: widget id, or -1 on error

Add a read-only hexadecimal byte viewer.

add a read-only hex viewer; returns the widget id or -1

function n_gui_add_dropmenu

int n_gui_add_dropmenu(
    N_GUI_CTX * ctx,
    int window_id,
    const char * label,
    float x,
    float y,
    float w,
    float h,
    void(*)(int, void *) on_open,
    void * on_open_user_data
)

add a dropdown menu widget (button that opens a menu panel with entries)

Parameters:

  • ctx the GUI context
  • window_id id of the parent window
  • label button label text
  • x horizontal position
  • y vertical position
  • w widget width
  • h widget height
  • on_open callback invoked when the menu is opened (or NULL)
  • on_open_user_data user data passed to on_open callback

Return:

  • widget id, or -1 on error
  • widget id, or -1 on error

Add a dropdown menu widget.

add a dropdown menu widget (button that opens a menu panel with entries)

function n_gui_add_datagrid

int n_gui_add_datagrid(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    void(*)(int, int, void *) on_select,
    void * user_data
)

add a sortable data grid; returns the widget id or -1

Parameters:

  • ctx the GUI context
  • window_id the parent window id
  • x widget x within the window content area
  • y widget y within the window content area
  • w widget width
  • h widget height
  • on_select callback fired on row selection, or NULL
  • user_data user data passed to on_select

Return: widget id, or -1 on error

Add a sortable data grid widget.

add a sortable data grid; returns the widget id or -1

function n_gui_add_custom

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.

Parameters:

  • ctx the GUI context
  • window_id the window to add the widget to
  • x widget x relative to the window
  • y widget y relative to the window
  • w widget width
  • h widget height
  • draw the paint callback (NULL draws nothing but reserves the space)
  • user_data opaque pointer handed back to the callback (not owned by n_gui)

Return: the new widget id, or -1 on error

add an owner-draw custom widget; returns the widget id or -1

The widget participates in the window layout, z-order, visibility, enable/ disable dimming, and resize like any other widget, but its interior is painted by draw during n_gui_draw. This is the general extension point for rendering a chart, a canvas, a custom editor, or any host-supplied content that no stock widget covers. Input is not routed to the widget (place stock widgets around it for interaction); the callback is paint-only.

Add an owner-draw custom widget to a window.

function n_gui_add_combobox

int n_gui_add_combobox(
    N_GUI_CTX * ctx,
    int window_id,
    float x,
    float y,
    float w,
    float h,
    void(*)(int, int, void *) on_select,
    void * user_data
)

add a combo box widget

Return: widget id, or -1 on error

Add a combo box widget (dropdown selector).

add a combo box widget

function n_gui_add_checkbox

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(*)(int, int, void *) on_toggle,
    void * user_data
)

add a checkbox widget.

Return: widget id, or -1 on error

Add a checkbox widget.

A mouse press toggles it on RELEASE over the same box, like a button's click: a press that drags off it (a touch scroll starting on the box) changes nothing. Space on a focused box toggles at once.

add a checkbox widget.

function n_gui_add_button_bitmap

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(*)(int, void *) on_click,
    void * user_data
)

add a bitmap-based button widget

Return: widget id, or -1 on error

Add a bitmap-based button.

add a bitmap-based button widget

function n_gui_add_button

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(*)(int, void *) on_click,
    void * user_data
)

add a button widget

Return: widget id, or -1 on error

Add a button widget to a window.

add a button widget

Macros Documentation

define N_GUI_ZORDER_POPUP

#define N_GUI_ZORDER_POPUP 4

popup/modal dialogs: drawn above EVERYTHING including ALWAYS_ON_TOP windows.

Use for transient attention-demanding windows (confirmations, invitations, NPC dialogs, loot/reward popups, context menus). Unlike ALWAYS_ON_TOP, POPUP windows ARE raisable (n_gui_raise_window / click-to-raise) WITHIN their group, so the most recently opened/clicked popup wins among popups while none of them can ever be covered by HUD furniture.

define N_GUI_ZORDER_NORMAL

#define N_GUI_ZORDER_NORMAL 0

default z-order: window participates in normal raise/lower ordering

define N_GUI_ZORDER_FIXED

#define N_GUI_ZORDER_FIXED 3

fixed z-value: window is sorted within a dedicated group between ALWAYS_BEHIND and NORMAL windows.

The draw order of groups is: ALWAYS_BEHIND < FIXED < NORMAL < ALWAYS_ON_TOP < POPUP. Within the FIXED group, windows are ordered by z_value (lower = drawn first / behind, higher = drawn last / on top). z_value has no effect on other z-order modes. Windows with the same z_value preserve their relative list order (stable sort).

define N_GUI_ZORDER_ALWAYS_ON_TOP

#define N_GUI_ZORDER_ALWAYS_ON_TOP 1

always drawn on top of normal windows, cannot be lowered behind them

define N_GUI_ZORDER_ALWAYS_BEHIND

#define N_GUI_ZORDER_ALWAYS_BEHIND 2

always drawn behind normal windows, cannot be raised above them

define N_GUI_WIN_VSCROLL_HOVER

#define N_GUI_WIN_VSCROLL_HOVER 128

pointer is over the window's vertical auto-scrollbar

define N_GUI_WIN_VSCROLL_DRAG

#define N_GUI_WIN_VSCROLL_DRAG 16

window vertical auto-scrollbar is being dragged

define N_GUI_WIN_RESIZING

#define N_GUI_WIN_RESIZING 8

window is being resized

define N_GUI_WIN_RESIZE_SCALE

#define N_GUI_WIN_RESIZE_SCALE 2

reposition AND resize proportionally, child widgets scale too

define N_GUI_WIN_RESIZE_NONE

#define N_GUI_WIN_RESIZE_NONE 0

no adaptation: absolute position and size unchanged

define N_GUI_WIN_RESIZE_MOVE

#define N_GUI_WIN_RESIZE_MOVE 1

reposition proportionally, keep pixel size

define N_GUI_WIN_RESIZABLE

#define N_GUI_WIN_RESIZABLE 32

enable user-resizable window with a drag handle at bottom-right

define N_GUI_WIN_OPEN

#define N_GUI_WIN_OPEN 1

window is visible

define N_GUI_WIN_NO_HSCROLL

#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_MINIMISED

#define N_GUI_WIN_MINIMISED 2

window is minimised (title bar only)

define N_GUI_WIN_MAXIMISED

#define N_GUI_WIN_MAXIMISED 64

window is maximised (full display size)

define N_GUI_WIN_HSCROLL_HOVER

#define N_GUI_WIN_HSCROLL_HOVER 256

pointer is over the window's horizontal auto-scrollbar

define N_GUI_WIN_HSCROLL_DRAG

#define N_GUI_WIN_HSCROLL_DRAG 32

window horizontal auto-scrollbar is being dragged

define N_GUI_WIN_FRAMELESS

#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_FIXED_POSITION

#define N_GUI_WIN_FIXED_POSITION 64

disable window dragging (default:enable)

define N_GUI_WIN_DRAGGING

#define N_GUI_WIN_DRAGGING 4

window is being dragged

define N_GUI_WIN_BTN_MINIMIZE

#define N_GUI_WIN_BTN_MINIMIZE 256

enable minimize button on the title bar

define N_GUI_WIN_BTN_MAXIMIZE

#define N_GUI_WIN_BTN_MAXIMIZE 512

enable maximize/restore button on the title bar

define N_GUI_WIN_BTN_CLOSE

#define N_GUI_WIN_BTN_CLOSE 1024

enable close button on the title bar

define N_GUI_WIN_BTN_ALL

#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_AUTO_SCROLLBAR

#define N_GUI_WIN_AUTO_SCROLLBAR 16

enable automatic scrollbars when content exceeds window size

define N_GUI_TYPE_TEXTAREA

#define N_GUI_TYPE_TEXTAREA 3

widget type: text area

define N_GUI_TYPE_SYNTAXVIEW

#define N_GUI_TYPE_SYNTAXVIEW 14

widget type: read-only syntax-highlighted text view

define N_GUI_TYPE_SPLITPANE

#define N_GUI_TYPE_SPLITPANE 12

widget type: split pane with a draggable divider between two regions

define N_GUI_TYPE_SLIDER

#define N_GUI_TYPE_SLIDER 2

widget type: slider

define N_GUI_TYPE_SCROLLBAR

#define N_GUI_TYPE_SCROLLBAR 5

widget type: scrollbar

define N_GUI_TYPE_RADIOLIST

#define N_GUI_TYPE_RADIOLIST 7

widget type: radio list (single select radio buttons)

define N_GUI_TYPE_PROGRESSBAR

#define N_GUI_TYPE_PROGRESSBAR 16

widget type: horizontal progress bar (display only)

define N_GUI_TYPE_MARKDOWNVIEW

#define N_GUI_TYPE_MARKDOWNVIEW 18

widget type: read-only scrolling Markdown view

define N_GUI_TYPE_LISTBOX

#define N_GUI_TYPE_LISTBOX 6

widget type: listbox (selectable list)

define N_GUI_TYPE_LABEL

#define N_GUI_TYPE_LABEL 10

widget type: static text label (with optional hyperlink)

define N_GUI_TYPE_IMAGE

#define N_GUI_TYPE_IMAGE 9

widget type: image display

define N_GUI_TYPE_HEXVIEW

#define N_GUI_TYPE_HEXVIEW 13

widget type: read-only hexadecimal byte viewer

define N_GUI_TYPE_DROPMENU

#define N_GUI_TYPE_DROPMENU 11

widget type: dropdown menu with static and dynamic entries

define N_GUI_TYPE_DATAGRID

#define N_GUI_TYPE_DATAGRID 15

widget type: sortable column data grid

define N_GUI_TYPE_CUSTOM

#define N_GUI_TYPE_CUSTOM 17

widget type: owner-draw custom widget (rendering delegated to a callback)

define N_GUI_TYPE_COMBOBOX

#define N_GUI_TYPE_COMBOBOX 8

widget type: combo box (dropdown)

define N_GUI_TYPE_CHECKBOX

#define N_GUI_TYPE_CHECKBOX 4

widget type: checkbox

define N_GUI_TYPE_BUTTON

#define N_GUI_TYPE_BUTTON 1

widget type: button

define N_GUI_TRUNCATE_START

#define N_GUI_TRUNCATE_START 1

text too wide for its box is cut at the start, "...ong sentence": for anything whose end is what tells it apart

define N_GUI_TRUNCATE_PATH

#define N_GUI_TRUNCATE_PATH 2

a path too wide for its box loses whole leading components, ".../photos/IMG_0001.CR3", and the file name only if it is wider than the box on its own; both '/' and '' separate components

define N_GUI_TRUNCATE_END

#define N_GUI_TRUNCATE_END 0

text too wide for its box is cut at the end, "Long senten...": the default, right for a sentence

define N_GUI_TREE_STATE_MAX

#define N_GUI_TREE_STATE_MAX 512

maximum number of expanded paths remembered by an N_GUI_TREE_STATE

define N_GUI_TREE_PATH_SEP

#define N_GUI_TREE_PATH_SEP '\x1f'

separator joining the labels of a node path.

A unit separator cannot appear in a label, so a path can never be ambiguous

define N_GUI_TREE_PATH_MAX

#define N_GUI_TREE_PATH_MAX 1024

maximum length of a node path (labels from the root, joined)

define N_GUI_TREE_MAX

#define N_GUI_TREE_MAX 2048

maximum number of nodes in a tree view

define N_GUI_TEXT_MAX

#define N_GUI_TEXT_MAX 4096

maximum length for textarea content

define N_GUI_TB_BTN_NONE

#define N_GUI_TB_BTN_NONE 0

no titlebar button

define N_GUI_TB_BTN_MINIMIZE

#define N_GUI_TB_BTN_MINIMIZE 1

minimize titlebar button

define N_GUI_TB_BTN_MAXIMIZE

#define N_GUI_TB_BTN_MAXIMIZE 2

maximize/restore titlebar button

define N_GUI_TB_BTN_CLOSE

#define N_GUI_TB_BTN_CLOSE 3

close titlebar button

define N_GUI_TAB_MAX

#define N_GUI_TAB_MAX 16

maximum number of tabs in a single tab panel

define N_GUI_SYNTAX_YAML

#define N_GUI_SYNTAX_YAML 4

syntax view: YAML highlighting (keys, quoted values, list markers, comments)

define N_GUI_SYNTAX_XML

#define N_GUI_SYNTAX_XML 3

syntax view: XML/HTML highlighting (tags, attributes, quoted values, comments)

define N_GUI_SYNTAX_PLAIN

#define N_GUI_SYNTAX_PLAIN 0

syntax view: no highlighting

define N_GUI_SYNTAX_JSON

#define N_GUI_SYNTAX_JSON 2

syntax view: JSON highlighting (keys, strings, numbers, punctuation)

define N_GUI_SYNTAX_JS

#define N_GUI_SYNTAX_JS 5

syntax view: JavaScript highlighting (keywords, strings, numbers, comments)

define N_GUI_SYNTAX_HTTP

#define N_GUI_SYNTAX_HTTP 1

syntax view: HTTP message highlighting (request/status line and headers)

define N_GUI_SYNTAX_DIFF

#define N_GUI_SYNTAX_DIFF 6

syntax view: unified diff highlighting (added, removed and hunk header lines, as produced by n_diff_to_unified).

Added and removed are semantic the way a status colour is, so they are fixed instead of theme derived and read the same on a light or a dark background.

define N_GUI_SUGGEST_VISIBLE

#define N_GUI_SUGGEST_VISIBLE 8

most completions a suggestion panel shows at once.

The rest are reached with the arrow keys or the wheel, which scroll the window.

define N_GUI_SUGGEST_SEP_MAX

#define N_GUI_SUGGEST_SEP_MAX 8

longest separator set a suggestion-aware textarea takes, including the terminator

define N_GUI_SUGGEST_MAX

#define N_GUI_SUGGEST_MAX 64

most completions a textarea's suggestion list keeps for one prefix.

Past this the list is not a help, it is a second problem: the point of completion is to offer the few things that match, and a prefix matching more than this has not narrowed anything yet.

define N_GUI_STATE_SCROLLBAR_DRAG

#define N_GUI_STATE_SCROLLBAR_DRAG 8

widget scrollbar is being dragged

define N_GUI_STATE_IDLE

#define N_GUI_STATE_IDLE 0

widget is idle / normal state

define N_GUI_STATE_HOVER

#define N_GUI_STATE_HOVER 1

mouse is hovering the widget

define N_GUI_STATE_FOCUSED

#define N_GUI_STATE_FOCUSED 4

widget has keyboard focus

define N_GUI_STATE_ACTIVE

#define N_GUI_STATE_ACTIVE 2

widget is being pressed / dragged

define N_GUI_SPLIT_VERTICAL

#define N_GUI_SPLIT_VERTICAL 0

split pane: vertical divider, regions are left and right

define N_GUI_SPLIT_HORIZONTAL

#define N_GUI_SPLIT_HORIZONTAL 1

split pane: horizontal divider, regions are top and bottom

define N_GUI_SLIDER_VALUE

#define N_GUI_SLIDER_VALUE 0

slider uses raw start/end values

define N_GUI_SLIDER_V

#define N_GUI_SLIDER_V 1

vertical slider

define N_GUI_SLIDER_PERCENT

#define N_GUI_SLIDER_PERCENT 1

slider uses 0-100 percentage

define N_GUI_SLIDER_H

#define N_GUI_SLIDER_H 0

horizontal slider (default)

define N_GUI_SHAPE_ROUNDED

#define N_GUI_SHAPE_ROUNDED 1

rounded rectangle shape

define N_GUI_SHAPE_RECT

#define N_GUI_SHAPE_RECT 0

rectangle shape (default)

define N_GUI_SHAPE_BITMAP

#define N_GUI_SHAPE_BITMAP 2

bitmap-based rendering

define N_GUI_SELECT_SINGLE

#define N_GUI_SELECT_SINGLE 1

single item selection

define N_GUI_SELECT_NONE

#define N_GUI_SELECT_NONE 0

no selection allowed (display only)

define N_GUI_SELECT_MULTIPLE

#define N_GUI_SELECT_MULTIPLE 2

multiple item selection

define N_GUI_SECTION_WIDGETS_MAX

#define N_GUI_SECTION_WIDGETS_MAX 96

maximum number of member widgets per section.

48 until a panel built from a plugin's description outgrew it: six colour rows of five widgets, eight sliders of two and the rest came to 52, and the last four were dropped without a word, laid out at the top of the window.

define N_GUI_SECTIONLIST_MAX

#define N_GUI_SECTIONLIST_MAX 16

maximum number of foldable sections in a section list

define N_GUI_SCROLLBAR_V

#define N_GUI_SCROLLBAR_V 1

vertical scrollbar

define N_GUI_SCROLLBAR_H

#define N_GUI_SCROLLBAR_H 0

horizontal scrollbar

define N_GUI_RESIZE_VIRTUAL

#define N_GUI_RESIZE_VIRTUAL 0

fixed virtual canvas with uniform scaling (default/existing behavior)

define N_GUI_RESIZE_ADAPTIVE

#define N_GUI_RESIZE_ADAPTIVE 1

virtual size tracks display; windows adapt per their resize_policy

define N_GUI_PERSIST_MAX_COLS

#define N_GUI_PERSIST_MAX_COLS 64

Maximum datagrid columns whose layout is persisted per widget.

define N_GUI_MOUSE_WHEEL

#define N_GUI_MOUSE_WHEEL 5

custom widget mouse event: the wheel turned over it

define N_GUI_MOUSE_UP

#define N_GUI_MOUSE_UP 2

custom widget mouse event: the release of a button 1 press that began in it, wherever the pointer is now

define N_GUI_MOUSE_MOVE

#define N_GUI_MOUSE_MOVE 3

custom widget mouse event: the pointer moved over it with no button held

define N_GUI_MOUSE_DRAG

#define N_GUI_MOUSE_DRAG 4

custom widget mouse event: the pointer moved with button 1 held after a press in it; reported outside the widget too, as a slider's drag is

define N_GUI_MOUSE_DOWN

#define N_GUI_MOUSE_DOWN 1

custom widget mouse event: a press inside it, button 1 or 2

define N_GUI_KV_MAX

#define N_GUI_KV_MAX 128

maximum number of rows in a KV table

define N_GUI_KEY_SOURCES_MAX

#define N_GUI_KEY_SOURCES_MAX 8

maximum number of source widgets for a focused key binding

define N_GUI_KEY_MOD_MASK

#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_IMAGE_STRETCH

#define N_GUI_IMAGE_STRETCH 1

stretch to fill bounds

define N_GUI_IMAGE_FIT

#define N_GUI_IMAGE_FIT 0

scale to fit within bounds, keep aspect ratio

define N_GUI_IMAGE_CENTER

#define N_GUI_IMAGE_CENTER 2

draw at original size, centered

define N_GUI_ID_MAX

#define N_GUI_ID_MAX 128

maximum length for widget id/name strings

define N_GUI_GLYPH_PLUS

#define N_GUI_GLYPH_PLUS 5

plus sign

define N_GUI_GLYPH_NONE

#define N_GUI_GLYPH_NONE 0

no glyph: the button draws its text label (default)

define N_GUI_GLYPH_MINUS

#define N_GUI_GLYPH_MINUS 6

minus sign

define N_GUI_GLYPH_CROSS

#define N_GUI_GLYPH_CROSS 7

diagonal cross

define N_GUI_GLYPH_COUNT

#define N_GUI_GLYPH_COUNT 9

number of defined glyphs, for range checks

define N_GUI_GLYPH_COPY

#define N_GUI_GLYPH_COPY 8

two offset sheets: duplicate / copy

define N_GUI_GLYPH_ARROW_UP

#define N_GUI_GLYPH_ARROW_UP 1

filled triangle pointing up

define N_GUI_GLYPH_ARROW_RIGHT

#define N_GUI_GLYPH_ARROW_RIGHT 4

filled triangle pointing right

define N_GUI_GLYPH_ARROW_LEFT

#define N_GUI_GLYPH_ARROW_LEFT 3

filled triangle pointing left

define N_GUI_GLYPH_ARROW_DOWN

#define N_GUI_GLYPH_ARROW_DOWN 2

filled triangle pointing down

define N_GUI_GLOBAL_SCROLL_SLACK

#define N_GUI_GLOBAL_SCROLL_SLACK 0.5f

how far, in pixels, the open windows may reach past the display before the global scrollbars appear: under half a pixel is a rounding error of a layout computed in floats, and hides nothing

define N_GUI_DROP_INTO

#define N_GUI_DROP_INTO 1

define N_GUI_DROP_BEFORE

#define N_GUI_DROP_BEFORE 0

drop position relative to a tree row (drag-and-drop)

define N_GUI_DROP_AFTER

#define N_GUI_DROP_AFTER 2

define N_GUI_DROPMENU_EXPAND_UP

#define N_GUI_DROPMENU_EXPAND_UP 1

dropdown panel opens upward (above the button) instead of downward.

Auto-flip fallback (pick direction based on available space) also kicks in whenever the panel doesn't fit below and does fit above.

define N_GUI_DETACH_SCALE_CONTENT

#define N_GUI_DETACH_SCALE_CONTENT 2

scale the window's widgets when the native window is resized by the user.

Requires N_GUI_DETACH_RESIZABLE and normalized widget coords, which n_gui_window_detach captures at detach time. Without it the widgets keep their pixel layout and the extra room is just empty space (or scrolled, when the window carries N_GUI_WIN_AUTO_SCROLLBAR).

define N_GUI_DETACH_RESIZABLE

#define N_GUI_DETACH_RESIZABLE 1

the native window can be resized by the user through the OS window manager

define N_GUI_DETACH_OWN_CHROME

#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.

Dragging the title bar moves the OS window, the resize grip resizes it, and the minimise / maximise / close buttons act on it.

Without this flag (the default) the OS supplies the title bar and all of the above is the window manager's job. Frameless windows are the less well trodden path on some window managers, which is why this is opt-in.

define N_GUI_DETACH_NONE

#define N_GUI_DETACH_NONE 0

no option

define N_GUI_COMBOBOX_EXPAND_UP

#define N_GUI_COMBOBOX_EXPAND_UP 2

dropdown panel opens upward (above the widget) instead of downward.

Useful for bottom-anchored comboboxes where the default downward panel would render off-screen. Without the flag, an auto-flip fallback still kicks in whenever the panel doesn't fit below and does fit above.

define N_GUI_COMBOBOX_AUTO_WIDTH

#define N_GUI_COMBOBOX_AUTO_WIDTH 1

dropdown panel expands to fit the longest item text

define N_GUI_AUTOFIT_WH

#define N_GUI_AUTOFIT_WH 3

auto-adjust both width and height (convenience: W|H)

define N_GUI_AUTOFIT_W

#define N_GUI_AUTOFIT_W 1

auto-adjust window width to content

define N_GUI_AUTOFIT_H

#define N_GUI_AUTOFIT_H 2

auto-adjust window height to content

define N_GUI_AUTOFIT_EXPAND_UP

#define N_GUI_AUTOFIT_EXPAND_UP 8

expand upward instead of downward when adjusting height

define N_GUI_AUTOFIT_EXPAND_LEFT

#define N_GUI_AUTOFIT_EXPAND_LEFT 4

expand leftward instead of rightward when adjusting width

define N_GUI_AUTOFIT_CENTER

#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_ALIGN_RIGHT

#define N_GUI_ALIGN_RIGHT 2

right aligned text

define N_GUI_ALIGN_LEFT

#define N_GUI_ALIGN_LEFT 0

left aligned text

define N_GUI_ALIGN_JUSTIFIED

#define N_GUI_ALIGN_JUSTIFIED 3

justified text (spread words to fill width)

define N_GUI_ALIGN_CENTER

#define N_GUI_ALIGN_CENTER 1

center aligned text

Home

Modules