6 Struct N_GUI_CTX
gullradriel edited this page 2026-10-12 07:59:13 +02:00
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.

N_GUI_CTX

Module: GUI: allegro5 widget system with pseudo-windows

The top-level GUI context that holds all windows.

#include "n_gui.h"

Public Attributes

Name
LIST * windows
ordered list of N_GUI_WINDOW* (back to front)
HASH_TABLE * widgets_by_id
hash table for fast widget lookup by id
float virtual_w
virtual canvas width (0 = disabled / identity transform)
float virtual_h
virtual canvas height (0 = disabled / identity transform)
int tooltip_widget_id
widget the pointer is resting on for tooltip purposes (-1 = none)
double tooltip_armed_at
time the tooltip hover was (re)armed, from al_get_time()
int tooltip_anchor_y
pointer y when the tooltip was last armed
int tooltip_anchor_x
pointer x when the tooltip was last armed (movement re-arms)
N_GUI_STYLE style
configurable style (sizes, colours, paddings)
int selected_syntaxview_id
id of the syntax-view widget with the most recent text selection, or -1
int selected_label_id
id of the label widget with the most recent text selection, or -1
int scrollbar_drag_widget_id
id of the widget whose scrollbar is being dragged, or -1
int resize_mode
context resize mode: N_GUI_RESIZE_VIRTUAL or N_GUI_RESIZE_ADAPTIVE
float ref_display_w
reference display width at the time normalized values were last captured
float ref_display_h
reference display height at the time normalized values were last captured
int prev_over_win
whether the pointer was over a window on the previous motion event, so a motion that leaves the GUI still forces one redraw to clear hover state.
int pending_widgets_count
number of valid entries in pending_widgets
N_GUI_PENDING_WIDGET * pending_widgets
saved widget state for keyed widgets that did NOT exist when the layout was loaded; n_gui_widget_set_persist_key applies the first matching entry (by owning window title + key) to the widget being keyed.
int pending_layout_count
number of valid entries in pending_layout
N_GUI_PENDING_GEOM * pending_layout
layout entries for windows that did NOT exist when the saved layout was loaded (lazily-created panels).
ALLEGRO_DISPLAY * pass_display
display the pass currently being processed or drawn belongs to: NULL for the host's main display (and for the headless case), or a detached window's native display.
int open_suggest_id
id of the textarea whose completion panel is currently open, or -1.
int open_dropmenu_id
id of the dropdown menu whose panel is currently open, or -1
int open_combobox_id
id of the combobox whose dropdown is currently open, or -1
int next_window_id
next window id to assign
int next_widget_id
next widget id to assign
int mouse_y
mouse state tracking
int mouse_x
mouse state tracking
int mouse_b1_prev
previous mouse button 1 state
int mouse_b1
mouse button 1 state
int held_modifier_keys
the modifier keys held down, one bit per key (left and right apart, so letting go of one Ctrl while the other is held keeps Ctrl down), from the KEY_DOWN and KEY_UP events n_gui_process_event has seen.
float gui_scale
computed uniform scale factor for virtual canvas
float gui_offset_y
vertical letterbox offset for virtual canvas
float gui_offset_x
horizontal letterbox offset for virtual canvas
float gui_bounds_w
total bounding box width of all windows (computed internally)
float gui_bounds_h
total bounding box height of all windows (computed internally)
int global_vscroll_drag
1 if global scrollbar vertical thumb is being dragged
float global_scroll_y
global vertical scroll offset (when GUI exceeds display)
float global_scroll_x
global horizontal scroll offset (when GUI exceeds display)
int global_hscroll_drag
1 if global scrollbar horizontal thumb is being dragged
int focused_widget_id
id of the widget that currently has focus, or -1
ALLEGRO_EVENT_QUEUE * event_queue
event queue the context registers native window event sources into (set via n_gui_set_event_queue).
float dpi_scale
DPI scale factor (1.0 = normal, 1.25 = 125%, 2.0 = HiDPI, etc.).
int double_clicked_widget_id
widget the press just processed double clicked, or -1.
double double_click_time
how long after a press a second one still counts as a double click, in seconds.
int double_click_radius
how far the pointer may move between the two presses and still count, in pixels.
float display_w
display/viewport width (set via n_gui_set_display_size)
int display_size_warned
non-zero once the fallback above has logged that it is in use
int display_size_set
non-zero once n_gui_set_display_size() has been called.
float display_h
display/viewport height
ALLEGRO_DISPLAY * display
display pointer for clipboard operations (set via n_gui_set_display)
int dirty
non-zero when the GUI's appearance may have changed since the last n_gui_draw.
N_GUI_THEME default_theme
default theme (applied to new widgets/windows)
N_GUI_THEME default_tb_close_theme
default theme for titlebar close button
N_GUI_THEME default_tb_btn_theme
default theme for titlebar minimize/maximize buttons
ALLEGRO_FONT * default_font
default font.
int cursor_want_shape
the cursor the application asked for with n_gui_set_cursor(), shown wherever the GUI has no cursor of its own to show: a system cursor (an ALLEGRO_SYSTEM_MOUSE_CURSOR_* value) ...
ALLEGRO_MOUSE_CURSOR * cursor_want_custom
... or a custom one, borrowed, which wins over the shape when set
int cursor_shape
system mouse cursor currently applied to the display (an ALLEGRO_SYSTEM_MOUSE_CURSOR_* value), so a horizontal-resize cursor is set over a datagrid column border and reset elsewhere without redundant calls
ALLEGRO_MOUSE_CURSOR * cursor_custom
the custom cursor currently applied to the display, or NULL when a system cursor is (cursor_shape then says which)
int click_y
pointer y at that press
int click_x
pointer x at that press
int click_widget_id
widget the previous primary press landed on, for double click detection (-1 = none yet)
double click_time
time of that press, from al_get_time()
double anim_until
deadline (al_get_time seconds) until which a transient animation is in progress (button key-press flash, tooltip reveal): n_gui_needs_redraw keeps returning non-zero until then.
ALLEGRO_DISPLAY * active_display
display that last received input, used to pick the display for clipboard and mouse-cursor calls.

