Add `AtomicLayout`, abstracing layouting within widgets #5830

lucasmerlin · 2025-03-20T12:29:04Z

Today each widget does its own custom layout, which has some drawbacks:

not very flexible
- you can add an Image to Button but it will always be shown on the left side
- you can't add a Image to a e.g. a SelectableLabel
a lot of duplicated code

This PR introduces Atomics and AtomicLayout which abstracts over "widget content" and layout within widgets, so it'd be possible to add images / text / custom rendering (for e.g. the checkbox) to any widget.

A simple custom button implementation is now as easy as this:

pub struct ALButton<'a> {
    al: AtomicLayout<'a>,
}

impl<'a> ALButton<'a> {
    pub fn new(content: impl IntoAtomics) -> Self {
        Self { al: content.into_atomics() }
    }
}

impl<'a> Widget for ALButton<'a> {
    fn ui(mut self, ui: &mut Ui) -> Response {
        let response = ui.ctx().read_response(ui.next_auto_id());

        let visuals = response.map_or(&ui.style().visuals.widgets.inactive, |response| {
            ui.style().interact(&response)
        });

        self.al.frame = self
            .al
            .frame
            .inner_margin(ui.style().spacing.button_padding)
            .fill(visuals.bg_fill)
            .stroke(visuals.bg_stroke)
            .corner_radius(visuals.corner_radius);

        self.al.show(ui)
    }
}

The initial implementation only does very basic layout, just enough to be able to implement most current egui widgets, so:

only horizontal layout
everything is centered
a single item may grow/shrink based on the available space
everything can be contained in a Frame

There is a trait IntoAtomics that conveniently allows you to construct Atomics from a tuple

   ui.button((Image::new("image.png"), "Click me!"))

to get a button with image and text.

This PR reimplements three egui widgets based on the new AtomicLayout:

Button
- matches the old button pixel-by-pixel
- Button with image is now properly aligned in justified layouts
- selected button style now matches SelecatbleLabel look
- For some reason the DragValue text seems shifted by a pixel almost everywhere, but I think it's more centered now, yay?
Checkbox
- basically pixel-perfect but apparently the check mesh is very slightly different so I had to update the snapshot
- somehow needs a bit more space in some snapshot tests?
RadioButton
- pixel-perfect
- somehow needs a bit more space in some snapshot tests?

I plan on updating TextEdit based on AtomicLayout in a separate PR (so you could use it to add a icon within the textedit frame).

github-actions · 2025-03-20T12:35:04Z

Preview available at https://egui-pr-preview.github.io/pr/5830-lucasexperimentswidgetlayout
Note that it might take a couple seconds for the update to show up after the preview_build workflow has completed.

This is mostly in preparation for #5830 where I want to ensure that I don't introduce any regressions

crates/egui/src/lib.rs

crates/egui/src/style.rs

tests/egui_tests/tests/snapshots/layout/checkbox_checked.png

emilk

Please run some benchmarks (the ones that are already there, and maybe some new ones more focused on e.g. just Button)

emilk · 2025-04-24T12:57:46Z

crates/egui_kittest/tests/menu.rs

