Xilem and Masonry Documentation

Masonry is a foundational framework designed for building GUI libraries in Rust. It provides a platform-independent manager that owns and maintains a widget tree, along with tools for runtime inspection, unit testing, and debugging.

Key characteristics:

• Not opinionated about abstraction: You can implement immediate-mode, Elm architecture, or functional reactive GUI on top of it.
• Opinionated about internals: Centralizes handling of text focus, pointer interactions, and accessibility events.
• Built on top of: Imaging (Vello/wgpu), Parley (text stack), and AccessKit (accessibility).
• Target Audience: Developers creating GUI libraries. If you are building a standard application, consider using Xilem, which is built on top of Masonry.

Tree Arena provides two tree implementations designed for use in the Masonry crate:

1. Safe Tree: The default, baseline implementation. It uses a TreeArena that owns root nodes in a Vec<TreeNode<T>> and a parents_map to track parentage. Each node owns its children via Vec<TreeNode<T>>. Accessing a descendant requires traversing ancestors, resulting in $O(\text{depth})$ time for descendant checks and $O(\text{children})$ time at each level.

2. Unsafe Tree: A high-performance implementation using a DataMap arena. It uses a HashMap to store nodes as Box<UnsafeCell<TreeNode<T>>> to allow interior mutability and prevent movement during resizing. It provides shared (ArenaRef) and exclusive (ArenaMut) access. While faster, it is not yet fully tested and is not used by default.

xilem_masonry is a backend implementation of the Xilem architecture (via xilem_core) that uses masonry widgets as Xilem elements.

Note: You should generally avoid depending on this crate directly unless your goal is to embed Xilem into a non-Winit platform. For standard usage, use [Xilem] or [Xilem Web] instead.

Masonry is a foundation for building Rust GUI libraries. It provides a platform to create windows (typically using winit) containing a tree of widgets. Developers can implement various GUI architectures (immediate-mode, Elm-architecture, functional reactive, etc.) by implementing the Widget trait.

Key design principles include:

• Minimalism: Masonry avoids complex internal reconciliation or dataflow algorithms; high-level logic is left to downstream crates.
• Rust-native mutability: It avoids unsafe code and minimizes the use of Cell/Mutex, working within Rust's ownership system.
• Testability & Debugging: Built-in support for simulated user interactions, screenshot testing, and reflection of the widget tree/accessibility data.

Placehero is a Mastodon client built using the [Xilem][xilem] framework. It serves as a practical example of how to use Xilem for application development.

Privacy Note: Placehero assumes that all supported Mastodon servers are trusted. It links accounts even across different sessions and logouts; if you require strict privacy between accounts, do not use Placehero.

The RobotoFlex-Subset.ttf font is a variable font used to validate Masonry's support for variable fonts, specifically in the variable_clock example. It includes a subset of characters (0123456789:-/+=÷×±()) and supports the following variable axes:

• GRAD (Grade)
• XOPQ (Horizontal Optical Size)
• XTRA (Width)
• YOPQ (Vertical Optical Size)
• YTAS (Ascender)
• YTDE (Descender)
• YTFI (Ascender/Descender spacing)
• YTLC (Line Gap)
• YTUC (Ascender/Descender spacing)
• opsz (Optical Size)
• slnt (Slant)
• wdth (Width)
• wght (Weight)

When running Placehero, a dedicated user data folder is used to store sensitive information such as login tokens and profile data.

Security Warning: Do not share the contents of this folder, as it contains private credentials.

Note that as of the current version, this folder is reserved for future use and is not yet actively utilized by the application, but it is maintained to prevent accidental credential uploads once login functionality is implemented.

Masonry Core provides the following fundamental GUI engine capabilities:

• Widget: The core trait for defining GUI widgets.
• Event Handling: Event bubbling and handling using ui-events types.
• Layout Communication: Mechanisms for parent and child widgets to communicate during layout.
• Compositing: Content compositing intended for use with the imaging crate.
• Accessibility: Creation of accessibility trees via accesskit.
• Widget Manipulation: APIs for interacting with widgets, such as WidgetMut.
• Action Mechanism: The Action associated type on the Widget trait, used by widgets to send events to the application.

Masonry's architecture is based on a series of passes—computations run over a subset of the widget tree during every frame. Passes are categorized into three main types:

• Event passes: Triggered by user interaction (e.g., mouse clicks, text input).
• Rewrite passes: Run after event passes to recompute invalidated values. These may run multiple times until all invalidation flags are cleared.
• Render passes: Run just before rendering a new frame (e.g., painting or accessibility tree generation).

Unless otherwise specified, all passes run over widgets in depth-first preorder, where child order is determined by their position in the children_ids() array.