Public Attributes Documentation

variable windows

LIST * windows;

ordered list of N_GUI_WINDOW* (back to front)

variable widgets_by_id

HASH_TABLE * widgets_by_id;

hash table for fast widget lookup by id

variable virtual_w

float virtual_w;

virtual canvas width (0 = disabled / identity transform)

variable virtual_h

float virtual_h;

virtual canvas height (0 = disabled / identity transform)

variable tooltip_widget_id

int tooltip_widget_id;

widget the pointer is resting on for tooltip purposes (-1 = none)

variable tooltip_armed_at

double tooltip_armed_at;

time the tooltip hover was (re)armed, from al_get_time()

variable tooltip_anchor_y

int tooltip_anchor_y;

pointer y when the tooltip was last armed

variable tooltip_anchor_x

int tooltip_anchor_x;

pointer x when the tooltip was last armed (movement re-arms)

variable style

N_GUI_STYLE style;

configurable style (sizes, colours, paddings)

variable selected_syntaxview_id

int selected_syntaxview_id;

id of the syntax-view widget with the most recent text selection, or -1

variable selected_label_id

int selected_label_id;

id of the label widget with the most recent text selection, or -1

variable scrollbar_drag_widget_id

int scrollbar_drag_widget_id;

id of the widget whose scrollbar is being dragged, or -1

variable resize_mode

int resize_mode;

context resize mode: N_GUI_RESIZE_VIRTUAL or N_GUI_RESIZE_ADAPTIVE

variable ref_display_w

float ref_display_w;

reference display width at the time normalized values were last captured

variable ref_display_h

float ref_display_h;

reference display height at the time normalized values were last captured

variable prev_over_win

int prev_over_win;

whether the pointer was over a window on the previous motion event, so a motion that leaves the GUI still forces one redraw to clear hover state.

variable pending_widgets_count

int pending_widgets_count;

number of valid entries in pending_widgets

variable pending_widgets

N_GUI_PENDING_WIDGET * pending_widgets;

saved widget state for keyed widgets that did NOT exist when the layout was loaded; n_gui_widget_set_persist_key applies the first matching entry (by owning window title + key) to the widget being keyed.

Owned by the ctx; freed in n_gui_destroy_ctx.

variable pending_layout_count

int pending_layout_count;

number of valid entries in pending_layout

variable pending_layout

N_GUI_PENDING_GEOM * pending_layout;

layout entries for windows that did NOT exist when the saved layout was loaded (lazily-created panels).

n_gui_add_window applies the saved (x,y) to the first window created later with a matching title, giving cross-session position restore without eager-creating every window. Owned by the ctx; freed in n_gui_destroy_ctx.

variable pass_display

ALLEGRO_DISPLAY * pass_display;

display the pass currently being processed or drawn belongs to: NULL for the host's main display (and for the headless case), or a detached window's native display.

Internal, maintained by n_gui_process_event and n_gui_draw / n_gui_draw_detached. A window takes part in the pass when its N_GUI_WINDOW::native equals this, so with no detached window every pass is the main one and behaviour is unchanged.

variable open_suggest_id

int open_suggest_id;

id of the textarea whose completion panel is currently open, or -1.

One at a time, like the two above: the panel floats over everything and two of them would fight for the same keys.

variable open_dropmenu_id

int open_dropmenu_id;

id of the dropdown menu whose panel is currently open, or -1

variable open_combobox_id

int open_combobox_id;

id of the combobox whose dropdown is currently open, or -1

variable next_window_id

int next_window_id;

next window id to assign

variable next_widget_id

int next_widget_id;

next widget id to assign

variable mouse_y

int mouse_y;

mouse state tracking

variable mouse_x

int mouse_x;

mouse state tracking

variable mouse_b1_prev

int mouse_b1_prev;

previous mouse button 1 state

variable mouse_b1

int mouse_b1;

mouse button 1 state

variable held_modifier_keys

int held_modifier_keys;

