Crate taffy 

Taffy

Taffy is a flexible, high-performance library for UI layout. 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.

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”: arbitrary user-defined data (which you can access when using a “measure function” to integrate Taffy with other kinds of layout such as text layout)

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:

• basic
• flexbox_gap
• grid_holy_grail
• measure
• cosmic_text

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 LayoutPartialTree 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 crate::tree::traits module for more details on this API.

Examples which show usage of the low-level API are:

• custom_tree_vec 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 which implements a custom Taffy tree using directly owned children with NodeId’s being index’s into vec on parent node.
• custom_tree_owned_unsafe which implements a custom Taffy tree using directly owned children with NodeId’s being pointers.

Modules

compute

Low-level access to the layout algorithms themselves. For a higher-level API, see the TaffyTree struct.

geometry

Geometric primitives useful for layout

prelude

Commonly used types

style

A typed representation of CSS style properties in Rust. Used as input to layout computation.

style_helpers

Helper functions which it make it easier to create instances of types in the style and geometry modules.

tree

Contains both a high-level interface to Taffy using a ready-made node tree, and a set of traits for defining custom node trees.

util

Helpful misc. utilities such as a function to debug print a tree

Structs

BlockContext

Context for each individual Block within a Block Formatting Context

BlockFormattingContext

Context for positioning Block and Float boxes within a Block Formatting Context

Cache

A cache for caching the results of a sizing a Grid Item or Flexbox Item

CollapsibleMarginSet

A set of margins that are available for collapsing with for block layout’s margin collapsing

CompactLength

A representation of a length as a compact 64-bit tagged pointer

ContentSlot

An empty “slot” that avoids floats that is suitable for non-floated content to be laid out into

DetailedGridInfo

Information from the computation of grid

DetailedGridItemsInfo

Grid area information from the placement algorithm

DetailedGridTracksInfo

Information from the computation of grids tracks

Dimension

A unit of linear measurement

FloatContext

A context for placing floated boxes

FloatIntrinsicWidthCalculator

Context for computing the intrinsic width contribution of a set of floats

GridTemplateArea

Defines a grid area

GridTemplateRepetition

A typed representation of a repeat(..) in grid-template-* value

Layout

The final result of a layout algorithm for a single node.

LayoutInput

A struct containing the inputs constraints/hints for laying out a node, which are passed in by the parent

LayoutOutput

A struct containing the result of laying a single node, which is returned up to the parent node

LengthPercentage

A unit of linear measurement

LengthPercentageAuto

A unit of linear measurement

Line

An abstract “line”. Represents any type that has a start and an end

MaxTrackSizingFunction

Maximum track sizing function

MinMax

Generic struct which holds a “min” value and a “max” value

MinTrackSizingFunction

Minimum track sizing function

NamedGridLine

Defines a named grid line

NodeId

A type representing the id of a single node in a tree of nodes

Point

A 2-dimensional coordinate.

Rect

An axis-aligned UI rectangle

Size

The width and height of a Rect

Style

A typed representation of the CSS style information for a single node.

TaffyTree

An entire tree of UI nodes. The entry point to Taffy’s high-level API.

Enums

AbsoluteAxis

The simple absolute horizontal and vertical axis

AbstractAxis

The CSS abstract axis https://www.w3.org/TR/css-writing-modes-3/#abstract-axes

AlignContent

Sets the distribution of space between and around content items For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis

AlignItems

Used to control how child nodes are aligned. For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis

AvailableSpace

The amount of space available to a node in a given axis https://www.w3.org/TR/css-sizing-3/#available

BoxGenerationMode

An abstracted version of the CSS display property where any value other than “none” is represented by “normal” See: https://www.w3.org/TR/css-display-3/#box-generation

BoxSizing

Specifies whether size styles for this node are assigned to the node’s “content box” or “border box”

Clear

Gives a box “clearance”, which moves it below floated boxes which precede it in the tree.

ClearState

Clear operation outcome. See Cache::clear

DetailedLayoutInfo

The additional information from layout algorithm

Direction

Sets the direction of text, table and grid columns, and horizontal overflow. https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/direction

Display

Sets the layout used for the children of this node

FlexDirection

The direction of the flexbox layout main axis.

FlexWrap

Controls whether flex items are forced onto one line or can wrap onto multiple lines.

Float

Floats a box to the left or right. This property only applies to children of a block layout

FloatDirection

Whether a box that is definitely floated is floated to the left of to the right.

GenericGridPlacement

