Architecture

Architecture Overview

This document provides a high-level overview of the Figuro GUI toolkit's architecture. It was generated by Gemini 2.5 based on a repomix compressed representation of this repository as of April 30th, 2025.

Core Concepts:

• Multi-threaded Architecture: Figuro utilizes a multi-threaded design, separating the main UI logic/application thread from the rendering thread. This is achieved through components like Agent, AgentProxy, threads, and RChan (channels for inter-thread communication) found in the runtime and examples.
• Node-Based Structure: The UI is constructed using a tree of nodes (Figuro objects). These nodes represent UI elements and concepts. The src/figuro/common/nodes directory defines basic node properties, CSS integration, and the mechanism for transferring data between UI and render nodes.
• Widget System: Figuro includes a collection of pre-built, reusable UI components (widgets) such as buttons, checkboxes, and sliders, located in src/figuro/widgets. Developers can utilize these standard widgets or create custom ones.

Key Architectural Layers:

Common (src/figuro/common)

• Contains fundamental data structures, types (like UiScalar, Color, Box), and utilities shared across the toolkit.
• Defines the basic Node structure, event types (uievents), input handling (inputs), font types (fonttypes), and mathematical utilities (uimaths).
• Includes modules for handling CSS basics, values, and parsing (cssbasics, cssvalues, cssparser).

UI Logic (src/figuro/ui)

• Manages core user interface aspects.
• CSS Engine (cssengine.nim): Parses and applies CSS rules for styling and theming, utilizing the stylus library and CSS Grid concepts.
• Layout Engine (layout.nim): Calculates the size and position of UI elements using CSS Grid principles, as evidenced by files like apisImpl.nim and the use of the cssgrid library.
• Event Handling (events.nim): Processes user inputs (mouse clicks, key presses, hover, drag) and dispatches events to the appropriate UI nodes.
• Text Handling (text.nim, textboxes.nim): Manages text rendering, layout, and input within text-based widgets.
• Animations (animations.nim): Provides mechanisms for creating UI animations, such as fading effects.

Widgets (src/figuro/widgets)

• Contains implementations for standard UI controls including Button, Checkbox, Input, ScrollPane, Slider, Dropdown, etc.
• These widgets are built upon the core UI logic and the node structure.

Runtime (src/figuro/runtime)

• Handles the main application loop and environment setup.
• runtimeCore.nim manages the interaction between the UI thread and the renderer thread.
• runtimeNative.nim contains platform-specific code for native application execution.
• Includes utilities like timers and a CSS file monitor (utils/cssMonitor.nim) for live theme updates.

Renderer (src/figuro/renderer)

• Responsible for drawing the UI onto the screen.
• OpenGL Backend (opengl): The primary rendering backend employs OpenGL. Its components manage:
  • Shaders (glsl): Contains GLSL code for rendering, with support for different OpenGL versions and Emscripten.
  • Buffers (buffers.nim): Manages OpenGL vertex and index buffers.
  • Textures (textures.nim, atlas.frag/vert): Handles texture loading and management, using a texture atlas for efficiency and supporting formats like .flippy.
  • Context (context.nim): Manages OpenGL state, matrix transformations, and drawing commands.
  • Windowing (window.nim): Interfaces with the underlying windowing system (via windex).
• Render Tree (transfer.nim): Converts the UI node tree into a structure optimized for rendering (Renders, RenderList, Node), potentially organized by Z-level for layering.

---

See https://deepwiki.com/elcritch/figuro for a more detailed description (AI generated and maybe contain some errors).