ratatui_core/layout/flex.rs
1use strum::{Display, EnumIs, EnumString};
2
3#[expect(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 and there
9/// is excess space available. The `Flex` option is used with [`Layout`](crate::layout::Layout) to
10/// control how extra space is distributed among layout segments, which is particularly useful for
11/// creating responsive layouts that adapt to different terminal sizes.
12///
13/// Available options:
14///
15/// - `Legacy`: Fills the available space within the container, putting excess space into the last
16/// element.
17/// - `Start`: Aligns items to the start of the container.
18/// - `End`: Aligns items to the end of the container.
19/// - `Center`: Centers items within the container.
20/// - `SpaceBetween`: Adds excess space between each element.
21/// - `SpaceAround`: Adds excess space around each element.
22///
23/// For comprehensive layout documentation and examples, see the [`layout`](crate::layout) module.
24#[derive(Copy, Debug, Default, Display, EnumString, Clone, Eq, PartialEq, Hash, EnumIs)]
25#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
26pub enum Flex {
27 /// Fills the available space within the container, putting excess space into the last
28 /// constraint of the lowest priority. This matches the default behavior of ratatui and tui
29 /// applications without [`Flex`]
30 ///
31 /// The following examples illustrate the allocation of excess in various combinations of
32 /// constraints. As a refresher, the priorities of constraints are as follows:
33 ///
34 /// 1. [`Constraint::Min`]
35 /// 2. [`Constraint::Max`]
36 /// 3. [`Constraint::Length`]
37 /// 4. [`Constraint::Percentage`]
38 /// 5. [`Constraint::Ratio`]
39 /// 6. [`Constraint::Fill`]
40 ///
41 /// When every constraint is `Length`, the last element gets the excess.
42 ///
43 /// ```plain
44 /// <----------------------------------- 80 px ------------------------------------>
45 /// ┌──────20 px───────┐┌──────20 px───────┐┌────────────────40 px─────────────────┐
46 /// │ Length(20) ││ Length(20) ││ Length(20) │
47 /// └──────────────────┘└──────────────────┘└──────────────────────────────────────┘
48 /// ^^^^^^^^^^^^^^^^ EXCESS ^^^^^^^^^^^^^^^^
49 /// ```
50 ///
51 /// Fill constraints have the lowest priority amongst all the constraints and hence
52 /// will always take up any excess space available.
53 ///
54 /// ```plain
55 /// <----------------------------------- 80 px ------------------------------------>
56 /// ┌──────20 px───────┐┌──────20 px───────┐┌──────20 px───────┐┌──────20 px───────┐
57 /// │ Fill(0) ││ Max(20) ││ Length(20) ││ Length(20) │
58 /// └──────────────────┘└──────────────────┘└──────────────────┘└──────────────────┘
59 /// ^^^^^^ EXCESS ^^^^^^
60 /// ```
61 ///
62 /// # Examples
63 ///
64 /// ```plain
65 /// <------------------------------------80 px------------------------------------->
66 /// ┌──────────────────────────60 px───────────────────────────┐┌──────20 px───────┐
67 /// │ Min(20) ││ Max(20) │
68 /// └──────────────────────────────────────────────────────────┘└──────────────────┘
69 ///
70 /// <------------------------------------80 px------------------------------------->
71 /// ┌────────────────────────────────────80 px─────────────────────────────────────┐
72 /// │ Max(20) │
73 /// └──────────────────────────────────────────────────────────────────────────────┘
74 /// ```
75 Legacy,
76
77 /// Aligns items to the start of the container.
78 ///
79 /// # Examples
80 ///
81 /// ```plain
82 /// <------------------------------------80 px------------------------------------->
83 /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
84 /// │Percentage(20)││ Length(20) ││ Fixed(20) │
85 /// └──────────────┘└──────────────────┘└──────────────────┘
86 ///
87 /// <------------------------------------80 px------------------------------------->
88 /// ┌──────20 px───────┐┌──────20 px───────┐
89 /// │ Max(20) ││ Max(20) │
90 /// └──────────────────┘└──────────────────┘
91 ///
92 /// <------------------------------------80 px------------------------------------->
93 /// ┌──────20 px───────┐
94 /// │ Max(20) │
95 /// └──────────────────┘
96 /// ```
97 #[default]
98 Start,
99
100 /// Aligns items to the end of the container.
101 ///
102 /// # Examples
103 ///
104 /// ```plain
105 /// <------------------------------------80 px------------------------------------->
106 /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
107 /// │Percentage(20)││ Length(20) ││ Length(20) │
108 /// └──────────────┘└──────────────────┘└──────────────────┘
109 ///
110 /// <------------------------------------80 px------------------------------------->
111 /// ┌──────20 px───────┐┌──────20 px───────┐
112 /// │ Max(20) ││ Max(20) │
113 /// └──────────────────┘└──────────────────┘
114 ///
115 /// <------------------------------------80 px------------------------------------->
116 /// ┌──────20 px───────┐
117 /// │ Max(20) │
118 /// └──────────────────┘
119 /// ```
120 End,
121
122 /// Centers items within the container.
123 ///
124 /// # Examples
125 ///
126 /// ```plain
127 /// <------------------------------------80 px------------------------------------->
128 /// ┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
129 /// │Percentage(20)││ Length(20) ││ Length(20) │
130 /// └──────────────┘└──────────────────┘└──────────────────┘
131 ///
132 /// <------------------------------------80 px------------------------------------->
133 /// ┌──────20 px───────┐┌──────20 px───────┐
134 /// │ Max(20) ││ Max(20) │
135 /// └──────────────────┘└──────────────────┘
136 ///
137 /// <------------------------------------80 px------------------------------------->
138 /// ┌──────20 px───────┐
139 /// │ Max(20) │
140 /// └──────────────────┘
141 /// ```
142 Center,
143
144 /// Adds excess space between each element.
145 ///
146 /// # Examples
147 ///
148 /// ```plain
149 /// <------------------------------------80 px------------------------------------->
150 /// ┌────16 px─────┐ ┌──────20 px───────┐ ┌──────20 px───────┐
151 /// │Percentage(20)│ │ Length(20) │ │ Length(20) │
152 /// └──────────────┘ └──────────────────┘ └──────────────────┘
153 ///
154 /// <------------------------------------80 px------------------------------------->
155 /// ┌──────20 px───────┐ ┌──────20 px───────┐
156 /// │ Max(20) │ │ Max(20) │
157 /// └──────────────────┘ └──────────────────┘
158 ///
159 /// <------------------------------------80 px------------------------------------->
160 /// ┌────────────────────────────────────80 px─────────────────────────────────────┐
161 /// │ Max(20) │
162 /// └──────────────────────────────────────────────────────────────────────────────┘
163 /// ```
164 SpaceBetween,
165
166 /// Evenly distributes excess space between all elements, including before the first and after
167 /// the last.
168 ///
169 /// # Examples
170 ///
171 /// ```plain
172 /// <------------------------------------80 px------------------------------------->
173 /// ┌────16 px─────┐ ┌──────20 px───────┐ ┌──────20 px───────┐
174 /// │Percentage(20)│ │ Length(20) │ │ Length(20) │
175 /// └──────────────┘ └──────────────────┘ └──────────────────┘
176 ///
177 /// <------------------------------------80 px------------------------------------->
178 /// ┌──────20 px───────┐ ┌──────20 px───────┐
179 /// │ Max(20) │ │ Max(20) │
180 /// └──────────────────┘ └──────────────────┘
181 ///
182 /// <------------------------------------80 px------------------------------------->
183 /// ┌──────20 px───────┐
184 /// │ Max(20) │
185 /// └──────────────────┘
186 /// ```
187 SpaceEvenly,
188
189 /// Adds excess space around each element.
190 ///
191 /// # Examples
192 ///
193 /// ```plain
194 /// <------------------------------------80 px------------------------------------->
195 /// ┌────16 px─────┐ ┌──────20 px───────┐ ┌──────20 px───────┐
196 /// │Percentage(20)│ │ Length(20) │ │ Length(20) │
197 /// └──────────────┘ └──────────────────┘ └──────────────────┘
198 ///
199 /// <------------------------------------80 px------------------------------------->
200 /// ┌──────20 px───────┐ ┌──────20 px───────┐
201 /// │ Max(20) │ │ Max(20) │
202 /// └──────────────────┘ └──────────────────┘
203 ///
204 /// <------------------------------------80 px------------------------------------->
205 /// ┌──────20 px───────┐
206 /// │ Max(20) │
207 /// └──────────────────┘
208 /// ```
209 SpaceAround,
210}
211#[cfg(test)]
212mod tests {}