gummy 0.12.1

A flexible UI layout library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# Gummy

[![GitHub CI](https://github.com/RetGui/gummy/actions/workflows/ci.yml/badge.svg)](https://github.com/RetGui/gummy/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/gummy.svg)](https://crates.io/crates/gummy)
[![docs.rs](https://img.shields.io/docsrs/gummy)](https://docs.rs/gummy)
![Crates.io MSRV](https://img.shields.io/crates/msrv/gummy)

Gummy is a flexible, high-performance, cross-platform UI layout library written in [Rust](https://www.rust-lang.org).

Gummy is a fork of [Taffy](https://github.com/DioxusLabs/taffy). It builds on the work of Taffy's original authors and contributors; their authorship, license, changelog, and project history are retained in this repository.

It currently implements the CSS **Block**, **Flexbox** and **CSS Grid** layout algorithms. 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).

The upstream Taffy crate is a collaborative, cross-team project designed to be used as a dependency for other UI and GUI libraries. It powers:

- [Servo](https://github.com/servo/servo): an alternative web browser
- [Blitz](https://github.com/DioxusLabs/blitz): a radically modular web engine
- [Bevy](https://bevyengine.org/): an ergonomic, ECS-first Rust game engine
- [Takumi](https://github.com/kane50613/takumi): Renders your React components to images
- [iocraft](https://github.com/ccbrown/iocraft): crafting beautiful interfaces for the terminal
- [Slint](https://github.com/slint-ui/slint): a declarative GUI toolkit for building native user interfaces
- The [Lapce](https://lapce.dev/) text editor via the [Floem](https://github.com/lapce/floem) UI framework
- The [Zed](https://zed.dev/) text editor via the [GPUI](https://github.com/zed-industries/zed/tree/main/crates/gpui) UI framework

## Usage


```rust
use gummy::prelude::*;

// First create an instance of GummyTree
let mut tree : GummyTree<()> = GummyTree::new();

// Create a tree of nodes using `GummyTree.new_leaf` and `GummyTree.new_with_children`.
// These functions both return a node id which can be used to refer to that node
// The Style struct is used to specify styling information
let header_node = tree
    .new_leaf(
        Style {
            size: Size { width: length(800.0), height: length(100.0) },
            ..Default::default()
        },
    ).unwrap();

let body_node = tree
    .new_leaf(
        Style {
            size: Size { width: length(800.0), height: auto() },
            flex_grow: 1.0,
            ..Default::default()
        },
    ).unwrap();

let root_node = tree
    .new_with_children(
        Style {
            flex_direction: FlexDirection::Column,
            size: Size { width: length(800.0), height: length(600.0) },
            ..Default::default()
        },
        &[header_node, body_node],
    )
    .unwrap();

// Call compute_layout on the root of your tree to run the layout algorithm
tree.compute_layout(root_node, Size::MAX_CONTENT).unwrap();

// Inspect the computed layout using `GummyTree.layout`
assert_eq!(tree.layout(root_node).unwrap().size.width, 800.0);
assert_eq!(tree.layout(root_node).unwrap().size.height, 600.0);
assert_eq!(tree.layout(header_node).unwrap().size.width, 800.0);
assert_eq!(tree.layout(header_node).unwrap().size.height, 100.0);
assert_eq!(tree.layout(body_node).unwrap().size.width, 800.0);
assert_eq!(tree.layout(body_node).unwrap().size.height, 500.0); // This value was not set explicitly, but was computed by Gummy

```

## Upstream bindings to other languages

- Python via [stretchable](https://github.com/mortencombat/stretchable)
- [WIP C bindings](https://github.com/DioxusLabs/taffy/pull/404)
- [WIP WASM bindings](https://github.com/DioxusLabs/taffy/pull/394)

## Learning Resources


Gummy inherits Taffy's faithful implementations of the Flexbox and CSS Grid specifications, so documentation designed for the web should translate cleanly to Gummy's implementation. For reference documentation on individual style properties we recommend the MDN documentation (for example [this page](https://developer.mozilla.org/en-US/docs/Web/CSS/width) on the `width` property). Such pages can usually be found by searching for "MDN property-name" using a search engine.

If you are interested in guide-level documentation on CSS layout, then we recommend the following resources:

### Flexbox


- [Flexbox Froggy](https://flexboxfroggy.com/). This is an interactive tutorial/game that allows you to learn the essential parts of Flexbox in a fun engaging way.
- [A Complete Guide To Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different Flexbox properties and how they work.

### CSS Grid


- [CSS Grid Garden](https://cssgridgarden.com/). This is an interactive tutorial/game that allows you to learn the essential parts of CSS Grid in a fun engaging way.
- [A Complete Guide To CSS Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different CSS Grid properties and how they work.

## Benchmarks (vs. [Yoga](https://github.com/facebook/yoga))


- Run on a 2021 MacBook Pro with M1 Pro processor using [criterion](https://github.com/bheisler/criterion.rs)
- The benchmarks measure layout computation only. They do not measure tree creation.
- Yoga benchmarks were run via the [yoga](https://github.com/bschwind/yoga-rs) crate (Rust bindings)
- Most popular websites seem to have between 3,000 and 10,000 nodes (although they also require text layout, which neither Yoga nor Taffy implement).

Note that the table below contains multiple different units (milliseconds vs. microseconds)

| Benchmark          | Node Count | Depth | Yoga ([ba27f9d]) | Taffy ([71027a8]) |
| ---                | ---        | ---   | ---              | ---               |
| yoga 'huge nested' | 1,000      | 3     | 364.60 µs        | 329.04 µs         |
| yoga 'huge nested' | 10,000     | 4     | 4.1988 ms        | 4.3486 ms         |
| yoga 'huge nested' | 100,000    | 5     | 45.804 ms        | 38.559 ms         |
| big trees (wide)   | 1,000      | 1     | 737.77 µs        | 505.99 µs         |
| big trees (wide)   | 10,000     | 1     | 7.1007 ms        | 8.3395 ms         |
| big trees (wide)   | 100,000    | 1     | 135.78 ms        | 247.42 ms         |
| big trees (deep)   | 4,000      | 12    | 2.2333 ms        | 1.7400 ms         |
| big trees (deep)   | 10,000     | 14    | 5.9477 ms        | 4.4445 ms         |
| big trees (deep)   | 100,000    | 17    | 76.755 ms        | 63.778 ms         |
| super deep         | 1,000      | 1,000 | 555.32 µs        | 472.85 µs         |

[ba27f9d]: https://github.com/facebook/yoga/commit/ba27f9d1ecfa7518019845b84b035d3d4a2a6658
[71027a8]: https://github.com/DioxusLabs/taffy/commit/71027a8de03b343e120852b84bb7dca9fb4651c5

## Credits

Gummy is derived from [Taffy](https://github.com/DioxusLabs/taffy), created and maintained by the authors and contributors credited in the package metadata and Git history. Taffy was itself forked from [Stretch](https://github.com/vislyhq/stretch). See [LICENSE.md](LICENSE.md) for the retained copyright and license terms.

## Contributions

[Contributions are welcome](CONTRIBUTING.md). If you'd like to use, improve, or build `gummy`, feel free to open an [issue](https://github.com/RetGui/gummy/issues) or submit a [pull request](https://github.com/RetGui/gummy/pulls).