Deprecate ui.set_enabled and set_visbile (emilk#4614)

These were confusing, because `set_enabled(true)` and `set_visible(true)` did nothing. Instead use one of: * `ui.add_enabled`, `ui.add_enabled_ui` or `ui.disable()` * `ui.add_visible`, `ui.add_visible_ui` or `ui.set_invisible()` * Closes emilk#4327
hacknus · Oct 30, 2024 · 9e38ec5 · 9e38ec5
1 parent 03e39f0
commit 9e38ec5
Show file tree

Hide file tree

Showing 5 changed files with 86 additions and 15 deletions.
diff --git a/crates/egui/src/containers/area.rs b/crates/egui/src/containers/area.rs
@@ -525,7 +525,9 @@ impl Prepared {
             }
         }
 
-        ui.set_enabled(self.enabled);
+        if !self.enabled {
+            ui.disable();
+        }
         if self.sizing_pass {
             ui.set_sizing_pass();
         }

diff --git a/crates/egui/src/containers/collapsing_header.rs b/crates/egui/src/containers/collapsing_header.rs
@@ -429,7 +429,7 @@ impl CollapsingHeader {
 
     /// If you set this to `false`, the [`CollapsingHeader`] will be grayed out and un-clickable.
     ///
-    /// This is a convenience for [`Ui::set_enabled`].
+    /// This is a convenience for [`Ui::disable`].
     #[inline]
     pub fn enabled(mut self, enabled: bool) -> Self {
         self.enabled = enabled;
@@ -616,7 +616,9 @@ impl CollapsingHeader {
         // Make sure body is bellow header,
         // and make sure it is one unit (necessary for putting a [`CollapsingHeader`] in a grid).
         ui.vertical(|ui| {
-            ui.set_enabled(self.enabled);
+            if !self.enabled {
+                ui.disable();
+            }
 
             let Prepared {
                 header_response,

diff --git a/crates/egui/src/ui.rs b/crates/egui/src/ui.rs
@@ -208,7 +208,7 @@ impl Ui {
     #[inline]
     pub fn set_sizing_pass(&mut self) {
         self.sizing_pass = true;
-        self.set_visible(false);
+        self.set_invisible();
     }
 
     /// Set to true in special cases where we do one frame
@@ -328,6 +328,36 @@ impl Ui {
         self.enabled
     }
 
+    /// Calling `disable()` will cause the [`Ui`] to deny all future interaction
+    /// and all the widgets will draw with a gray look.
+    ///
+    /// Usually it is more convenient to use [`Self::add_enabled_ui`] or [`Self::add_enabled`].
+    ///
+    /// Note that once disabled, there is no way to re-enable the [`Ui`].
+    ///
+    /// ### Example
+    /// ```
+    /// # egui::__run_test_ui(|ui| {
+    /// # let mut enabled = true;
+    /// ui.group(|ui| {
+    ///     ui.checkbox(&mut enabled, "Enable subsection");
+    ///     if !enabled {
+    ///         ui.disable();
+    ///     }
+    ///     if ui.button("Button that is not always clickable").clicked() {
+    ///         /* … */
+    ///     }
+    /// });
+    /// # });
+    /// ```
+    pub fn disable(&mut self) {
+        self.enabled = false;
+        if self.is_visible() {
+            self.painter
+                .set_fade_to_color(Some(self.visuals().fade_out_to_color()));
+        }
+    }
+
     /// Calling `set_enabled(false)` will cause the [`Ui`] to deny all future interaction
     /// and all the widgets will draw with a gray look.
     ///
@@ -348,11 +378,10 @@ impl Ui {
     /// });
     /// # });
     /// ```
+    #[deprecated = "Use disable(), add_enabled_ui(), or add_enabled() instead"]
     pub fn set_enabled(&mut self, enabled: bool) {
-        self.enabled &= enabled;
-        if !self.enabled && self.is_visible() {
-            self.painter
-                .set_fade_to_color(Some(self.visuals().fade_out_to_color()));
+        if !enabled {
+            self.disable();
         }
     }
 
@@ -362,6 +391,35 @@ impl Ui {
         self.painter.is_visible()
     }
 
+    /// Calling `set_invisible()` will cause all further widgets to be invisible,
+    /// yet still allocate space.
+    ///
+    /// The widgets will not be interactive (`set_invisible()` implies `disable()`).
+    ///
+    /// Once invisible, there is no way to make the [`Ui`] visible again.
+    ///
+    /// Usually it is more convenient to use [`Self::add_visible_ui`] or [`Self::add_visible`].
+    ///
+    /// ### Example
+    /// ```
+    /// # egui::__run_test_ui(|ui| {
+    /// # let mut visible = true;
+    /// ui.group(|ui| {
+    ///     ui.checkbox(&mut visible, "Show subsection");
+    ///     if !visible {
+    ///         ui.set_invisible();
+    ///     }
+    ///     if ui.button("Button that is not always shown").clicked() {
+    ///         /* … */
+    ///     }
+    /// });
+    /// # });
+    /// ```
+    pub fn set_invisible(&mut self) {
+        self.painter.set_invisible();
+        self.disable();
+    }
+
     /// Calling `set_visible(false)` will cause all further widgets to be invisible,
     /// yet still allocate space.
     ///
@@ -382,10 +440,11 @@ impl Ui {
     /// });
     /// # });
     /// ```
+    #[deprecated = "Use set_invisible(), add_visible_ui(), or add_visible() instead"]
     pub fn set_visible(&mut self, visible: bool) {
-        self.set_enabled(visible);
         if !visible {
             self.painter.set_invisible();
+            self.disable();
         }
     }
 
@@ -1299,7 +1358,7 @@ impl Ui {
     pub fn add_enabled(&mut self, enabled: bool, widget: impl Widget) -> Response {
         if self.is_enabled() && !enabled {
             let old_painter = self.painter.clone();
-            self.set_enabled(false);
+            self.disable();
             let response = self.add(widget);
             self.enabled = true;
             self.painter = old_painter;
@@ -1334,7 +1393,9 @@ impl Ui {
         add_contents: impl FnOnce(&mut Ui) -> R,
     ) -> InnerResponse<R> {
         self.scope(|ui| {
-            ui.set_enabled(enabled);
+            if !enabled {
+                ui.disable();
+            }
             add_contents(ui)
         })
     }
@@ -1359,7 +1420,7 @@ impl Ui {
             let old_painter = self.painter.clone();
             let old_enabled = self.enabled;
 
-            self.set_visible(false);
+            self.set_invisible();
 
             let response = self.add(widget);
 
@@ -1396,7 +1457,9 @@ impl Ui {
         add_contents: impl FnOnce(&mut Ui) -> R,
     ) -> InnerResponse<R> {
         self.scope(|ui| {
-            ui.set_visible(visible);
+            if !visible {
+                ui.set_invisible();
+            }
             add_contents(ui)
         })
     }

diff --git a/crates/egui_demo_lib/src/demo/widget_gallery.rs b/crates/egui_demo_lib/src/demo/widget_gallery.rs
@@ -62,7 +62,9 @@ impl super::Demo for WidgetGallery {
 impl super::View for WidgetGallery {
     fn ui(&mut self, ui: &mut egui::Ui) {
         ui.add_enabled_ui(self.enabled, |ui| {
-            ui.set_visible(self.visible);
+            if !self.visible {
+                ui.set_invisible();
+            }
             ui.multiply_opacity(self.opacity);
 
             egui::Grid::new("my_grid")

diff --git a/crates/egui_demo_lib/src/demo/window_options.rs b/crates/egui_demo_lib/src/demo/window_options.rs
@@ -115,7 +115,9 @@ impl super::View for WindowOptions {
             ui.group(|ui| {
                 ui.vertical(|ui| {
                     ui.checkbox(anchored, "anchored");
-                    ui.set_enabled(*anchored);
+                    if !*anchored {
+                        ui.disable();
+                    }
                     ui.horizontal(|ui| {
                         ui.label("x:");
                         ui.selectable_value(&mut anchor[0], egui::Align::LEFT, "Left");