tawasuyu/taffy

1//! Contains both [a high-level interface to Taffy](crate::Taffy) using a ready-made node tree, and [a trait for defining a custom node trees](crate::tree::LayoutTree) / utility types to help with that.
2
3use crate::geometry::{Line, Size};
4use crate::style::{AvailableSpace, Style};
5
6// Submodules
7mod cache;
8pub use cache::Cache;
9mod node;
10#[cfg(feature = "taffy_tree")]
11use node::NodeData;
12pub use node::NodeId;
13#[cfg(feature = "taffy_tree")]
14mod taffy_tree;
15#[cfg(feature = "taffy_tree")]
16pub use taffy_tree::{Taffy, TaffyError, TaffyResult};
17mod layout;
18pub use layout::{CollapsibleMarginSet, Layout, LayoutInput, LayoutOutput, RunMode, SizingMode};
19
20/// This if the core abstraction in Taffy. Any type that *correctly* implements `PartialLayoutTree` can be laid out using Taffy's algorithms.
21///
22/// The type implementing `PartialLayoutTree` would typically be an entire tree of nodes (or a view over an entire tree of nodes).
23/// However, `PartialLayoutTree` and Taffy's algorithm implementations have been designed such that they can be used for a laying out a single
24/// node that only has access to it's immediate children.
25pub trait PartialLayoutTree {
26    /// Type representing an iterator of the children of a node
27    type ChildIter<'a>: Iterator<Item = NodeId>
28    where
29        Self: 'a;
30
31    /// Get the list of children IDs for the given node
32    fn child_ids(&self, parent_node_id: NodeId) -> Self::ChildIter<'_>;
33
34    /// Get the number of children for the given node
35    fn child_count(&self, parent_node_id: NodeId) -> usize;
36
37    /// Get a specific child of a node, where the index represents the nth child
38    fn get_child_id(&self, parent_node_id: NodeId, child_index: usize) -> NodeId;
39
40    /// Get a reference to the [`Style`] for this node.
41    fn get_style(&self, node_id: NodeId) -> &Style;
42
43    /// Get a mutable reference to the node's unrounded layout
44    fn get_unrounded_layout_mut(&mut self, node_id: NodeId) -> &mut Layout;
45
46    /// Get a mutable reference to the [`Cache`] for this node.
47    fn get_cache_mut(&mut self, node_id: NodeId) -> &mut Cache;
48
49    /// Compute the specified node's size or full layout given the specified constraints
50    fn compute_child_layout(&mut self, node_id: NodeId, inputs: LayoutInput) -> LayoutOutput;
51}
52
53/// Extends [`PartialLayoutTree`] with an additional guarantee: that the child/children methods can be used to recurse
54/// infinitely down the tree. Enables Taffy's rounding and debug printing methods to be used.
55pub trait LayoutTree: PartialLayoutTree {
56    /// Get a reference to the node's final layout
57    fn get_final_layout(&self, node_id: NodeId) -> &Layout;
58    /// Get a mutable reference to the node's final layout
59    fn get_final_layout_mut(&mut self, node_id: NodeId) -> &mut Layout;
60}
61
62/// A private trait which allows us to add extra convenience methods to types which implement
63/// LayoutTree without making those methods public.
64pub(crate) trait PartialLayoutTreeExt: PartialLayoutTree {
65    /// Compute the size of the node given the specified constraints
66    #[inline(always)]
67    fn measure_child_size(
68        &mut self,
69        node_id: NodeId,
70        known_dimensions: Size<Option<f32>>,
71        parent_size: Size<Option<f32>>,
72        available_space: Size<AvailableSpace>,
73        sizing_mode: SizingMode,
74        vertical_margins_are_collapsible: Line<bool>,
75    ) -> Size<f32> {
76        self.compute_child_layout(
77            node_id,
78            LayoutInput {
79                known_dimensions,
80                parent_size,
81                available_space,
82                sizing_mode,
83                run_mode: RunMode::ComputeSize,
84                vertical_margins_are_collapsible,
85            },
86        )
87        .size
88    }
89
90    /// Perform a full layout on the node given the specified constraints
91    #[inline(always)]
92    fn perform_child_layout(
93        &mut self,
94        node_id: NodeId,
95        known_dimensions: Size<Option<f32>>,
96        parent_size: Size<Option<f32>>,
97        available_space: Size<AvailableSpace>,
98        sizing_mode: SizingMode,
99        vertical_margins_are_collapsible: Line<bool>,
100    ) -> LayoutOutput {
101        self.compute_child_layout(
102            node_id,
103            LayoutInput {
104                known_dimensions,
105                parent_size,
106                available_space,
107                sizing_mode,
108                run_mode: RunMode::PerformLayout,
109                vertical_margins_are_collapsible,
110            },
111        )
112    }
113}
114
115impl<T: PartialLayoutTree> PartialLayoutTreeExt for T {}