sleela_ui_layout.h
user-interface/include/sleela_ui_layout.h · 235 line(s) · c
#ifndef SLEELA_UI_LAYOUT_H
#define SLEELA_UI_LAYOUT_H
/* =============================================================================
* SleelaUI(TM) Layout & Flow manager -- named items, named groups, standardized
* units, and several flow solutions.
*
* This layer sits above the widget tree (sleela_ui.h). It treats a UI as an
* ORTHOGONAL CONFLATION of two independent concerns:
*
* * UNIT PARTS -- what each item measures: a size/mass expressed in a single
* standardized unit vocabulary that spans US customary, Eurasian metric, and
* device pixels.
* * ORGANIZATIONS -- how those parts are arranged: items are collected into
* named GROUPS, and a group is placed by a chosen FLOW (several solutions,
* below). The same item can be re-measured without changing its
* organization, and re-organized without changing its measure.
*
* Everything is NAMEABLE: items have names, groups have names, and you adjust a
* single named item, a whole named group, or an N-ARY selection (any subset of
* a group of some size) in one call.
*
* Named ergonomics ("the ergonomics of publics shall be Named"): alignment and
* packing have public, human names -- notably `MEDIUM` means CENTER, and
* `CENTRAL` means weight/mass (a centre-of-mass gravity packing). A set of named
* ergonomic presets (reading, gallery, dashboard, console, portrait, ...) tunes
* spacing, flow, and alignment for a common public use at once.
*
* Max Rupplin -- MEARVK LLC -- 2026
* ===========================================================================*/
#include "sleela_ui.h"
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* --------------------------------------------------------------------------
* Standardized units. One vocabulary across US customary, Eurasian metric, and
* device pixels, plus relative units. A measurement is a (value, unit) pair; it
* resolves to device pixels through a DPI and, for relative units, a reference
* length (the available extent along the axis).
* ------------------------------------------------------------------------- */
typedef enum {
/* device */
SLUI_UNIT_PX = 0, /* device pixels */
/* Eurasian / metric (SI) */
SLUI_UNIT_MM = 1, /* millimetre */
SLUI_UNIT_CM = 2, /* centimetre = 10 mm */
SLUI_UNIT_M = 3, /* metre = 1000 mm */
/* US customary */
SLUI_UNIT_IN = 4, /* inch = 25.4 mm */
SLUI_UNIT_FT = 5, /* foot = 12 in */
SLUI_UNIT_PT = 6, /* typographic point = 1/72 in */
SLUI_UNIT_PICA = 7, /* pica = 12 pt = 1/6 in */
/* relative */
SLUI_UNIT_PCT = 8, /* percent of the reference extent */
SLUI_UNIT_FR = 9, /* flexible fraction (a share of leftover space) */
SLUI_UNIT_EM = 10 /* multiples of the base font size (em) */
} SLUIUnitKind;
typedef struct {
double value;
SLUIUnitKind unit;
} SLUIMeasure;
/* Builders -- one per unit, so a call site reads like a measurement. */
SLUIMeasure slui_px(double v);
SLUIMeasure slui_mm_u(double v); /* _u to avoid clashing with mood's slui_mm */
SLUIMeasure slui_cm(double v);
SLUIMeasure slui_m(double v);
SLUIMeasure slui_in(double v);
SLUIMeasure slui_ft(double v);
SLUIMeasure slui_ptm(double v); /* points as a measure */
SLUIMeasure slui_pica(double v);
SLUIMeasure slui_pct(double v);
SLUIMeasure slui_fr(double v); /* flexible fraction / weight share */
SLUIMeasure slui_em(double v);
/* Resolve a measure to device pixels. `dpi` (default 96) converts physical
* units; `reference_px` is the axis extent for PCT; `em_px` is the base font
* size in px for EM. FR resolves to 0 here (fractions are distributed by the
* flow from leftover space, not fixed) -- query it with slui_measure_is_flex. */
double slui_measure_to_px(SLUIMeasure m, double dpi, double reference_px,
double em_px);
/* True if the measure is a flexible fraction (FR) the flow should distribute. */
int slui_measure_is_flex(SLUIMeasure m);
/* The fraction weight of an FR measure (its `value`), or 0 for non-FR. */
double slui_measure_flex(SLUIMeasure m);
/* Parse a string like "12px", "3mm", "0.5in", "2fr", "50%", "1.5em" into a
* measure. Returns 1 on success (writes *out), 0 on a parse error. Accepts US
* ("in","ft","pt","pc"), metric ("mm","cm","m"), and relative units. */
int slui_measure_parse(const char *text, SLUIMeasure *out);
/* --------------------------------------------------------------------------
* Named ergonomic alignment. MEDIUM is the public name for CENTER; the other
* names are the public ergonomics of placement.
* ------------------------------------------------------------------------- */
typedef enum {
SLUI_PLACE_START = 0, /* leading edge */
SLUI_PLACE_MEDIUM = 1, /* CENTER -- "medium implies center" */
SLUI_PLACE_END = 2, /* trailing edge */
SLUI_PLACE_FILL = 3, /* stretch to fill */
SLUI_PLACE_CENTRAL = 4 /* weight/mass -- pack toward the centre of mass */
} SLUIPlacement;
/* --------------------------------------------------------------------------
* Flow solutions -- several ways a group organizes its items.
* ------------------------------------------------------------------------- */
typedef enum {
SLUI_FLOW_STACK = 0, /* a single row/column (the box model) */
SLUI_FLOW_WRAP = 1, /* a flow that wraps to new lines when full */
SLUI_FLOW_GRID = 2, /* a fixed-column grid */
SLUI_FLOW_DOCK = 3, /* items docked to edges, the rest fills centre */
SLUI_FLOW_CENTRAL = 4 /* weight/mass packing -- heavier items pull in */
} SLUIFlowKind;
typedef enum {
SLUI_AXIS_HORIZONTAL = 0,
SLUI_AXIS_VERTICAL = 1
} SLUIAxis;
/* --------------------------------------------------------------------------
* The layout manager, its groups, and its items.
* ------------------------------------------------------------------------- */
typedef struct SLUILayout SLUILayout;
SLUILayout *slui_layout_create(void);
void slui_layout_destroy(SLUILayout *layout);
/* The DPI and base em used to resolve physical/relative units. */
void slui_layout_set_dpi(SLUILayout *layout, double dpi);
void slui_layout_set_em(SLUILayout *layout, double em_px);
/* ---- groups (named) ----------------------------------------------------- */
/* Create a named group with a flow and axis. Returns a group id (>=0), or
* SLUI_ERR_* . A duplicate name returns the existing group's id. */
int slui_layout_group(SLUILayout *layout, const char *group_name,
SLUIFlowKind flow, SLUIAxis axis);
int slui_layout_group_by_name(const SLUILayout *layout, const char *group_name);
int slui_layout_group_count(const SLUILayout *layout);
/* Per-group organization knobs. */
void slui_group_set_flow(SLUILayout *layout, const char *group_name,
SLUIFlowKind flow, SLUIAxis axis);
void slui_group_set_spacing(SLUILayout *layout, const char *group_name,
SLUIMeasure spacing);
void slui_group_set_padding(SLUILayout *layout, const char *group_name,
SLUIMeasure padding);
void slui_group_set_align(SLUILayout *layout, const char *group_name,
SLUIPlacement main_align, SLUIPlacement cross_align);
void slui_group_set_columns(SLUILayout *layout, const char *group_name,
int columns); /* for GRID / WRAP */
/* ---- items (named) ------------------------------------------------------ */
/* Add a named item carrying an optional widget, into a named group. `widget`
* may be NULL for a pure spacer/placeholder. The item's main-axis size is
* `size` (a measure; FR makes it flexible). Returns an item id (>=0). */
int slui_layout_item(SLUILayout *layout, const char *group_name,
const char *item_name, SLUIWidget *widget,
SLUIMeasure size);
int slui_layout_item_by_name(const SLUILayout *layout, const char *item_name);
int slui_group_item_count(const SLUILayout *layout, const char *group_name);
/* --------------------------------------------------------------------------
* Adjustment -- a single item, a whole group, or an N-ARY selection.
*
* The same adjustment verbs work at three granularities, so you can resize one
* item, re-weight a whole group, or nudge an arbitrary subset of a group of
* some size. "size" is the main-axis measure; "mass" is the CENTRAL weight that
* a SLUI_FLOW_CENTRAL / SLUI_PLACE_CENTRAL packing uses.
* ------------------------------------------------------------------------- */
/* single */
void slui_item_set_size(SLUILayout *layout, const char *item_name,
SLUIMeasure size);
void slui_item_set_mass(SLUILayout *layout, const char *item_name, double mass);
void slui_item_set_align(SLUILayout *layout, const char *item_name,
SLUIPlacement cross_align);
void slui_item_set_visible(SLUILayout *layout, const char *item_name, int on);
/* group (every item in the named group) */
void slui_group_set_size(SLUILayout *layout, const char *group_name,
SLUIMeasure size);
void slui_group_set_mass(SLUILayout *layout, const char *group_name,
double mass);
void slui_group_set_item_align(SLUILayout *layout, const char *group_name,
SLUIPlacement cross_align);
/* n-ary (a chosen subset of a group) -- pass an array of `count` item names.
* Adjusts exactly those items, leaving the rest of the group untouched. */
void slui_nary_set_size(SLUILayout *layout, const char *const *item_names,
int count, SLUIMeasure size);
void slui_nary_set_mass(SLUILayout *layout, const char *const *item_names,
int count, double mass);
void slui_nary_set_align(SLUILayout *layout, const char *const *item_names,
int count, SLUIPlacement cross_align);
/* --------------------------------------------------------------------------
* Named ergonomic presets -- "the ergonomics of publics shall be Named". Each
* applies a tasteful flow + spacing + alignment to a named group at once, for a
* common public use.
* ------------------------------------------------------------------------- */
typedef enum {
SLUI_ERGO_READING = 0, /* a calm single column, medium (centered) runs */
SLUI_ERGO_GALLERY = 1, /* a wrapping flow of equal tiles */
SLUI_ERGO_DASHBOARD = 2, /* a multi-column grid */
SLUI_ERGO_CONSOLE = 3, /* a dense top-aligned stack */
SLUI_ERGO_PORTRAIT = 4, /* central (weight/mass) packing, generous space*/
SLUI_ERGO_TOOLBAR = 5 /* a tight horizontal stack, start-aligned */
} SLUIErgonomics;
void slui_group_set_ergonomics(SLUILayout *layout, const char *group_name,
SLUIErgonomics ergo);
/* --------------------------------------------------------------------------
* Resolution -- lay the groups out within a device-pixel rectangle and read
* back each item's resolved rect, so a host can place real widgets. Call after
* any adjustment. A group with no explicit area is laid out within `area`;
* nested groups (an item whose name matches a group) recurse.
* ------------------------------------------------------------------------- */
void slui_layout_arrange(SLUILayout *layout, const char *group_name,
SLUIRect area);
/* The resolved rect of a named item (valid after arrange). Returns 1 on
* success (writes *out), 0 if the item is unknown or not yet arranged. */
int slui_layout_item_rect(const SLUILayout *layout, const char *item_name,
SLUIRect *out);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* SLEELA_UI_LAYOUT_H */