embedded_layout/align/
mod.rs

1//! Alignment operations
2//!
3//! Alignment operations are used to arrange two [`View`]s relative to each other. A single [`align_*`]
4//! call requires both a `horizontal` and a `vertical` alignment parameter.
5//!
6//! The list of currently supported alignments:
7//!  - [`horizontal`]
8//!    - `NoAlignment`, `Left`, `Center`, `Right`
9//!    - `LeftToRight`
10//!    - `RightToLeft`
11//!  - [`vertical`]
12//!    - `NoAlignment`, `Top`, `Center`, `Bottom`
13//!    - `TopToBottom`
14//!    - `BottomToTop`
15//!
16//! Alignment works by calling [`align_to`] or [`align_to_mut`] on an object that implements
17//! the [`Align`] trait. The call needs a second [`View`] to align to, called the reference [`View`],
18//! and two alignment parameters. The second [`View`] will not be translated by the alignment
19//! operation.
20//!
21//! [`horizontal`]: crate::align::horizontal
22//! [`vertical`]: crate::align::vertical
23//! [`align_*`]: crate::align::Align
24//! [`align_to`]: crate::align::Align::align_to
25//! [`align_to_mut`]: crate::align::Align::align_to_mut
26use crate::prelude::*;
27use embedded_graphics::{prelude::Point, primitives::Rectangle};
28
29pub mod horizontal;
30pub mod vertical;
31
32/// This trait enables alignment operations for [`View`] objects
33///
34/// This trait is blanket-implemented for all objects that implement [`View`].
35///
36/// For more information, see the [module level documentation](crate::align)
37pub trait Align {
38    /// Return the object aligned to an other one using the alignment parameters as rules
39    fn align_to<H, V>(self, reference: &impl View, horizontal: H, vertical: V) -> Self
40    where
41        H: HorizontalAlignment,
42        V: VerticalAlignment;
43
44    /// Align the object to an other one using the alignment parameters as rules
45    fn align_to_mut<H, V>(
46        &mut self,
47        reference: &impl View,
48        horizontal: H,
49        vertical: V,
50    ) -> &mut Self
51    where
52        H: HorizontalAlignment,
53        V: VerticalAlignment;
54}
55
56impl<T> Align for T
57where
58    T: View,
59{
60    #[inline]
61    fn align_to<H, V>(mut self, reference: &impl View, horizontal: H, vertical: V) -> Self
62    where
63        H: HorizontalAlignment,
64        V: VerticalAlignment,
65    {
66        self.align_to_mut(reference, horizontal, vertical);
67        self
68    }
69
70    #[inline]
71    fn align_to_mut<H, V>(&mut self, reference: &impl View, horizontal: H, vertical: V) -> &mut Self
72    where
73        H: HorizontalAlignment,
74        V: VerticalAlignment,
75    {
76        let self_bounds = self.bounds();
77        let reference_bounds = reference.bounds();
78
79        let h = horizontal.align(self_bounds, reference_bounds);
80        let v = vertical.align(self_bounds, reference_bounds);
81
82        self.translate_mut(Point::new(h, v))
83    }
84}
85
86/// Base trait for alignment operations
87///
88/// An [`Alignment`] object modifies either the horizontal, or the vertical position of a [`View`].
89/// Usually, these objects are passed to methods of [`Align`] or they can be used to parametrize
90/// layouts.
91///
92/// Implementors should also implement either the [`HorizontalAlignment`] or [`VerticalAlignment`]
93/// trait, otherwise the implementor can't be used as an alignment operation with `embedded-layout`.
94pub trait Alignment: Copy + Clone + Default {
95    /// Align one coordinate of `View` to the given reference
96    #[inline]
97    fn align(&self, what: Rectangle, reference: Rectangle) -> i32 {
98        self.align_with_offset(what, reference, 0)
99    }
100
101    /// Align one coordinate of `View` to the given reference with some offset
102    fn align_with_offset(&self, what: Rectangle, reference: Rectangle, offset: i32) -> i32;
103}
104
105/// Implement this trait for horizontal alignment operations
106///
107/// This trait does not provide any functionality other than that of [`Alignment`], but marks
108/// implementors to be used as horizontal alignmenent operations.
109///
110/// For a list of available horizontal alignments, see the [`horizontal`] module.
111///
112/// [`horizontal`]: crate::align::horizontal
113pub trait HorizontalAlignment: Alignment {}
114
115/// Implement this trait for vertical alignment operations
116///
117/// Vertical alignment assumes lower coordinate values are higher up on the display.
118///
119/// This trait does not provide any functionality other than that of [`Alignment`], but marks
120/// implementors to be used as vertical alignmenent operations.
121///
122/// For a list of available vertical alignments, see the [`vertical`] module.
123///
124/// [`vertical`]: crate::align::vertical
125pub trait VerticalAlignment: Alignment {}
embedded_layout/align/mod.rs

embedded_layout/align/
mod.rs
