freya_elements/attributes/layout_attributes.rs
1use crate::def_attribute;
2
3def_attribute!(
4 /// Specify the height for the given element.
5 ///
6 /// See syntax in [`Size Units`](crate::_docs::size_unit).
7 ///
8 /// ### Example
9 ///
10 /// ```rust, no_run
11 /// # use freya::prelude::*;
12 /// fn app() -> Element {
13 /// rsx!(
14 /// rect {
15 /// background: "red",
16 /// height: "50",
17 /// width: "15",
18 /// }
19 /// )
20 /// }
21 /// ```
22 height,
23
24 /// Specify the width for the given element.
25 ///
26 /// See syntax in [`Size Units`](crate::_docs::size_unit).
27 ///
28 /// ### Example
29 ///
30 /// ```rust, no_run
31 /// # use freya::prelude::*;
32 /// fn app() -> Element {
33 /// rsx!(
34 /// rect {
35 /// background: "red",
36 /// height: "50",
37 /// width: "15",
38 /// }
39 /// )
40 /// }
41 /// ```
42 width,
43
44 /// Specify a minimum width for the given element.
45 /// This can be useful if you use it alongside a percentage for the target size.
46 ///
47 /// See syntax for [`Size Units`](crate::_docs::size_unit).
48 ///
49 /// ### Example
50 ///
51 /// ```rust, no_run
52 /// # use freya::prelude::*;
53 /// fn app() -> Element {
54 /// rsx!(
55 /// rect {
56 /// background: "red",
57 /// min_width: "100",
58 /// min_height: "100",
59 /// width: "50%",
60 /// height: "50%",
61 /// }
62 /// )
63 /// }
64 /// ```
65 min_width,
66
67 /// Specify a minimum height for the given element.
68 /// This can be useful if you use it alongside a percentage for the target size.
69 ///
70 /// See syntax for [`Size Units`](crate::_docs::size_unit).
71 ///
72 /// ### Example
73 ///
74 /// ```rust, no_run
75 /// # use freya::prelude::*;
76 /// fn app() -> Element {
77 /// rsx!(
78 /// rect {
79 /// background: "red",
80 /// min_width: "100",
81 /// min_height: "100",
82 /// width: "50%",
83 /// height: "50%",
84 /// }
85 /// )
86 /// }
87 /// ```
88 min_height,
89
90 /// Specify a maximum width for the given element.
91 ///
92 /// See syntax for [`Size Units`](crate::_docs::size_unit).
93 ///
94 /// ### Example
95 ///
96 /// ```rust, no_run
97 /// # use freya::prelude::*;
98 /// fn app() -> Element {
99 /// rsx!(
100 /// rect {
101 /// background: "red",
102 /// max_width: "50%",
103 /// width: "500",
104 /// height: "500",
105 /// }
106 /// )
107 /// }
108 /// ```
109 max_width,
110
111 /// Specify a maximum height for the given element.
112 ///
113 /// See syntax for [`Size Units`](crate::_docs::size_unit).
114 ///
115 /// ### Example
116 ///
117 /// ```rust, no_run
118 /// # use freya::prelude::*;
119 /// fn app() -> Element {
120 /// rsx!(
121 /// rect {
122 /// background: "red",
123 /// max_height: "50%",
124 /// width: "500",
125 /// height: "500",
126 /// }
127 /// )
128 /// }
129 /// ```
130 max_height,
131
132 /// Specify the percentage of width to be visible.
133 ///
134 /// ### Example
135 ///
136 /// ```rust, no_run
137 /// # use freya::prelude::*;
138 /// fn app() -> Element {
139 /// rsx!(
140 /// rect {
141 /// background: "red",
142 /// visible_width: "50%", // 250
143 /// width: "500",
144 /// height: "500",
145 /// }
146 /// )
147 /// }
148 /// ```
149 visible_width,
150
151 /// Specify the percentage of height to be visible.
152 ///
153 /// ### Example
154 ///
155 /// ```rust, no_run
156 /// # use freya::prelude::*;
157 /// fn app() -> Element {
158 /// rsx!(
159 /// rect {
160 /// background: "red",
161 /// visible_height: "50%", // 250
162 /// width: "500",
163 /// height: "500",
164 /// }
165 /// )
166 /// }
167 /// ```
168 visible_height,
169
170 /// Specify the margin of an element.
171 /// You can do so by four different ways, just like in CSS.
172 ///
173 /// ### Example
174 ///
175 /// ```rust, no_run
176 /// # use freya::prelude::*;
177 /// fn app() -> Element {
178 /// rsx!(
179 /// rect {
180 /// margin: "25", // 25 in all sides
181 /// margin: "100 50", // 100 in top and bottom, and 50 in left and right
182 /// margin: "2 15 25", // 2 in top, 15 in left and right, and 25 in bottom
183 /// margin: "5 7 3 9" // 5 in top, 7 in right, 3 in bottom and 9 in left
184 /// }
185 /// )
186 /// }
187 /// ```
188 margin,
189
190 /// Specify the inner paddings of an element. You can do so by four different ways, just like in CSS.
191 ///
192 /// ### Example
193 ///
194 /// ```rust, no_run
195 /// # use freya::prelude::*;
196 /// fn app() -> Element {
197 /// rsx!(
198 /// rect {
199 /// padding: "25", // 25 in all sides
200 /// padding: "100 50", // 100 in top and bottom, and 50 in left and right
201 /// padding: "2 15 25", // 2 in top, 15 in left and right, and 25 in bottom
202 /// padding: "5 7 3 9" // 5 in top, 7 in right, 3 in bottom and 9 in left
203 /// }
204 /// )
205 /// }
206 /// ```
207 padding,
208
209 /// Specify how you want the element to be positioned inside it's parent area.
210 ///
211 /// Accepted values:
212 ///
213 /// - `stacked` (default)
214 /// - `absolute` (Floating element relative to the parent element)
215 /// - `global` (Floating element relative to the window)
216 ///
217 /// When using the `absolute` or `global` modes, you can also combine them with the following attributes:
218 ///
219 /// - `position_top`
220 /// - `position_right`
221 /// - `position_bottom`
222 /// - `position_left`
223 ///
224 /// These only support pixels.
225 ///
226 /// ### Example
227 ///
228 /// ```rust, no_run
229 /// # use freya::prelude::*;
230 /// fn app() -> Element {
231 /// rsx!(
232 /// rect {
233 /// width: "100%",
234 /// height: "100%",
235 /// rect {
236 /// position: "absolute",
237 /// position_bottom: "15",
238 /// position_right: "15",
239 /// background: "black",
240 /// width: "100",
241 /// height: "100",
242 /// }
243 /// }
244 /// )
245 /// }
246 /// ```
247 position,
248
249 /// Specify the top position of an element when using `position: "absolute"` or `position: "global"`.
250 /// This supports pixels only.
251 ///
252 /// ### Example
253 ///
254 /// ```rust, no_run
255 /// # use freya::prelude::*;
256 /// fn app() -> Element {
257 /// rsx!(
258 /// rect {
259 /// width: "100%",
260 /// height: "100%",
261 /// rect {
262 /// position: "absolute",
263 /// position_top: "15",
264 /// position_left: "15",
265 /// background: "black",
266 /// width: "100",
267 /// height: "100",
268 /// }
269 /// }
270 /// )
271 /// }
272 /// ```
273 position_top,
274
275 /// Specify the right position of an element when using `position: "absolute"` or `position: "global"`.
276 /// This supports pixels only.
277 ///
278 /// ### Example
279 ///
280 /// ```rust, no_run
281 /// # use freya::prelude::*;
282 /// fn app() -> Element {
283 /// rsx!(
284 /// rect {
285 /// width: "100%",
286 /// height: "100%",
287 /// rect {
288 /// position: "absolute",
289 /// position_top: "15",
290 /// position_right: "15",
291 /// background: "black",
292 /// width: "100",
293 /// height: "100",
294 /// }
295 /// }
296 /// )
297 /// }
298 /// ```
299 position_right,
300
301 /// Specify the bottom position of an element when using `position: "absolute"` or `position: "global"`.
302 /// This supports pixels only.
303 ///
304 /// ### Example
305 ///
306 /// ```rust, no_run
307 /// # use freya::prelude::*;
308 /// fn app() -> Element {
309 /// rsx!(
310 /// rect {
311 /// width: "100%",
312 /// height: "100%",
313 /// rect {
314 /// position: "absolute",
315 /// position_bottom: "15",
316 /// position_right: "15",
317 /// background: "black",
318 /// width: "100",
319 /// height: "100",
320 /// }
321 /// }
322 /// )
323 /// }
324 /// ```
325 position_bottom,
326
327 /// Specify the left position of an element when using `position: "absolute"` or `position: "global"`.
328 /// This supports pixels only.
329 ///
330 /// ### Example
331 ///
332 /// ```rust, no_run
333 /// # use freya::prelude::*;
334 /// fn app() -> Element {
335 /// rsx!(
336 /// rect {
337 /// width: "100%",
338 /// height: "100%",
339 /// rect {
340 /// position: "absolute",
341 /// position_bottom: "15",
342 /// position_left: "15",
343 /// background: "black",
344 /// width: "100",
345 /// height: "100",
346 /// }
347 /// }
348 /// )
349 /// }
350 /// ```
351 position_left,
352
353 /// Control how the inner elements stack.
354 ///
355 /// Accepted values:
356 ///
357 /// - `vertical` (default)
358 /// - `horizontal`
359 ///
360 /// ### Example
361 ///
362 /// ```rust, no_run
363 /// # use freya::prelude::*;
364 /// fn app() -> Element {
365 /// rsx!(
366 /// rect {
367 /// width: "100%",
368 /// height: "100%",
369 /// direction: "vertical",
370 /// rect {
371 /// width: "100%",
372 /// height: "50%",
373 /// background: "red"
374 /// },
375 /// rect {
376 /// width: "100%",
377 /// height: "50%",
378 /// background: "green"
379 /// }
380 /// }
381 /// )
382 /// }
383 /// ```
384 direction,
385
386 /// Specify how you want the automatic (e.g `width: auto`) bounds in the cross axis to be constrained for the inner elements.
387 ///
388 /// Accepted values:
389 ///
390 /// - `normal` (default): Uses parent bounds.
391 /// - `fit`: Uses parent bounds but later shrunks to the size of the biggest element inside.
392 /// - `flex`: Marks the container as flex container, children of this element will be able to use `size`/`size(n)` in their `width` and `height` attributes.
393 ///
394 ///
395 /// ### `fit`
396 ///
397 /// The `fit` mode will allow the inner elements using `width: fill-min` to expand to the biggest element inside this element.
398 ///
399 /// ### Example
400 ///
401 /// ```rust, no_run
402 /// # use freya::prelude::*;
403 /// fn app() -> Element {
404 /// rsx!(
405 /// rect {
406 /// content: "fit",
407 /// height: "100%",
408 /// rect {
409 /// width: "fill-min", // Will have a width of 300px
410 /// height: "25%",
411 /// background: "red",
412 /// }
413 /// rect {
414 /// width: "150", // Will have a width of 150px
415 /// height: "25%",
416 /// background: "green",
417 /// }
418 /// rect {
419 /// width: "fill-min", // Will have a width of 300px
420 /// height: "25%",
421 /// background: "blue",
422 /// }
423 /// rect {
424 /// width: "300", // Biggest element, will have a width of 300px
425 /// height: "25%",
426 /// background: "black",
427 /// }
428 /// }
429 /// )
430 /// }
431 /// ```
432 content,
433
434 /// ### main_align
435 ///
436 /// Control how the inner elements are positioned inside the element. You can combine it with the `direction` attribute to create complex flows.
437 ///
438 /// Accepted values for `main_align`:
439 ///
440 /// - `start` (default): At the begining of the axis
441 /// - `center`: At the center of the axis
442 /// - `end`: At the end of the axis
443 /// - `space-between`(only for `main_align`): Distributed among the available space
444 /// - `space-around` (only for `main_align`): Distributed among the available space with small margins in the sides
445 /// - `space-evenly` (only for `main_align`): Distributed among the available space with the same size of margins in the sides and in between the elements
446 ///
447 /// When using the `vertical` direction it uses the Y axis and in `horizontal` direction it uses the X axis.
448 ///
449 /// Example on how to center the inner elements in the main axis:
450 ///
451 /// ### Example
452 ///
453 /// ```rust, no_run
454 /// # use freya::prelude::*;
455 /// fn app() -> Element {
456 /// rsx!(
457 /// rect {
458 /// width: "100%",
459 /// height: "100%",
460 /// main_align: "center",
461 /// rect {
462 /// width: "50%",
463 /// height: "50%",
464 /// background: "red"
465 /// },
466 /// }
467 /// )
468 /// }
469 /// ```
470 main_align,
471
472 /// ### cross_align
473 ///
474 /// Control how the inner elements are positioned inside the element in the axis perpendicular to the direction.
475 ///
476 /// Accepted values:
477 ///
478 /// - `start` (default): At the begining of the axis (same as in `main_align`)
479 /// - `center`: At the center of the axis (same as in `main_align`)
480 /// - `end`: At the end of the axis (same as in `main_align`)
481 ///
482 /// When using the `vertical` direction it uses the X axis and in `horizontal` direction it uses the Y axis.
483 ///
484 /// Example on how to center the inner elements in the cross axis:
485 ///
486 /// ### Example
487 ///
488 /// ```rust, no_run
489 /// # use freya::prelude::*;
490 /// fn app() -> Element {
491 /// rsx!(
492 /// rect {
493 /// width: "100%",
494 /// height: "100%",
495 /// cross_align: "center",
496 /// rect {
497 /// width: "50%",
498 /// height: "50%",
499 /// background: "red"
500 /// },
501 /// }
502 /// )
503 /// }
504 /// ```
505 cross_align,
506
507 /// Specify a space between the inner elements. Think it as a margin for every element but defined by its parent.
508 /// It only applies to the side of the direction.
509 ///
510 /// ### Example
511 ///
512 /// ```rust, no_run
513 /// # use freya::prelude::*;
514 /// fn app() -> Element {
515 /// rsx!(
516 /// rect {
517 /// direction: "vertical",
518 /// spacing: "20",
519 /// // Not before
520 /// rect {
521 /// width: "100",
522 /// height: "100",
523 /// background: "red",
524 /// }
525 /// // There will be a space between these two elements of 20 pixels
526 /// rect {
527 /// width: "100",
528 /// height: "100",
529 /// background: "blue",
530 /// }
531 /// // Here as well
532 /// rect {
533 /// width: "100",
534 /// height: "100",
535 /// background: "green",
536 /// }
537 /// // But not after
538 /// }
539 /// )
540 /// }
541 /// ```
542 spacing,
543
544 /// Specify how overflow should be handled.
545 ///
546 /// Accepted values:
547 ///
548 /// - `clip`
549 /// - `none`
550 ///
551 /// ### Example
552 ///
553 /// ```rust, no_run
554 /// # use freya::prelude::*;
555 /// fn app() -> Element {
556 /// rsx!(
557 /// rect {
558 /// overflow: "clip",
559 /// width: "100",
560 /// height: "100%",
561 /// rect {
562 /// width: "500",
563 /// height: "100%",
564 /// background: "red",
565 /// }
566 /// }
567 /// )
568 /// }
569 /// ```
570 overflow,
571
572 /// Moves the content inside of the container horizontally by the specified pixel amount.
573 /// This attribute only supports pixels.
574 ///
575 /// ### Example
576 ///
577 /// ```rust, no_run
578 /// # use freya::prelude::*;
579 /// fn app() -> Element {
580 /// rsx!(
581 /// rect {
582 /// width: "200",
583 /// height: "200",
584 /// background: "gray",
585 /// offset_x: "20", // Shifts content 20 pixels to the right
586 /// rect {
587 /// width: "100",
588 /// height: "100",
589 /// background: "red",
590 /// }
591 /// }
592 /// )
593 /// }
594 /// ```
595 offset_x,
596
597 /// Moves the content inside of the container vertically by the specified pixel amount.
598 /// This attribute only supports pixels.
599 ///
600 /// ### Example
601 ///
602 /// ```rust, no_run
603 /// # use freya::prelude::*;
604 /// fn app() -> Element {
605 /// rsx!(
606 /// rect {
607 /// width: "200",
608 /// height: "200",
609 /// background: "gray",
610 /// offset_y: "30", // Shifts content 30 pixels down
611 /// rect {
612 /// width: "100",
613 /// height: "100",
614 /// background: "red",
615 /// }
616 /// }
617 /// )
618 /// }
619 /// ```
620 offset_y,
621
622 /// Controls the stacking order of elements on the z-axis.
623 ///
624 /// In Freya, elements are stacked in the order they appear in the DOM, with later elements
625 /// appearing on top of earlier ones. The `layer` attribute allows you to explicitly control
626 /// this stacking behavior.
627 ///
628 /// Lower layer values position elements higher in the stack (visually on top), while higher
629 /// values position elements lower in the stack (visually behind).
630 ///
631 /// A value of 0 maintains the default stacking order, effectively keeping the layer the same.
632 ///
633 /// ### Example
634 ///
635 /// ```rust, no_run
636 /// # use freya::prelude::*;
637 /// fn app() -> Element {
638 /// rsx!(
639 /// rect {
640 /// width: "500",
641 /// height: "500",
642 /// // Using an image as the base element
643 /// image {
644 /// width: "300",
645 /// height: "200",
646 /// image_data: static_bytes(include_bytes!("../_docs/rust_logo.png")),
647 /// }
648 /// // Overlay on top of the image using absolute positioning
649 /// rect {
650 /// position: "absolute",
651 /// position_top: "0",
652 /// position_left: "0",
653 /// width: "300",
654 /// height: "200",
655 /// background: "rgba(0, 0, 255, 0.5)", // Semi-transparent blue overlay
656 /// layer: "-1", // Ensures this is on top
657 /// }
658 /// }
659 /// )
660 /// }
661 /// ```
662 layer,
663);