@@ -99,7 +99,7 @@ fn menu_close_on_click_outside() {
    harness.run();

    harness
-        .get_by_label("Submenu C (CloseOnClickOutside)")
+        .get_by_label_contains("Submenu C (CloseOnClickOutside)")


Does the label not contain more than just the text?

I added a todo for this here:
https://github.com/emilk/egui/pull/5830/files#diff-7fd879073a3ce1839ef5c8fdd4dc5e50afc139c018b71c35ca5660bf89420470R657-R673

The text now unfortunately contains the ⏵ from the submenu button. Not sure what a good solution is to handle this. Maybe a flag on the Atomic? Maybe the Atomic could have a alt_text you could use for images, and if you add a text like ⏵ you could do "⏵".a_alt_text("") or something like that.
This would also solve accessibility for Icon Fonts.

crates/egui/src/widgets/button.rs

crates/egui/src/widgets/checkbox.rs

emilk · 2025-04-24T13:21:28Z

Remember to run cargo doc -p egui --open and check the docs for the new top-level types. Some are missing, some are bad

crates/egui/src/lib.rs

crates/egui/src/atomic_layout.rs

…ew Atomics

…h the current one. - offset frame margin for stroke width - handle expansion - add min_size - calculate image size based on font height - correctly handle alignment / ui layout

* In preparation of #5830, this should reduce the performance impact of that PR --------- Co-authored-by: Emil Ernerfeldt <[email protected]>

# Conflicts: # crates/egui/src/widgets/button.rs

lucasmerlin · 2025-05-07T10:24:36Z

Should it be Atomic or Atom? 🤔

…implement it as fallback for old Button::image methods instead

lucasmerlin · 2025-05-08T10:23:57Z

Ran the demo benchmark for main and the PR and it seems to be slightly slower but I feel the slow down is acceptable for the features we gain:

	Demo Realistic	Demo No Tesselate	Demo Only Tesselate
Master	109.83 µs	73.938 µs	38.209 µs
Atomics	112.93 µs	75.127 µs	38.099 µs

See this comment for the button benchmark results.

emilk · 2025-05-08T11:19:16Z

crates/egui/Cargo.toml

@@ -87,6 +87,7 @@ ahash.workspace = true
 bitflags.workspace = true
 nohash-hasher.workspace = true
 profiling.workspace = true
+smallvec.workspace = true


emilk · 2025-05-08T11:23:12Z

crates/egui/src/atomics/atomic.rs

+    pub grow: bool,
+    pub shrink: bool,


These should have docstrings:

What dimension can grow/shrink?

What happens if they are both set?

Can the atomic grow beyond the max_size?

How does it interact with size?

…

emilk · 2025-05-08T11:28:15Z

tests/egui_tests/tests/snapshots/layout/button_image.png

Unrelated to this PR: I suspect this grid would be a lot easier to read if we replaced all cross_/main_ with horiz_/vert_ instead, e.g. so that the rightmost column is always horiz_align: Right

emilk · 2025-05-08T11:34:38Z

crates/egui/src/widgets/checkbox.rs


-            (Some(galley), desired_size)
-        };
+        let text = atomics.text();


We can use Cow here to avoid allocations in the common case of there being only one (or zero) AtomicKind::Text in Atomics. That should save an allocation for each widget, which could be quite significant

emilk · 2025-05-08T11:36:35Z

crates/egui/src/containers/menu.rs

