Document low-level traits (#604)
Delta semántico
Ninguna definición cambió: el cambio es de texto, documentación o datos.
3 archivos · +153 −9
- src/compute/mod.rs +21 −4
- src/lib.rs +5 −5
- src/tree/traits.rs +127 −0
diff --git a/src/compute/mod.rs b/src/compute/mod.rs
index 6ea352984..09aa7226a 100644
--- a/src/compute/mod.rs
+++ b/src/compute/mod.rs
@@ -1,9 +1,26 @@
-//! Low-level access to the layout algorithms themselves
+//! Low-level access to the layout algorithms themselves. For a higher-level API, see the [`TaffyTree`](crate::TaffyTree) struct.
//!
-//! All of the functions in this module except `round_layout` operate on the [`LayoutPartialTree`] trait. See the [`crate::tree::traits`] module for details on how to implement this trait.
+//! ### Layout functions
+//!
+//! The layout functions all take an [`&mut impl LayoutPartialTree`](crate::LayoutPartialTree) parameter, which represents a single container node and it's direct children.
+//!
+//! | Function | Purpose |
+//! | --- | --- |
+//! | [`compute_flexbox_layout`] | Layout a Flexbox container and it's direct children |
+//! | [`compute_grid_layout`] | Layout a CSS Grid container and it's direct children |
+//! | [`compute_block_layout`] | Layout a Block container and it's direct children |
+//! | [`compute_leaf_layout`] | Applies common properties like padding/border/aspect-ratio to a node before deferring to a passed closure to determine it's size. Can be applied to nodes like text or image nodes. |
+//! | [`compute_root_layout`] | Layout the root node of a tree (regardless of it's layout mode). This function is typically called once to begin a layout run. | |
+//! | [`compute_hidden_layout`] | Mark a node as hidden during layout (like `Display::None`) |
+//! | [`compute_cached_layout`] | Attempts to find a cached layout for the specified node and layout inputs. Uses the provided closure to compute the layout (and then stores the result in the cache) if no cached layout is found. |
+//!
+//! ### Other functions
+//!
+//! | Function | Requires | Purpose |
+//! | --- | --- | --- |
+//! | [`round_layout`] | [`RoundTree`] | Round a tree of float-valued layouts to integer pixels |
+//! | [`print_tree`](crate::print_tree) | [`PrintTree`](crate::PrintTree) | Print a debug representation of a node tree and it's computed layout |
//!
-//! For a higher-level API, see the [`TaffyTree`](crate::TaffyTree) struct.
-
pub(crate) mod common;
pub(crate) mod leaf;
diff --git a/src/lib.rs b/src/lib.rs
index 4f1e5fc06..039b1fc16 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,7 @@
//! # Taffy
//!
//! Taffy is a flexible, high-performance library for **UI layout**.
-//! It currently implements the Block, Flexbox and Grid layout algorithms from the CSS specification. Support for other paradigms is planned.
+//! It currently implements the Flexbox, Grid and Block layout algorithms from the CSS specification. Support for other paradigms is planned.
//! For more information on this and other future development plans see the [roadmap issue](https://github.com/DioxusLabs/taffy/issues/345).
//!
//! ## Architecture
@@ -20,7 +20,6 @@
//! ## High-level API vs. Low-level API
//!
//! Taffy has two APIs: a high-level API that is simpler and easier to get started with, and a low-level API that is more flexible gives greater control.
-//!
//! We would generally recommend the high-level API for users using Taffy standalone and the low-level API for users wanting to embed Taffy as part of
//! a wider layout system or as part of a UI framework that already has it's own node/widget tree representation.
//!
@@ -39,6 +38,7 @@
//! - [flexbox_gap](https://github.com/DioxusLabs/taffy/blob/main/examples/flexbox_gap.rs)
//! - [grid_holy_grail](https://github.com/DioxusLabs/taffy/blob/main/examples/basic.rs)
//! - [measure](https://github.com/DioxusLabs/taffy/blob/main/examples/measure.rs)
+//! - [cosmic_text](https://github.com/DioxusLabs/taffy/blob/main/examples/cosmic_text.rs)
//!
//! In particular, the "measure" example shows how to integrate Taffy layout with other layout modalities such as text or image layout when using the high level API.
//!
@@ -53,8 +53,9 @@
//!
//! Examples which show usage of the low-level API are:
//!
-//! - [custom_layout_tree_vec](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_layout_tree_vec.rs) which implements a custom Taffy tree using a `Vec` as an arena with NodeId's being index's into the Vec.
-//! - [custom_layout_tree_owned](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_layout_tree_owned.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers.
+//! - [custom_tree_vec](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_vec.rs) which implements a custom Taffy tree using a `Vec` as an arena with NodeId's being index's into the Vec.
+//! - [custom_tree_owned_partial](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_owned_partial.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers.
+//! - [custom_tree_owned_unsafe](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_owned_unsafe.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers.
#![cfg_attr(not(feature = "std"), no_std)]
#![deny(unsafe_code)]
@@ -115,4 +116,3 @@ pub use crate::util::print_tree;
pub use crate::geometry::*;
pub use crate::style::*;
pub use crate::tree::*;
-pub use crate::util::*;
diff --git a/src/tree/traits.rs b/src/tree/traits.rs
index 76bf7d6d3..ce6688294 100644
--- a/src/tree/traits.rs
+++ b/src/tree/traits.rs
@@ -1,4 +1,131 @@
//! The abstractions that make up the core of Taffy's low-level API
+//!
+//! ## Examples
+//!
+//! The following examples demonstrate end-to-end implementation of Taffy's traits and usage of the low-level compute APIs:
+//!
+//! - [custom_tree_vec](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_vec.rs) which implements a custom Taffy tree using a `Vec` as an arena with NodeId's being index's into the Vec.
+//! - [custom_tree_owned_partial](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_owned_partial.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers.
+//! - [custom_tree_owned_unsafe](https://github.com/DioxusLabs/taffy/blob/main/examples/custom_tree_owned_unsafe.rs) which implements a custom Taffy tree using directly owned children with NodeId's being pointers.
+//!
+//! ## Overview
+//!
+//! ### Trait dependency tree
+//!
+//! The tree below illustrates which traits depend on which other traits.
+//!
+//! ```text
+//! TraversePartialTree - Access a node's children
+//! ├── LayoutPartialTree - Run layout algorithms on a node and it's direct children
+//! └── TraverseTree - Recursively access a node's descendants
+//! ├── RoundTree - Round a float-valued` layout to integer pixels
+//! └── PrintTree - Print a debug representation of a node tree
+//! ```
+//!
+//! ### A table of traits
+//!
+//! | Trait | Requires | Enables |
+//! | --- | --- | --- |
+//! | [`LayoutPartialTree`] | [`TraversePartialTree`] | [`compute_flexbox_layout`](crate::compute_flexbox_layout)<br />[`compute_grid_layout`](crate::compute_grid_layout)<br />[`compute_block_layout`](crate::compute_block_layout)<br />[`compute_root_layout`](crate::compute_root_layout)<br />[`compute_leaf_layout`](crate::compute_leaf_layout)<br />[`compute_hidden_layout`](crate::compute_hidden_layout)<br />[`compute_cached_layout`](crate::compute_cached_layout) |
+//! | [`RoundTree`] | [`TraverseTree`] | [`round_layout`](crate::round_layout) |
+//! | [`PrintTree`] | [`TraverseTree`] | [`print_tree`](crate::print_tree) |
+//!
+//! ## All of the traits on one page
+//!
+//! ### TraversePartialTree and TraverseTree
+//! These traits are Taffy's abstraction for downward tree traversal:
+//! - [`TraversePartialTree`] allows access to a single container node, and it's immediate children. This is the only "traverse" trait that is required
+//! for use of Taffy's core layout algorithms (flexbox, grid, etc).
+//! - [`TraverseTree`] is a marker trait which uses the same API signature as `TraversePartialTree`, but extends it with a guarantee that the child/children methods can be used to recurse
+//! infinitely down the tree. It is required by the `RoundTree` and
+//! the `PrintTree` traits.
+//! ```rust
+//! # use taffy::*;
+//! pub trait TraversePartialTree {
+//! /// Type representing an iterator of the children of a node
+//! type ChildIter<'a>: Iterator<Item = NodeId>
+//! where
+//! Self: 'a;
+//!
+//! /// Get the list of children IDs for the given node
+//! fn child_ids(&self, parent_node_id: NodeId) -> Self::ChildIter<'_>;
+//!
+//! /// Get the number of children for the given node
+//! fn child_count(&self, parent_node_id: NodeId) -> usize;
+//!
+//! /// Get a specific child of a node, where the index represents the nth child
+//! fn get_child_id(&self, parent_node_id: NodeId, child_index: usize) -> NodeId;
+//! }
+//!
+//! pub trait TraverseTree: TraversePartialTree {}
+//! ```
+//!
+//! You must implement [`TraversePartialTree`] to access any of Taffy's low-level API. If your tree implementation allows you to implement [`TraverseTree`] with
+//! the correct semantics (full recursive traversal is available) then you should.
+//!
+//! ### LayoutPartialTree
+//!
+//! **Requires:** `TraversePartialTree`<br />
+//! **Enables:** Flexbox, Grid, Block and Leaf layout algorithms from the [`crate::compute`] module
+//!
+//! Any type that implements [`LayoutPartialTree`] can be laid out using [Taffy's algorithms](crate::compute)
+//!
+//! Note that this trait extends [`TraversePartialTree`] (not [`TraverseTree`]). Taffy's algorithm implementations have been designed such that they can be used for a laying out a single
+//! node that only has access to it's immediate children.
+//!
+//! ```rust
+//! # use taffy::*;
+//! pub trait LayoutPartialTree: TraversePartialTree {
+//! /// Get a reference to the [`Style`] for this node.
+//! fn get_style(&self, node_id: NodeId) -> &Style;
+//!
+//! /// Set the node's unrounded layout
+//! fn set_unrounded_layout(&mut self, node_id: NodeId, layout: &Layout);
+//!
+//! /// Get a mutable reference to the [`Cache`] for this node.
+//! fn get_cache_mut(&mut self, node_id: NodeId) -> &mut Cache;
+//!
+//! /// Compute the specified node's size or full layout given the specified constraints
+//! fn compute_child_layout(&mut self, node_id: NodeId, inputs: LayoutInput) -> LayoutOutput;
+//! }
+//! ```
+//!
+//! ### RoundTree
+//!
+//! **Requires:** `TraverseTree`
+//!
+//! Trait used by the `round_layout` method which takes a tree of unrounded float-valued layouts and performs
+//! rounding to snap the values to the pixel grid.
+//!
+//! As indicated by it's dependence on `TraverseTree`, it required full recursive access to the tree.
+//!
+//! ```rust
+//! # use taffy::*;
+//! pub trait RoundTree: TraverseTree {
+//! /// Get the node's unrounded layout
+//! fn get_unrounded_layout(&self, node_id: NodeId) -> &Layout;
+//! /// Get a reference to the node's final layout
+//! fn set_final_layout(&mut self, node_id: NodeId, layout: &Layout);
+//! }
+//! ```
+//!
+//! ### PrintTree
+//!
+//! **Requires:** `TraverseTree`
+//!
+//! ```rust
+//! /// Trait used by the `print_tree` method which prints a debug representation
+//! ///
+//! /// As indicated by it's dependence on `TraverseTree`, it required full recursive access to the tree.
+//! # use taffy::*;
+//! pub trait PrintTree: TraverseTree {
+//! /// Get a debug label for the node (typically the type of node: flexbox, grid, text, image, etc)
+//! fn get_debug_label(&self, node_id: NodeId) -> &'static str;
+//! /// Get a reference to the node's final layout
+//! fn get_final_layout(&self, node_id: NodeId) -> &Layout;
+//! }
+//! ```
+//!
use super::{Cache, Layout, LayoutInput, LayoutOutput, NodeId, RequestedAxis, RunMode, SizingMode};
use crate::geometry::{AbsoluteAxis, Line, Size};
use crate::style::{AvailableSpace, Style};