cotis_layout/
lib.rs

1//! Reference layout engine for [Cotis](https://docs.rs/cotis) element trees.
2//!
3//! `cotis-layout` implements Cotis's [`LayoutManager`](cotis::layout::LayoutManager) and
4//! [`LayoutFrameManager`](cotis::layout::LayoutFrameManager) traits. It runs a flexbox-like
5//! sizing and positioning pass over a configured element tree and produces a stream of
6//! [`RenderCommandOutput`](layout_struct::RenderCommandOutput) values for downstream pipes
7//! (typically [`cotis-pipes`](https://docs.rs/cotis-pipes)) and renderers.
8//!
9//! # Frame lifecycle
10//!
11//! 1. Create a [`CotisLayoutManager`](preamble::CotisLayoutManager) with the viewport
12//!    [`Dimensions`](cotis_utils::math::Dimensions).
13//! 2. Wire it into a [`CotisApp`](cotis::cotis_app::CotisApp) with a renderer. The renderer
14//!    supplies a text measurer and window dimensions via [`LayoutManagerCompatible`](cotis::layout::LayoutManagerCompatible).
15//! 3. Each frame: `begin_frame()` returns a [`CotisLayoutRun`](preamble::CotisLayoutRun).
16//! 4. UI code opens elements through [`ConfigureElements`](cotis::element_configuring::ConfigureElements)
17//!    (`open_new_element`, `set_config`, `close_element`).
18//! 5. Text leaves use [`ConfigureLeafElements`](cotis::element_configuring::ConfigureLeafElements)
19//!    with [`TextElementConfig`](cotis_defaults::element_configs::text_config::TextElementConfig).
20//! 6. `end()` runs layout (fit/grow/shrink, text wrap, positioning) and yields an iterator of
21//!    [`RenderCommandOutput`](layout_struct::RenderCommandOutput).
22//! 7. A pipe such as `CotisLayoutToRenderListPipeForGenerics` converts those commands into
23//!    renderer-specific draw lists.
24//!
25//! # Quick start
26//!
27//! For a runnable desktop demo, use a renderer backend such as
28//! [cotis-wgpu](https://github.com/igna-778/cotis-wgpu) or
29//! [cotis-raylib](https://github.com/igna-778/cotis-raylib). Local examples under `examples/`
30//! mirror the same wiring once ecosystem crates are on crates.io. A minimal setup looks like:
31//!
32//! ```rust,ignore
33//! use cotis::cotis_app::CotisApp;
34//! use cotis_layout::preamble::CotisLayoutManager;
35//! use cotis_pipes::cotis_layout_pipes::CotisLayoutToRenderListPipeForGenerics;
36//! use cotis_utils::math::Dimensions;
37//!
38//! let dimensions = Dimensions::new(800.0, 600.0);
39//! let manager = CotisLayoutManager::new(dimensions);
40//! // let app = CotisApp::new(renderer, manager, CotisLayoutToRenderListPipeForGenerics);
41//! ```
42//!
43//! # Modules
44//!
45//! - [`preamble`] — convenience re-exports: [`CotisLayoutManager`](preamble::CotisLayoutManager), [`CotisLayoutRun`](preamble::CotisLayoutRun),
46//!   [`TextConfigurable`](preamble::TextConfigurable).
47//! - [`layout_traits`] — [`CotisLayoutCompatible`](layout_traits::CotisLayoutCompatible), the bridge trait for custom config types.
48//! - [`layout_struct`] — layout output types ([`RenderCommandOutput`](layout_struct::RenderCommandOutput), clip markers,
49//!   [`TextDrawPayload`](layout_struct::TextDrawPayload)).
50//! - [`cotis_traits`] — Cotis trait implementations for the default [`ElementConfig`](cotis_defaults::element_configs::ElementConfig)
51//!   integration path and element-state query hooks.
52//!
53//! # Generic config types
54//!
55//! To use a config type other than `ElementConfig`, implement [`CotisLayoutCompatible`](layout_traits::CotisLayoutCompatible) to map
56//! your type into the internal layout style representation, and [`TextConfigurable`](preamble::TextConfigurable) if your type
57//! supports text leaves. Built-in wiring for `ElementConfig` lives in [`cotis_traits`].
58//!
59//! # Inspecting layout state
60//!
61//! After a frame completes, [`CotisLayoutManager::get_cache_element`](preamble::CotisLayoutManager::get_cache_element) exposes a snapshot of the
62//! last layout tree for debugging and hit-testing. [`cotis_traits::secondary_traits`] implements
63//! [`cotis_utils::element_state`] query traits on that cache.
64//!
65//! # Cargo features
66//!
67//! | Feature | Effect |
68//! |---------|--------|
69//! | `serialization` | Enables `serde` on render output types and serialization in `cotis`, `cotis-defaults`, and `cotis-utils`. |
70
71pub(crate) mod layout_management;
72pub mod layout_struct;
73
74pub(crate) mod layout_algorithm;
75
76pub(crate) mod text;
77
78/// Entry-point re-exports for the layout manager and frame configurator.
79///
80/// Most applications use [`CotisLayoutManager`](crate::layout_management::CotisLayoutManager) as the `LayoutManager` type parameter on
81/// [`CotisApp`](cotis::cotis_app::CotisApp) and interact with elements each frame through
82/// [`CotisLayoutRun`](crate::layout_management::CotisLayoutRun) via the standard Cotis configuring traits (see [`crate::cotis_traits`]).
83pub mod preamble {
84    pub use crate::layout_management::CotisLayoutManager;
85    pub use crate::layout_management::CotisLayoutRun;
86    pub use crate::text::text_leafs::TextConfigurable;
87}
88
89pub mod layout_traits;
90
91pub mod cotis_traits;
cotis_layout/lib.rs

cotis_layout/
lib.rs
