Expand description
§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. For more information on this and other future development plans see the roadmap issue.
§Architecture
Taffy is based on a tree of “UI nodes” similar to the tree of DOM nodes that one finds in web-based UI. Each node has:
- A
Style
struct which holds a set of CSS styles which function as the primary input to the layout computations. - A
Layout
struct containing a position (x/y) and a size (width/height) which function as the output of the layout computations. - Optionally:
- A
Vec
set of child nodes - “Context”: arbitary user-defined data (which you can access when using a “measure function” to integrate Taffy with other kinds of layout such as text layout)
- A
Usage of Taffy consists of constructing a tree of UI nodes (with associated styles, children and context), then calling function(s) from Taffy to translate those styles, parent-child relationships and measure functions into a size and position in 2d space for each node in the tree.
§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.
§High-level API
The high-level API** consists of the TaffyTree
struct which contains a tree implementation and provides methods that allow you to construct
a tree of UI nodes. Once constructed, you can call the compute_layout_with_measure
method to compute the layout (passing in a “measure function” closure which is used to compute the size of leaf nodes), and then access
the layout of each node using the layout
method.
When using the high-level API, Taffy will take care of node storage, caching and dispatching to the correct layout algorithm for a given node for you.
See the TaffyTree
struct for more details on this API.
Examples which show usage of the high-level API include:
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.
§Low-level API
The low-level API consists of a set of traits (notably the PartialLayoutTree
trait) which define an interface behind which you must implement your own
tree implementation, and a set of functions such as compute_flexbox_layout
and compute_grid_layout
which implement the layout algorithms (for a single node at a time), and are designed to be flexible
and easy to integrate into a wider layout or UI system.
When using this API, you must handle node storage, caching, and dispatching to the correct layout algorithm for a given node yourself.
See the PartialLayoutTree
trait for more details on this API.
Examples which show usage of the high-level API are:
- custom_layout_tree_vec 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 which implements a custom Taffy tree using directly owned children with NodeId’s being pointers.
Re-exports§
Modules§
- The layout algorithms themselves
- Geometric primitives useful for layout
- Commonly used types
- A typed representation of CSS style properties in Rust. Used as input to layout computation.
- Helper functions which it make it easier to create instances of types in the
style
andgeometry
modules. - Contains both a high-level interface to Taffy using a ready-made node tree, and a trait for defining a custom node trees / utility types to help with that.
- Helpful misc. utilities such as a function to debug print a tree
Structs§
- A typed representation of the CSS style information for a single node.
- An entire tree of UI nodes. The entry point to Taffy’s high-level API.
Traits§
- Extends
PartialLayoutTree
with an additional guarantee: that the child/children methods can be used to recurse infinitely down the tree. Enables Taffy’s rounding and debug printing methods to be used. - This if the core abstraction in Taffy. Any type that correctly implements
PartialLayoutTree
can be laid out using Taffy’s algorithms.
Functions§
- Computes the layout of
PartialLayoutTree
according to the block layout algorithm - Updates the stored layout of the provided
node
and its children - Computes the layout of
PartialLayoutTree
according to the flexbox algorithm - Grid layout algorithm This consists of a few phases:
- Creates a layout for this node and its children, recursively. Each hidden node has zero size and is placed at the origin
- Updates the stored layout of the provided
node
and its children - Compute the size of a leaf node (node with no children)
- Prints a debug representation of the computed layout for a tree of nodes, starting with the passed root node.
- Rounds the calculated
Layout
to exact pixel values