# kojix2/uing architecture

> Architecture diagram of the GitHub repository kojix2/uing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kojix2/uing
- Repository: https://github.com/kojix2/uing

## Overview

#### Purpose and Entry Points
UIng is a Crystal-language binding to the native C library libui-ng, providing cross-platform desktop GUI controls, layout, menus, drawing, tables, and images. Consumer applications `require "uing"`, initialize the runtime, construct controls, run the native event loop, then uninitialize. The public aggregation and runtime entry point are `src/uing.cr` and `src/uing/lib_ui/lib_ui.cr`; package installation/native-library download is driven by `shard.yml` and `download.cr`.

#### API Layer Boundary
The repository intentionally separates:
- **Low-level FFI:** `UIng::LibUI` exposes direct libui-ng C bindings and C-compatible structs. Paths: `src/uing/lib_ui/lib_ui.cr`, `src/uing/lib_ui/control.cr`, `include/ui.h`.
- **High-level Crystal wrappers:** object-oriented controls own native handles, expose Crystal callbacks, DSL block construction, and lifecycle methods. Paths: `src/uing/control.cr`, `src/uing/window.cr`, `src/uing/block_constructor.cr`.

This is the critical managed/unmanaged boundary: Crystal GC protects wrapper references and callbacks, while libui-ng resources still require explicit `destroy` or `free`.

#### UI Composition and Lifecycle
`Control` is the common abstraction for native widgets. Concrete controls and containers form parent/child ownership trees: destroying a native parent destroys its current children, while supported container deletion detaches children for reuse. Windows and menus are retained as roots to avoid premature GC. Core paths: `src/uing/control.cr`, `src/uing/window.cr`, `src/uing/box.cr`, `src/uing/group.cr`.

Application control flow is: `UIng.init` → construct menus/windows/control tree and install callbacks → `show` → `UIng.main` native event loop → quit/explicit resource release → `UIng.uninit`. Window-closing and global quit callbacks are the primary shutdown boundary.

#### Widget and Layout Surface
Standard controls map Crystal methods and event handlers onto libui-ng widgets. Layout containers encode the supported native composition model rather than pixel positioning: boxes, forms, tabs, groups, and grids. Key paths: `src/uing/button.cr`, `src/uing/entry.cr`, `src/uing/form.cr`, `src/uing/grid.cr`, `src/uing/tab.cr`.

Menus and dialog behavior are also native-backed and window-associated: `src/uing/menu.cr`, `src/uing/menu_item.cr`, `src/uing/window.cr`.

#### Advanced Data and Rendering Subsystems
**Tables** use a model/handler contract and selections/value types. They require explicit model and selection freeing at defined ownership boundaries; tables must be destroyed before their model. Paths: `src/uing/table/table.cr`, `src/uing/table/table/model.cr`, `src/uing/table/table/model/handler.cr`.

**Areas** provide custom drawing and input via native handler callbacks. Drawing contexts, paths, brushes, matrices, text layout, and event structures are represented as Crystal wrappers. Extended handler structures/trampolines bridge C function pointers back to boxed Crystal closures. Paths: `src/uing/area/area.cr`, `src/uing/area/area/handler.cr`, `src/uing/area/area/draw/context.cr`.

#### Native Runtime and Platform Dependencies
The binding links against downloaded patched libui-ng binaries. libui-ng uses platform-native GUI stacks: Win32 with Direct2D/DirectWrite on Windows, Cocoa/AppKit on macOS, and GTK 3/Pango on Linux/Unix. Supported CI targets cover Linux x64/ARM64, macOS Intel/ARM64, and Windows MSVC/MinGW/UCRT variants, via `.github/workflows/ci-linux-x64.yml` and corresponding platform workflows. Windows builds include Common Controls v6 manifest resources: `comctl32.manifest`, `comctl32.rc`.

#### Verification and Distribution Examples
The gallery is the primary executable compatibility surface for controls and rendering; screenshot automation runs it across OSes: `examples/gallery/control_gallery.cr`, `.github/workflows/screenshot.yml`, `.github/actions/screenshot/action.yml`. More complete app/distribution patterns live separately in `examples/md5_checker/src/app.cr` and `examples/air_hockey/src/air_hockey/app.cr`.