@@ -243,8 +243,8 @@ pub struct MenuButton<'a> {
 }

 impl<'a> MenuButton<'a> {
-    pub fn new(text: impl Into<WidgetText>) -> Self {
-        Self::from_button(Button::new(text))
+    pub fn new(text: impl IntoAtomics<'a>) -> Self {


We should probably rename text to atoms here and elsewhere

emilk · 2025-05-08T11:39:18Z

crates/egui/src/atomics/atomic_kind.rs

+            AtomicKind::Text(text) => {
+                let galley = text.into_galley(ui, wrap_mode, available_size.x, TextStyle::Button);
+                (
+                    galley.size(), // TODO(lucasmerlin): calculate the preferred size


It would be nice to link this TODO to a issue

emilk · 2025-05-08T11:53:06Z

crates/egui/src/atomics/atomic_layout.rs

+///
+/// You can use this to first allocate a response and then modify, e.g., the [`Frame`] on the
+/// [`AllocatedAtomicLayout`] for interaction styling.
+pub struct AtomicLayout<'a> {


AtomicLayout is 432 bytes now. Most of that is Atomics (360 bytes), because it has a SmallVec 2x of Atomic (176 bytes), most of which is Image (152 bytes).

Not something we need to fix right now; I just wanted to investigate it a bit.

A quick fix would be to change AtomicKind::Image into a Box<Image>, i.e. optimize for the case where there is no image. That shrinks AtomicLayout from 432 to to 176 bytes, a 60% reduction.

emilk · 2025-05-08T11:56:01Z

crates/egui/src/atomics/atomic_layout.rs

+    /// Set the minimum size of the Widget.
+    #[inline]


Suggested change

/// Set the minimum size of the Widget.

#[inline]

/// Set the minimum size of the Widget.

///

/// This will find and expand atoms with `grow: true`.

/// If there are no growable atoms then everything will be left-aligned.

#[inline]

emilk · 2025-05-08T12:00:14Z

crates/egui/src/widgets/button.rs

+        self.layout.push_left(Atomic::grow());
+        self.layout.push_left(atomic);


shouldn't this be push_right?

emilk · 2025-05-08T12:00:33Z

crates/egui/src/widgets/button.rs

+        self.layout.push_left(Atomic::grow());
+        self.layout.push_left(right_text.into());


This definitely should be .push_right. I think you just named the function wrong.

emilk · 2025-05-08T12:33:18Z

crates/egui/src/atomics/atomic_layout.rs

+        let grow_width = f32::max(extra_space / grow_count as f32, 0.0).floor_ui();
+
+        let aligned_rect = if grow_count > 0 {
+            align2.align_size_within_rect(Vec2::new(width_to_fill, desired_size.y), inner_rect)
+        } else {
+            align2.align_size_within_rect(desired_size, inner_rect)
+        };
+
+        let mut cursor = aligned_rect.left();
+
+        let mut response = AtomicLayoutResponse::empty(response);
+
+        for sized in sized_atomics {
+            let size = sized.size;
+            let growth = if sized.is_grow() { grow_width } else { 0.0 };


There is a subtle sizing issue lurking here, that it might be worth thinking about. Assume .round_ui rounds to integers for now (makes it easier to explain the problem):

If extra_space is 7, and we have 3 growable atoms, then the current code will grow each of those atoms by 2, leading to a total growth of 6, which is less than extra_space. Is that fine? Maybe. But a better (though more complicated) approach might be to handle this by allowing the last atom to grow more or less than the others.

emilk · 2025-05-08T12:34:29Z

crates/egui/src/atomics/atomic_layout.rs

+///
+/// Use the `custom_rects` together with [`AtomicKind::Custom`] to add child widgets to a widget.
+///
+/// NOTE: Don't `unwrap` rects, they might be empty when the widget is not visible.


This comment makes more sense on fn get_rect

emilk · 2025-05-08T12:34:56Z

crates/egui/src/atomics/atomic_layout.rs

+        self.custom_rects.iter().copied()
+    }
+
+    pub fn get_rect(&self, id: Id) -> Option<Rect> {


This should have a warning about that the id might be missing for hidden/invisible widgets

emilk · 2025-05-08T12:35:17Z

crates/egui/src/atomics/atomic_layout.rs

+        self.custom_rects.iter().copied()
+    }
+
+    pub fn get_rect(&self, id: Id) -> Option<Rect> {


https://rust-lang.github.io/api-guidelines/naming.html#getter-names-follow-rust-convention-c-getter

Suggested change

pub fn get_rect(&self, id: Id) -> Option<Rect> {

pub fn rect(&self, id: Id) -> Option<Rect> {

lucasmerlin mentioned this pull request Mar 20, 2025

Measure intrinsic_size in Placer #5831

Draft

lucasmerlin mentioned this pull request Apr 15, 2025

Add tests for layout and visuals of most egui widgets #6752

Merged

lucasmerlin added a commit that referenced this pull request Apr 16, 2025

Add tests for layout and visuals of most egui widgets (#6752)

501905b

This is mostly in preparation for #5830 where I want to ensure that I don't introduce any regressions

lucasmerlin force-pushed the lucas/experiments/widget_layout branch from 9b01154 to d468565 Compare April 16, 2025 22:00

lucasmerlin added feature New feature or request egui labels Apr 23, 2025

lucasmerlin marked this pull request as ready for review April 24, 2025 09:32

lucasmerlin commented Apr 24, 2025

View reviewed changes

crates/egui/src/lib.rs Outdated Show resolved Hide resolved

lucasmerlin commented Apr 24, 2025

View reviewed changes

crates/egui/src/style.rs Outdated Show resolved Hide resolved

lucasmerlin requested a review from emilk April 24, 2025 09:52

lucasmerlin changed the title ~~Add AtomicLayout that abstracts layouting within widgets~~ Add AtomicLayout, abstracing layouting within widgets Apr 24, 2025