ratatui/layout/flex.rs
1use strum::{Display, EnumIs, EnumString};
2
3#[allow(unused_imports)]
4use crate::layout::Constraint;
5
6/// Defines the options for layout flex justify content in a container.
7///
8/// This enumeration controls the distribution of space when layout constraints are met.
9///
10/// - `Legacy`: Fills the available space within the container, putting excess space into the last
11/// element.
12/// - `Start`: Aligns items to the start of the container.
13/// - `End`: Aligns items to the end of the container.
14/// - `Center`: Centers items within the container.
15/// - `SpaceBetween`: Adds excess space between each element.
16/// - `SpaceAround`: Adds excess space around each element.
17#[derive(Copy, Debug, Default, Display, EnumString, Clone, Eq, PartialEq, Hash, EnumIs)]
18pub enum Flex {
19 /// Fills the available space within the container, putting excess space into the last
20 /// constraint of the lowest priority. This matches the default behavior of ratatui and tui
21 /// applications without [`Flex`]
22 ///
23 /// The following examples illustrate the allocation of excess in various combinations of
24 /// constraints. As a refresher, the priorities of constraints are as follows:
25 ///
26 /// 1. [`Constraint::Min`]
27 /// 2. [`Constraint::Max`]
28 /// 3. [`Constraint::Length`]
29 /// 4. [`Constraint::Percentage`]
30 /// 5. [`Constraint::Ratio`]
31 /// 6. [`Constraint::Fill`]
32 ///
33 /// When every constraint is `Length`, the last element gets the excess.
34 ///
35 /// ```plain
36 /// <----------------------------------- 80 px ------------------------------------>
37 /// ┌──────20 px───────┐┌──────20 px───────┐┌────────────────40 px─────────────────┐
38 /// │ Length(20) ││ Length(20) ││ Length(20) │
39 /// └──────────────────┘└──────────────────┘└──────────────────────────────────────┘
40 /// ^^^^^^^^^^^^^^^^ EXCESS ^^^^^^^^^^^^^^^^
41 /// ```
42 ///
43 /// Fill constraints have the lowest priority amongst all the constraints and hence
44 /// will always take up any excess space available.
45 ///
46 /// ```plain
47 /// <----------------------------------- 80 px ------------------------------------>
48 /// ┌──────20 px───────┐┌──────20 px───────┐┌──────20 px───────┐┌──────20 px───────┐
49 /// │ Fill(0) ││ Max(20) ││ Length(20) ││ Length(20) │
50 /// └──────────────────┘└──────────────────┘└──────────────────┘└──────────────────┘
51 /// ^^^^^^ EXCESS ^^^^^^
52 /// ```
53 ///
54 /// # Examples
55 ///
56 /// ```plain
57 /// <------------------------------------80 px------------------------------------->
58 /// ┌──────────────────────────60 px───────────────────────────┐┌──────20 px───────┐
59 /// │ Min(20) ││ Max(20) │
60 /// └──────────────────────────────────────────────────────────┘└──────────────────┘
61 ///
62 /// <------------------------------------80 px------------------------------------->
63 /// ┌────────────────────────────────────80 px─────────────────────────────────────┐
64 /// │ Max(20) │
65 /// └──────────────────────────────────────────────────────────────────────────────┘
66 /// ```
67 Legacy,
68
69 /// Aligns items to the start of the container.
70 ///
71 /// # Examples
72 ///
73 /// ```plain
74 /// <------------------------------------80 px------------------------------------->
75 /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
76 /// │Percentage(20)││ Length(20) ││ Fixed(20) │
77 /// └──────────────┘└──────────────────┘└──────────────────┘
78 ///
79 /// <------------------------------------80 px------------------------------------->
80 /// ┌──────20 px───────┐┌──────20 px───────┐
81 /// │ Max(20) ││ Max(20) │
82 /// └──────────────────┘└──────────────────┘
83 ///
84 /// <------------------------------------80 px------------------------------------->
85 /// ┌──────20 px───────┐
86 /// │ Max(20) │
87 /// └──────────────────┘
88 /// ```
89 #[default]
90 Start,
91
92 /// Aligns items to the end of the container.
93 ///
94 /// # Examples
95 ///
96 /// ```plain
97 /// <------------------------------------80 px------------------------------------->
98 /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
99 /// │Percentage(20)││ Length(20) ││ Length(20) │
100 /// └──────────────┘└──────────────────┘└──────────────────┘
101 ///
102 /// <------------------------------------80 px------------------------------------->
103 /// ┌──────20 px───────┐┌──────20 px───────┐
104 /// │ Max(20) ││ Max(20) │
105 /// └──────────────────┘└──────────────────┘
106 ///
107 /// <------------------------------------80 px------------------------------------->
108 /// ┌──────20 px───────┐
109 /// │ Max(20) │
110 /// └──────────────────┘
111 /// ```
112 End,
113
114 /// Centers items within the container.
115 ///
116 /// # Examples
117 ///
118 /// ```plain
119 /// <------------------------------------80 px------------------------------------->
120 /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
121 /// │Percentage(20)││ Length(20) ││ Length(20) │
122 /// └──────────────┘└──────────────────┘└──────────────────┘
123 ///
124 /// <------------------------------------80 px------------------------------------->
125 /// ┌──────20 px───────┐┌──────20 px───────┐
126 /// │ Max(20) ││ Max(20) │
127 /// └──────────────────┘└──────────────────┘
128 ///
129 /// <------------------------------------80 px------------------------------------->
130 /// ┌──────20 px───────┐
131 /// │ Max(20) │
132 /// └──────────────────┘
133 /// ```
134 Center,
135
136 /// Adds excess space between each element.
137 ///
138 /// # Examples
139 ///
140 /// ```plain
141 /// <------------------------------------80 px------------------------------------->
142 /// ┌────16 px─────┐ ┌──────20 px───────┐ ┌──────20 px───────┐
143 /// │Percentage(20)│ │ Length(20) │ │ Length(20) │
144 /// └──────────────┘ └──────────────────┘ └──────────────────┘
145 ///
146 /// <------------------------------------80 px------------------------------------->
147 /// ┌──────20 px───────┐ ┌──────20 px───────┐
148 /// │ Max(20) │ │ Max(20) │
149 /// └──────────────────┘ └──────────────────┘
150 ///
151 /// <------------------------------------80 px------------------------------------->
152 /// ┌────────────────────────────────────80 px─────────────────────────────────────┐
153 /// │ Max(20) │
154 /// └──────────────────────────────────────────────────────────────────────────────┘
155 /// ```
156 SpaceBetween,
157
158 /// Adds excess space around each element.
159 ///
160 /// # Examples
161 ///
162 /// ```plain
163 /// <------------------------------------80 px------------------------------------->
164 /// ┌────16 px─────┐ ┌──────20 px───────┐ ┌──────20 px───────┐
165 /// │Percentage(20)│ │ Length(20) │ │ Length(20) │
166 /// └──────────────┘ └──────────────────┘ └──────────────────┘
167 ///
168 /// <------------------------------------80 px------------------------------------->
169 /// ┌──────20 px───────┐ ┌──────20 px───────┐
170 /// │ Max(20) │ │ Max(20) │
171 /// └──────────────────┘ └──────────────────┘
172 ///
173 /// <------------------------------------80 px------------------------------------->
174 /// ┌──────20 px───────┐
175 /// │ Max(20) │
176 /// └──────────────────┘
177 /// ```
178 SpaceAround,
179}
180#[cfg(test)]
181mod tests {}