Main entry points: [`src/uing/control.cr`](https://github.com/kojix2/uing/blob/main/src/uing/control.cr) (Control wrapper base), [`src/uing/lib_ui/lib_ui.cr`](https://github.com/kojix2/uing/blob/main/src/uing/lib_ui/lib_ui.cr) (LibUI bindings), [`src/uing/area/area.cr`](https://github.com/kojix2/uing/blob/main/src/uing/area/area.cr) (Areas), [`src/uing/window.cr`](https://github.com/kojix2/uing/blob/main/src/uing/window.cr) (Windows & shutdown)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Crystal API"]
  node_public_api["UIng entry point<br/>public API<br/>[uing.cr]"]
  node_ffi_runtime{{"LibUI bindings<br/>FFI layer<br/>[lib_ui.cr]"}}
  node_ffi_control["Native control ABI<br/>FFI structs<br/>[control.cr]"]
  node_wrappers["Control wrapper base<br/>managed wrapper<br/>[control.cr]"]
  node_dsl["Block construction<br/>Crystal DSL"]
end

subgraph group_ui["UI Composition"]
  node_window["Windows &amp; shutdown<br/>root control<br/>[window.cr]"]
  node_controls["Standard controls<br/>widget wrappers<br/>[button.cr]"]
  node_layout["Layout containers<br/>container wrappers<br/>[box.cr]"]
  node_menus["Menus &amp; menu items<br/>native menu wrappers<br/>[menu.cr]"]
end

subgraph group_advanced["Advanced UI"]
  node_tables["Tables<br/>data widget<br/>[table.cr]"]
  node_table_model["Table model handlers<br/>model callback bridge<br/>[handler.cr]"]
  node_areas["Areas<br/>custom drawing widget<br/>[area.cr]"]
  node_area_handlers{{"Area callback bridge<br/>C callback trampoline<br/>[handler.cr]"}}
  node_drawing["Drawing context<br/>rendering wrapper<br/>[context.cr]"]
end

subgraph group_native["Native Delivery"]
  node_libui{{"libui-ng<br/>native GUI runtime<br/>[download.cr]"}}
  node_platform_gui["Platform GUI stacks<br/>OS dependencies"]
end

subgraph group_verification["Examples &amp; CI"]
  node_gallery["Control gallery<br/>example application<br/>[control_gallery.cr]"]
  node_screenshots["Screenshot automation<br/>CI workflow<br/>[screenshot.yml]"]
end

node_consumer["Consumer application<br/>Crystal app"]

node_consumer -->|"require and lifecycle"| node_public_api
node_public_api -->|"init / main / uninit"| node_ffi_runtime
node_ffi_runtime -->|"defines ABI"| node_ffi_control
node_wrappers -->|"native calls"| node_ffi_runtime
node_dsl -->|"constructs"| node_wrappers
node_window -->|"extends control lifecycle"| node_wrappers
node_controls -->|"extends"| node_wrappers
node_layout -->|"extends"| node_wrappers
node_layout -->|"owns child controls"| node_controls
node_window -->|"hosts control tree"| node_layout
node_menus -->|"associated with"| node_window
node_tables -->|"uses model and handlers"| node_table_model
node_tables -->|"native control lifecycle"| node_wrappers
node_areas -->|"installs callbacks"| node_area_handlers
node_areas -->|"draws through"| node_drawing
node_areas -->|"native control lifecycle"| node_wrappers
node_ffi_runtime -->|"links against"| node_libui
node_libui -->|"uses"| node_platform_gui
node_gallery -->|"exercises"| node_public_api
node_screenshots -->|"runs"| node_gallery

click node_public_api "https://github.com/kojix2/uing/blob/main/src/uing.cr"
click node_ffi_runtime "https://github.com/kojix2/uing/blob/main/src/uing/lib_ui/lib_ui.cr"
click node_ffi_control "https://github.com/kojix2/uing/blob/main/src/uing/lib_ui/control.cr"
click node_wrappers "https://github.com/kojix2/uing/blob/main/src/uing/control.cr"
click node_dsl "https://github.com/kojix2/uing/blob/main/src/uing/block_constructor.cr"
click node_window "https://github.com/kojix2/uing/blob/main/src/uing/window.cr"
click node_controls "https://github.com/kojix2/uing/blob/main/src/uing/button.cr"
click node_layout "https://github.com/kojix2/uing/blob/main/src/uing/box.cr"
click node_menus "https://github.com/kojix2/uing/blob/main/src/uing/menu.cr"
click node_tables "https://github.com/kojix2/uing/blob/main/src/uing/table/table.cr"
click node_table_model "https://github.com/kojix2/uing/blob/main/src/uing/table/table/model/handler.cr"
click node_areas "https://github.com/kojix2/uing/blob/main/src/uing/area/area.cr"
click node_area_handlers "https://github.com/kojix2/uing/blob/main/src/uing/area/area/handler.cr"
click node_drawing "https://github.com/kojix2/uing/blob/main/src/uing/area/area/draw/context.cr"
click node_libui "https://github.com/kojix2/uing/blob/main/download.cr"
click node_gallery "https://github.com/kojix2/uing/blob/main/examples/gallery/control_gallery.cr"
click node_screenshots "https://github.com/kojix2/uing/blob/main/.github/workflows/screenshot.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_ffi_runtime,node_ffi_control,node_wrappers,node_dsl toneBlue
class node_window,node_controls,node_layout,node_menus toneAmber
class node_tables,node_table_model,node_areas,node_area_handlers,node_drawing toneMint
class node_libui,node_platform_gui toneRose
class node_gallery,node_screenshots toneIndigo
class node_consumer toneNeutral
```

## Components

### Crystal API

Public runtime, FFI, and managed wrapper boundary.

- [UIng entry point](https://github.com/kojix2/uing/blob/main/src/uing.cr): public API · Initializes, runs, and uninitializes the native runtime. · `src/uing.cr`
- [LibUI bindings](https://github.com/kojix2/uing/blob/main/src/uing/lib_ui/lib_ui.cr): FFI layer · Direct libui-ng calls and C-compatible structures. · `src/uing/lib_ui/lib_ui.cr`
- [Native control ABI](https://github.com/kojix2/uing/blob/main/src/uing/lib_ui/control.cr): FFI structs · `src/uing/lib_ui/control.cr`
- [Control wrapper base](https://github.com/kojix2/uing/blob/main/src/uing/control.cr): managed wrapper · Owns native handles and provides lifecycle and callback behavior. · `src/uing/control.cr`
- [Block construction](https://github.com/kojix2/uing/blob/main/src/uing/block_constructor.cr): Crystal DSL · `src/uing/block_constructor.cr`

### UI Composition

Native-backed controls, layout, and window roots.

- [Windows & shutdown](https://github.com/kojix2/uing/blob/main/src/uing/window.cr): root control · Retains window roots and supplies close and quit boundaries. · `src/uing/window.cr`
- [Standard controls](https://github.com/kojix2/uing/blob/main/src/uing/button.cr): widget wrappers · Crystal widget methods and event handlers over native controls. · `src/uing/button.cr`
- [Layout containers](https://github.com/kojix2/uing/blob/main/src/uing/box.cr): container wrappers · Build parent-child ownership trees with native layout rules. · `src/uing/box.cr`
- [Menus & menu items](https://github.com/kojix2/uing/blob/main/src/uing/menu.cr): native menu wrappers · Window-associated native menu behavior. · `src/uing/menu.cr`

### Advanced UI

Data-model and custom-rendering subsystems.

- [Tables](https://github.com/kojix2/uing/blob/main/src/uing/table/table.cr): data widget · Tables must be destroyed before their native model. · `src/uing/table/table.cr`
- [Table model handlers](https://github.com/kojix2/uing/blob/main/src/uing/table/table/model/handler.cr): model callback bridge · Model and handler contract with explicit model and selection freeing. · `src/uing/table/table/model/handler.cr`
- [Areas](https://github.com/kojix2/uing/blob/main/src/uing/area/area.cr): custom drawing widget · Custom drawing and input backed by native handlers. · `src/uing/area/area.cr`
- [Area callback bridge](https://github.com/kojix2/uing/blob/main/src/uing/area/area/handler.cr): C callback trampoline · Bridges native function pointers to boxed Crystal closures. · `src/uing/area/area/handler.cr`
- [Drawing context](https://github.com/kojix2/uing/blob/main/src/uing/area/area/draw/context.cr): rendering wrapper · Wraps drawing contexts and related rendering resources. · `src/uing/area/area/draw/context.cr`

### Native Delivery

Downloaded runtime and platform GUI dependencies.

- [libui-ng](https://github.com/kojix2/uing/blob/main/download.cr): native GUI runtime · Patched downloaded binary implementing native controls and event loop. · `download.cr`
- **Platform GUI stacks**: OS dependencies · Win32/Direct2D, Cocoa/AppKit, or GTK 3/Pango.

### Examples & CI

Executable compatibility and screenshot coverage.

- [Control gallery](https://github.com/kojix2/uing/blob/main/examples/gallery/control_gallery.cr): example application · Primary executable compatibility surface. · `examples/gallery/control_gallery.cr`
- [Screenshot automation](https://github.com/kojix2/uing/blob/main/.github/workflows/screenshot.yml): CI workflow · Runs gallery screenshots across operating systems. · `.github/workflows/screenshot.yml`

### Other components

- **Consumer application**: Crystal app · Requires UIng and owns application shutdown.

## Connections

- Consumer application → UIng entry point: require and lifecycle
- UIng entry point → LibUI bindings: init / main / uninit
- LibUI bindings → Native control ABI: defines ABI
- Control wrapper base → LibUI bindings: native calls
- Block construction → Control wrapper base: constructs
- Windows & shutdown → Control wrapper base: extends control lifecycle
- Standard controls → Control wrapper base: extends
- Layout containers → Control wrapper base: extends
- Layout containers → Standard controls: owns child controls
- Windows & shutdown → Layout containers: hosts control tree
- Menus & menu items → Windows & shutdown: associated with
- Tables → Table model handlers: uses model and handlers
- Tables → Control wrapper base: native control lifecycle
- Areas → Area callback bridge: installs callbacks
- Areas → Drawing context: draws through
- Areas → Control wrapper base: native control lifecycle
- LibUI bindings → libui-ng: links against
- libui-ng → Platform GUI stacks: uses
- Control gallery → UIng entry point: exercises
- Screenshot automation → Control gallery: runs