A grid line placement specification which is generic over the coordinate system that it uses to define grid line positions.

GenericGridTemplateComponent

A type representing a component in a grid-template-* defintion where the type representing repeat()s is generic

GridAutoFlow

Controls whether grid items are placed row-wise or column-wise. And whether the sparse or dense packing algorithm is used.

GridPlacement

A grid line placement specification. Used for grid-[row/column]-[start/end]. Named tracks are not implemented.

GridTemplateComponent

An element in a grid-template-columns or grid-template-rows definition. Either a track sizing function or a repeat().

Overflow

How children overflowing their container should affect layout

Position

The positioning strategy for this item.

RepetitionCount

The first argument to a repeated track definition. This type represents the type of automatic repetition to perform.

RequestedAxis

An axis that layout algorithms can be requested to compute a size for

RunMode

Whether we are performing a full layout, or we merely need to size the node

SizingMode

Whether styles should be taken into account when computing size

TaffyError

An error that occurs while trying to access or modify a node’s children by index.

TextAlign

Used by block layout to implement the legacy behaviour of <center> and <div align="left | right | center">

Traits

BlockContainerStyle

The set of styles required for a Block layout container

BlockItemStyle

The set of styles required for a Block layout item (child of a Block container)

CacheTree

Trait used by the compute_cached_layout method which allows cached layout results to be stored and retrieved.

CheapCloneStr

Trait that represents a cheaply clonable string. If you’re unsure what to use here consider Arc<str> or string_cache::Atom.

CoreStyle

The core set of styles that are shared between all CSS layout nodes

FlexboxContainerStyle

The set of styles required for a Flexbox container

FlexboxItemStyle

The set of styles required for a Flexbox item (child of a Flexbox container)

GenericRepetition

A trait to represent a repeat() clause in a grid-template-* definition

GridContainerStyle

The set of styles required for a CSS Grid container

GridItemStyle

The set of styles required for a CSS Grid item (child of a CSS Grid container)

LayoutBlockContainer

Extends LayoutPartialTree with getters for the styles required for CSS Block layout

LayoutFlexboxContainer

Extends LayoutPartialTree with getters for the styles required for Flexbox layout

LayoutGridContainer

Extends LayoutPartialTree with getters for the styles required for CSS Grid layout

LayoutPartialTree

Any type that implements LayoutPartialTree can be laid out using Taffy’s algorithms

MaybeMath

A trait to conveniently calculate minimums and maximums when some data may not be defined

MaybeResolve

Trait to encapsulate behaviour where we need to resolve from a potentially context-dependent size or dimension into a context-independent size or dimension.

PrintTree

Trait used by the print_tree method which prints a debug representation

ResolveOrZero

Trait to encapsulate behaviour where we need to resolve from a potentially context-dependent size or dimension into a context-independent size or dimension.

RoundTree

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.

TemplateLineNames

A nested list of line names. This is effectively a generic representation of Vec<Vec<String>> that allows both the collection and string type to be customised.

TraversePartialTree

Taffy’s abstraction for downward tree traversal.

TraverseTree

A marker trait which extends TraversePartialTree

Functions

compute_block_layout

Computes the layout of LayoutPartialTree according to the block layout algorithm

compute_cached_layout

Attempts to find a cached layout for the specified node and layout inputs.

compute_flexbox_layout

Computes the layout of a box according to the flexbox algorithm

compute_grid_layout

Grid layout algorithm This consists of a few phases:

compute_hidden_layout

Creates a layout for this node and its children, recursively. Each hidden node has zero size and is placed at the origin

compute_leaf_layout

Compute the size of a leaf node (node with no children)

compute_root_layout

Compute layout for the root node in the tree

print_tree

Prints a debug representation of the computed layout for a tree of nodes, starting with the passed root node.

round_layout

Rounds the calculated layout to exact pixel values

write_tree

Writes a debug representation of the computed layout to the writer, starting with the passed root node.

Type Aliases

AlignSelf

Controls alignment of an individual node

JustifyContent

Sets the distribution of space between and around content items For Flexbox it controls alignment in the main axis For Grid it controls alignment in the inline axis

JustifyItems

Used to control how child nodes are aligned. Does not apply to Flexbox, and will be ignored if specified on a flex container For Grid it controls alignment in the inline axis

JustifySelf

Controls alignment of an individual node

TaffyResult

The error Taffy generates on invalid operations

TrackSizingFunction

The sizing function for a grid track (row/column)