Add AtomLayout, abstracing layouting within widgets

Cargo.lock

@@ -1263,6 +1263,7 @@ dependencies = [
  "profiling",
  "ron",
  "serde",
+ "smallvec",
  "unicode-segmentation",
 ]
 

Cargo.toml

@@ -98,6 +98,7 @@ raw-window-handle = "0.6.0"
 ron = "0.10.1"
 serde = { version = "1", features = ["derive"] }
 similar-asserts = "1.4.2"
+smallvec = "1"
 thiserror = "1.0.37"
 type-map = "0.5.0"
 unicode-segmentation = "1.12.0"

crates/egui/Cargo.toml

@@ -87,6 +87,7 @@ ahash.workspace = true
 bitflags.workspace = true
 nohash-hasher.workspace = true
 profiling.workspace = true
+smallvec.workspace = true
 unicode-segmentation.workspace = true
 
 #! ### Optional dependencies

crates/egui/src/atomics/atom.rs

@@ -0,0 +1,109 @@
+use crate::{AtomKind, Id, SizedAtom, Ui};
+use emath::{NumExt as _, Vec2};
+use epaint::text::TextWrapMode;
+
+/// A low-level ui building block.
+///
+/// Implements [`From`] for [`String`], [`str`], [`crate::Image`] and much more for convenience.
+/// You can directly call the `atom_*` methods on anything that implements `Into<Atom>`.
+/// ```
+/// # use egui::{Image, emath::Vec2};
+/// use egui::AtomExt as _;
+/// let string_atom = "Hello".atom_grow(true);
+/// let image_atom = Image::new("some_image_url").atom_size(Vec2::splat(20.0));
+/// ```
+#[derive(Clone, Debug)]
+pub struct Atom<'a> {
+    /// See [`crate::AtomExt::atom_size`]
+    pub size: Option<Vec2>,
+
+    /// See [`crate::AtomExt::atom_max_size`]
+    pub max_size: Vec2,
+
+    /// See [`crate::AtomExt::atom_grow`]
+    pub grow: bool,
+
+    /// See [`crate::AtomExt::atom_shrink`]
+    pub shrink: bool,
+
+    /// The atom type
+    pub kind: AtomKind<'a>,
+}
+
+impl Default for Atom<'_> {
+    fn default() -> Self {
+        Atom {
+            size: None,
+            max_size: Vec2::INFINITY,
+            grow: false,
+            shrink: false,
+            kind: AtomKind::Empty,
+        }
+    }
+}
+
+impl<'a> Atom<'a> {
+    /// Create an empty [`Atom`] marked as `grow`.
+    ///
+    /// This will expand in size, allowing all preceding atoms to be left-aligned,
+    /// and all following atoms to be right-aligned
+    pub fn grow() -> Self {
+        Atom {
+            grow: true,
+            ..Default::default()
+        }
+    }
+
+    /// Create a [`AtomKind::Custom`] with a specific size.
+    pub fn custom(id: Id, size: impl Into<Vec2>) -> Self {
+        Atom {
+            size: Some(size.into()),
+            kind: AtomKind::Custom(id),
+            ..Default::default()
+        }
+    }
+
+    /// Turn this into a [`SizedAtom`].
+    pub fn into_sized(
+        self,
+        ui: &Ui,
+        mut available_size: Vec2,
+        mut wrap_mode: Option<TextWrapMode>,
+    ) -> SizedAtom<'a> {
+        if !self.shrink && self.max_size.x.is_infinite() {
+            wrap_mode = Some(TextWrapMode::Extend);
+        }
+        available_size = available_size.at_most(self.max_size);
+        if let Some(size) = self.size {
+            available_size = available_size.at_most(size);
+        }
+        if self.max_size.x.is_finite() {
+            wrap_mode = Some(TextWrapMode::Truncate);
+        }
+
+        let (preferred, kind) = self.kind.into_sized(ui, available_size, wrap_mode);
+
+        let size = self
+            .size
+            .map_or_else(|| kind.size(), |s| s.at_most(self.max_size));
+
+        SizedAtom {
+            size,
+            preferred_size: preferred,
+            grow: self.grow,
+            kind,
+        }
+    }
+}
+
+impl<'a, T> From<T> for Atom<'a>
+where
+    T: Into<AtomKind<'a>>,
+{
+    fn from(value: T) -> Self {
+        Atom {
+            kind: value.into(),
+            ..Default::default()
+        }
+    }
+}

crates/egui/src/atomics/atom_ext.rs