the modifier keys held down, one bit per key (left and right apart, so letting go of one Ctrl while the other is held keeps Ctrl down), from the KEY_DOWN and KEY_UP events n_gui_process_event has seen.

Read through n_gui_get_key_modifiers().

variable gui_scale

float gui_scale;

computed uniform scale factor for virtual canvas

variable gui_offset_y

float gui_offset_y;

vertical letterbox offset for virtual canvas

variable gui_offset_x

float gui_offset_x;

horizontal letterbox offset for virtual canvas

variable gui_bounds_w

float gui_bounds_w;

total bounding box width of all windows (computed internally)

variable gui_bounds_h

float gui_bounds_h;

total bounding box height of all windows (computed internally)

variable global_vscroll_drag

int global_vscroll_drag;

1 if global scrollbar vertical thumb is being dragged

variable global_scroll_y

float global_scroll_y;

global vertical scroll offset (when GUI exceeds display)

variable global_scroll_x

float global_scroll_x;

global horizontal scroll offset (when GUI exceeds display)

variable global_hscroll_drag

int global_hscroll_drag;

1 if global scrollbar horizontal thumb is being dragged

variable focused_widget_id

int focused_widget_id;

id of the widget that currently has focus, or -1

variable event_queue

ALLEGRO_EVENT_QUEUE * event_queue;

event queue the context registers native window event sources into (set via n_gui_set_event_queue).

Required by n_gui_window_detach.

variable dpi_scale

float dpi_scale;

DPI scale factor (1.0 = normal, 1.25 = 125%, 2.0 = HiDPI, etc.).

variable double_clicked_widget_id

int double_clicked_widget_id;

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

Valid until the next event is processed. Read with n_gui_double_clicked_widget().

variable double_click_time

double double_click_time;

how long after a press a second one still counts as a double click, in seconds.

n_gui_set_double_click_time() sets it.

variable double_click_radius

int double_click_radius;

how far the pointer may move between the two presses and still count, in pixels.

Without this a drag that happens to pause reads as a double click. n_gui_set_double_click_radius() sets it.

variable display_w

float display_w;

display/viewport width (set via n_gui_set_display_size)

variable display_size_warned

int display_size_warned;

non-zero once the fallback above has logged that it is in use

variable display_size_set

int display_size_set;

non-zero once n_gui_set_display_size() has been called.

Until then n_gui_draw() takes the display size from its target bitmap on every pass, so a caller who never sets it still gets tooltips, dropdowns and window clamps sized to the screen rather than to zero

variable display_h

float display_h;

display/viewport height

variable display

ALLEGRO_DISPLAY * display;

display pointer for clipboard operations (set via n_gui_set_display)

variable dirty

int dirty;

non-zero when the GUI's appearance may have changed since the last n_gui_draw.

Set by widget/window creation, by input events that can change state, and by n_gui_mark_dirty; cleared at the end of n_gui_draw. Read via n_gui_needs_redraw so an event-driven host can skip drawing an unchanged, non-animating GUI. Initialised to 1 so the first frame draws.

variable default_theme

N_GUI_THEME default_theme;

default theme (applied to new widgets/windows)

variable default_tb_close_theme

N_GUI_THEME default_tb_close_theme;

default theme for titlebar close button

variable default_tb_btn_theme

N_GUI_THEME default_tb_btn_theme;

default theme for titlebar minimize/maximize buttons

variable default_font

ALLEGRO_FONT * default_font;

default font.

Widgets resolve their font at DRAW time (wgt->font ? wgt->font : ctx->default_font), so this can be swapped after widgets exist – see n_gui_set_default_font().

variable cursor_want_shape

int cursor_want_shape;

the cursor the application asked for with n_gui_set_cursor(), shown wherever the GUI has no cursor of its own to show: a system cursor (an ALLEGRO_SYSTEM_MOUSE_CURSOR_* value) ...

variable cursor_want_custom

ALLEGRO_MOUSE_CURSOR * cursor_want_custom;

... or a custom one, borrowed, which wins over the shape when set

variable cursor_shape

int cursor_shape;

system mouse cursor currently applied to the display (an ALLEGRO_SYSTEM_MOUSE_CURSOR_* value), so a horizontal-resize cursor is set over a datagrid column border and reset elsewhere without redundant calls

variable cursor_custom

ALLEGRO_MOUSE_CURSOR * cursor_custom;

the custom cursor currently applied to the display, or NULL when a system cursor is (cursor_shape then says which)

variable click_y

int click_y;

pointer y at that press

variable click_x

int click_x;

pointer x at that press

variable click_widget_id

int click_widget_id;

widget the previous primary press landed on, for double click detection (-1 = none yet)

variable click_time

double click_time;

time of that press, from al_get_time()

variable anim_until

double anim_until;

deadline (al_get_time seconds) until which a transient animation is in progress (button key-press flash, tooltip reveal): n_gui_needs_redraw keeps returning non-zero until then.

0 when no timed animation is pending.

variable active_display

ALLEGRO_DISPLAY * active_display;

display that last received input, used to pick the display for clipboard and mouse-cursor calls.

NULL falls back to N_GUI_CTX::display.