@@ -0,0 +1,107 @@
+use crate::{Atom, FontSelection, Ui};
+use emath::Vec2;
+
+/// A trait for conveniently building [`Atom`]s.
+///
+/// The functions are prefixed with `atom_` to avoid conflicts with e.g. [`crate::RichText::size`].
+pub trait AtomExt<'a> {
+    /// Set the atom to a fixed size.
+    ///
+    /// If [`Atom::grow`] is `true`, this will be the minimum width.
+    /// If [`Atom::shrink`] is `true`, this will be the maximum width.
+    /// If both are true, the width will have no effect.
+    ///
+    /// [`Self::atom_max_size`] will limit size.
+    ///
+    /// See [`crate::AtomKind`] docs to see how the size affects the different types.
+    fn atom_size(self, size: Vec2) -> Atom<'a>;
+
+    /// Grow this atom to the available space.
+    ///
+    /// This will affect the size of the [`Atom`] in the main direction. Since
+    /// [`crate::AtomLayout`] today only supports horizontal layout, it will affect the width.
+    ///
+    /// You can also combine this with [`Self::atom_shrink`] to make it always take exactly the
+    /// remaining space.
+    fn atom_grow(self, grow: bool) -> Atom<'a>;
+
+    /// Shrink this atom if there isn't enough space.
+    ///
+    /// This will affect the size of the [`Atom`] in the main direction. Since
+    /// [`crate::AtomLayout`] today only supports horizontal layout, it will affect the width.
+    ///
+    /// NOTE: Only a single [`Atom`] may shrink for each widget.
+    ///
+    /// If no atom was set to shrink and `wrap_mode != TextWrapMode::Extend`, the first
+    /// `AtomKind::Text` is set to shrink.
+    fn atom_shrink(self, shrink: bool) -> Atom<'a>;
+
+    /// Set the maximum size of this atom.
+    ///
+    /// Will not affect the space taken by `grow` (All atoms marked as grow will always grow
+    /// equally to fill the available space).
+    fn atom_max_size(self, max_size: Vec2) -> Atom<'a>;
+
+    /// Set the maximum width of this atom.
+    ///
+    /// Will not affect the space taken by `grow` (All atoms marked as grow will always grow
+    /// equally to fill the available space).
+    fn atom_max_width(self, max_width: f32) -> Atom<'a>;
+
+    /// Set the maximum height of this atom.
+    fn atom_max_height(self, max_height: f32) -> Atom<'a>;
+
+    /// Set the max height of this atom to match the font size.
+    ///
+    /// This is useful for e.g. limiting the height of icons in buttons.
+    fn atom_max_height_font_size(self, ui: &Ui) -> Atom<'a>
+    where
+        Self: Sized,
+    {
+        let font_selection = FontSelection::default();
+        let font_id = font_selection.resolve(ui.style());
+        let height = ui.fonts(|f| f.row_height(&font_id));
+        self.atom_max_height(height)
+    }
+}
+
+impl<'a, T> AtomExt<'a> for T
+where
+    T: Into<Atom<'a>> + Sized,
+{
+    fn atom_size(self, size: Vec2) -> Atom<'a> {
+        let mut atom = self.into();
+        atom.size = Some(size);
+        atom
+    }
+
+    fn atom_grow(self, grow: bool) -> Atom<'a> {
+        let mut atom = self.into();
+        atom.grow = grow;
+        atom
+    }
+
+    fn atom_shrink(self, shrink: bool) -> Atom<'a> {
+        let mut atom = self.into();
+        atom.shrink = shrink;
+        atom
+    }
+
+    fn atom_max_size(self, max_size: Vec2) -> Atom<'a> {
+        let mut atom = self.into();
+        atom.max_size = max_size;
+        atom
+    }
+
+    fn atom_max_width(self, max_width: f32) -> Atom<'a> {
+        let mut atom = self.into();
+        atom.max_size.x = max_width;
+        atom
+    }
+
+    fn atom_max_height(self, max_height: f32) -> Atom<'a> {
+        let mut atom = self.into();
+        atom.max_size.y = max_height;
+        atom
+    }
+}

crates/egui/src/atomics/atom_kind.rs

@@ -0,0 +1,120 @@
+use crate::{Id, Image, ImageSource, SizedAtomKind, TextStyle, Ui, WidgetText};
+use emath::Vec2;
+use epaint::text::TextWrapMode;
+
+/// The different kinds of [`crate::Atom`]s.
+#[derive(Clone, Default, Debug)]
+pub enum AtomKind<'a> {
+    /// Empty, that can be used with [`crate::AtomExt::atom_grow`] to reserve space.
+    #[default]
+    Empty,
+
+    /// Text atom.
+    ///
+    /// Truncation within [`crate::AtomLayout`] works like this:
+    /// -
+    /// - if `wrap_mode` is not Extend
+    ///   - if no atom is `shrink`
+    ///     - the first text atom is selected and will be marked as `shrink`
+    ///   - the atom marked as `shrink` will shrink / wrap based on the selected wrap mode
+    ///   - any other text atoms will have `wrap_mode` extend
+    /// - if `wrap_mode` is extend, Text will extend as expected.
+    ///
+    /// Unless [`crate::AtomExt::atom_max_width`] is set, `wrap_mode` should only be set via [`crate::Style`] or
+    /// [`crate::AtomLayout::wrap_mode`], as setting a wrap mode on a [`WidgetText`] atom
+    /// that is not `shrink` will have unexpected results.
+    ///
+    /// The size is determined by converting the [`WidgetText`] into a galley and using the galleys
+    /// size. You can use [`crate::AtomExt::atom_size`] to override this, and [`crate::AtomExt::atom_max_width`]
+    /// to limit the width (Causing the text to wrap or truncate, depending on the `wrap_mode`.
+    /// [`crate::AtomExt::atom_max_height`] has no effect on text.
+    Text(WidgetText),
+
+    /// Image atom.
+    ///
+    /// By default the size is determined via [`Image::calc_size`].
+    /// You can use [`crate::AtomExt::atom_max_size`] or [`crate::AtomExt::atom_size`] to customize the size.
+    /// There is also a helper [`crate::AtomExt::atom_max_height_font_size`] to set the max height to the
+    /// default font height, which is convenient for icons.
+    Image(Image<'a>),
+
+    /// For custom rendering.
+    ///
+    /// You can get the [`crate::Rect`] with the [`Id`] from [`crate::AtomLayoutResponse`] and use a
+    /// [`crate::Painter`] or [`Ui::put`] to add/draw some custom content.
+    ///
+    /// Example:
+    /// ```
+    /// # use egui::{AtomExt, AtomKind, Atom, Button, Id, __run_test_ui};
+    /// # use emath::Vec2;
+    /// # __run_test_ui(|ui| {
+    /// let id = Id::new("my_button");
+    /// let response = Button::new(("Hi!", Atom::custom(id, Vec2::splat(18.0)))).atom_ui(ui);
+    ///
+    /// let rect = response.rect(id);
+    /// if let Some(rect) = rect {
+    ///     ui.put(rect, Button::new("⏵"));
+    /// }
+    /// # });
+    /// ```
+    Custom(Id),
+}
+
+impl<'a> AtomKind<'a> {
+    pub fn text(text: impl Into<WidgetText>) -> Self {
+        AtomKind::Text(text.into())
+    }
+
+    pub fn image(image: impl Into<Image<'a>>) -> Self {
+        AtomKind::Image(image.into())
+    }
+
+    /// Turn this [`AtomKind`] into a [`SizedAtomKind`].
+    ///
+    /// This converts [`WidgetText`] into [`crate::Galley`] and tries to load and size [`Image`].
+    /// The first returned argument is the preferred size.
+    pub fn into_sized(
+        self,
+        ui: &Ui,
+        available_size: Vec2,
+        wrap_mode: Option<TextWrapMode>,
+    ) -> (Vec2, SizedAtomKind<'a>) {
+        match self {
+            AtomKind::Text(text) => {
+                let galley = text.into_galley(ui, wrap_mode, available_size.x, TextStyle::Button);
+                (
+                    galley.size(), // TODO(#5762): calculate the preferred size
+                    SizedAtomKind::Text(galley),
+                )
+            }
+            AtomKind::Image(image) => {
+                let size = image.load_and_calc_size(ui, available_size);
+                let size = size.unwrap_or(Vec2::ZERO);
+                (size, SizedAtomKind::Image(image, size))
+            }
+            AtomKind::Custom(id) => (Vec2::ZERO, SizedAtomKind::Custom(id)),
+            AtomKind::Empty => (Vec2::ZERO, SizedAtomKind::Empty),
+        }
+    }
+}
+
+impl<'a> From<ImageSource<'a>> for AtomKind<'a> {
+    fn from(value: ImageSource<'a>) -> Self {
+        AtomKind::Image(value.into())
+    }
+}
+
+impl<'a> From<Image<'a>> for AtomKind<'a> {
+    fn from(value: Image<'a>) -> Self {
+        AtomKind::Image(value)
+    }
+}
+
+impl<T> From<T> for AtomKind<'_>
+where
+    T: Into<WidgetText>,
+{
+    fn from(value: T) -> Self {
+        AtomKind::Text(value.into())
+    }
+}