Replace Context::begin_frame/end_frame with fn run taking a closu…

…re (#872) * Replace Context begin_frame/end_frame with `fn run` taking a closure * Create `egui::__run_test_ui` to replace `Ui::__test` * Add helper `egui::__run_test_ctx` for doctests
emilk · Nov 3, 2021 · 49e4388 · 49e4388
1 parent e54106e
commit 49e4388
Show file tree

Hide file tree

Showing 32 changed files with 294 additions and 199 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,8 @@ NOTE: [`epaint`](epaint/CHANGELOG.md), [`eframe`](eframe/CHANGELOG.md), [`egui_w
 ### Changed 🔧
 * Unifiy the four `Memory` data buckets (`data`, `data_temp`, `id_data` and `id_data_temp`) into a single `Memory::data`, with a new interface ([#836](https://github.com/emilk/egui/pull/836)).
 * `ui.add(Button::new("…").text_color(…))` is now `ui.button(RichText::new("…").color(…))` (same for `Label` )([#855](https://github.com/emilk/egui/pull/855)).
+* Replace `CtxRef::begin_frame` and `end_frame` with `CtxRef::run` ([#872](https://github.com/emilk/egui/pull/872)).
+* Replace `Ui::__test` with `egui::__run_test_ui` ([#872](https://github.com/emilk/egui/pull/872)).
 
 ### Contributors 🙏
 * [mankinskin](https://github.com/mankinskin) ([#543](https://github.com/emilk/egui/pull/543))

diff --git a/README.md b/README.md
@@ -198,14 +198,14 @@ Missing an integration for the thing you're working on? Create one, it is easy!
 You need to collect [`egui::RawInput`](https://docs.rs/egui/latest/egui/struct.RawInput.html), paint [`egui::ClippedMesh`](https://docs.rs/epaint/):es and handle [`egui::Output`](https://docs.rs/egui/latest/egui/struct.Output.html). The basic structure is this:
 
 ``` rust
-let mut egui_ctx = egui::Context::new();
+let mut egui_ctx = egui::CtxRef::default();
 
 // Game loop:
 loop {
     let raw_input: egui::RawInput = my_integration.gather_input();
-    egui_ctx.begin_frame(raw_input);
-    my_app.ui(&mut egui_ctx); // add panels, windows and widgets to `egui_ctx` here
-    let (output, shapes) = egui_ctx.end_frame();
+    let (output, shapes) = egui_ctx.run(raw_input, |egui_ctx| {
+        my_app.ui(egui_ctx); // add panels, windows and widgets to `egui_ctx` here
+    });
     let clipped_meshes = egui_ctx.tessellate(shapes); // create triangles to paint
     my_integration.paint(clipped_meshes);
     my_integration.set_cursor_icon(output.cursor_icon);

diff --git a/egui-winit/src/epi.rs b/egui-winit/src/epi.rs
@@ -282,8 +282,6 @@ impl EpiIntegration {
 
         let raw_input = self.egui_winit.take_egui_input(window);
 
-        self.egui_ctx.begin_frame(raw_input);
-
         let mut app_output = epi::backend::AppOutput::default();
         let mut frame = epi::backend::FrameBuilder {
             info: integration_info(self.integration_name, window, self.latest_frame_time),
@@ -293,9 +291,11 @@ impl EpiIntegration {
         }
         .build();
 
-        self.app.update(&self.egui_ctx, &mut frame);
+        let app = &mut self.app; // TODO: remove when we update MSVR to 1.56
+        let (egui_output, shapes) = self.egui_ctx.run(raw_input, |egui_ctx| {
+            app.update(egui_ctx, &mut frame);
+        });
 
-        let (egui_output, shapes) = self.egui_ctx.end_frame();
         let needs_repaint = egui_output.needs_repaint;
         self.egui_winit
             .handle_output(window, &self.egui_ctx, egui_output);

diff --git a/egui/src/containers/area.rs b/egui/src/containers/area.rs
@@ -33,14 +33,13 @@ impl State {
 /// This forms the base of the [`Window`] container.
 ///
 /// ```
-/// # let mut ctx = egui::CtxRef::default();
-/// # ctx.begin_frame(Default::default());
-/// # let ctx = &ctx;
+/// # egui::__run_test_ctx(|ctx| {
 /// egui::Area::new("my_area")
 ///     .fixed_pos(egui::pos2(32.0, 32.0))
 ///     .show(ctx, |ui| {
 ///         ui.label("Floating text!");
 ///     });
+/// # });
 #[must_use = "You should call .show()"]
 #[derive(Clone, Copy, Debug)]
 pub struct Area {

diff --git a/egui/src/containers/collapsing_header.rs b/egui/src/containers/collapsing_header.rs
@@ -130,14 +130,15 @@ pub(crate) fn paint_icon(ui: &mut Ui, openness: f32, response: &Response) {
 ///
 ///
 /// ```
-/// # let ui = &mut egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// egui::CollapsingHeader::new("Heading")
 ///     .show(ui, |ui| {
 ///         ui.label("Contents");
 ///     });
 ///
 /// // Short version:
 /// ui.collapsing("Heading", |ui| { ui.label("Contents"); });
+/// # });
 /// ```
 #[must_use = "You should call .show()"]
 pub struct CollapsingHeader {
@@ -210,7 +211,7 @@ impl CollapsingHeader {
     ///
     /// Example:
     /// ```
-    /// # let ui = &mut egui::Ui::__test();
+    /// # egui::__run_test_ui(|ui| {
     /// let mut selected = false;
     /// let response = egui::CollapsingHeader::new("Select and open me")
     ///     .selectable(true)
@@ -219,6 +220,7 @@ impl CollapsingHeader {
     /// if response.header_response.clicked() {
     ///     selected = true;
     /// }
+    /// # });
     /// ```
     pub fn selected(mut self, selected: bool) -> Self {
         self.selected = selected;
@@ -229,8 +231,9 @@ impl CollapsingHeader {
     ///
     /// To show it behind all `CollapsingHeader` you can just use:
     /// ```
-    /// # let ui = &mut egui::Ui::__test();
+    /// # egui::__run_test_ui(|ui| {
     /// ui.visuals_mut().collapsing_header_frame = true;
+    /// # });
     /// ```
     pub fn show_background(mut self, show_background: bool) -> Self {
         self.show_background = show_background;

diff --git a/egui/src/containers/combo_box.rs b/egui/src/containers/combo_box.rs
@@ -7,7 +7,7 @@ use epaint::Shape;
 /// # #[derive(Debug, PartialEq)]
 /// # enum Enum { First, Second, Third }
 /// # let mut selected = Enum::First;
-/// # let mut ui = &mut egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// egui::ComboBox::from_label("Select one!")
 ///     .selected_text(format!("{:?}", selected))
 ///     .show_ui(ui, |ui| {
@@ -16,6 +16,7 @@ use epaint::Shape;
 ///         ui.selectable_value(&mut selected, Enum::Third, "Third");
 ///     }
 /// );
+/// # });
 /// ```
 #[must_use = "You should call .show*"]
 pub struct ComboBox {
@@ -109,7 +110,7 @@ impl ComboBox {
     /// # #[derive(Debug, PartialEq)]
     /// # enum Enum { First, Second, Third }
     /// # let mut selected = Enum::First;
-    /// # let mut ui = &mut egui::Ui::__test();
+    /// # egui::__run_test_ui(|ui| {
     /// let alternatives = ["a", "b", "c", "d"];
     /// let mut selected = 2;
     /// egui::ComboBox::from_label("Select one!").show_index(
@@ -118,6 +119,7 @@ impl ComboBox {
     ///     alternatives.len(),
     ///     |i| alternatives[i].to_owned()
     /// );
+    /// # });
     /// ```
     pub fn show_index(
         self,

diff --git a/egui/src/containers/panel.rs b/egui/src/containers/panel.rs
@@ -73,12 +73,11 @@ impl Side {
 /// See the [module level docs](crate::containers::panel) for more details.
 ///
 /// ```
-/// # let mut ctx = egui::CtxRef::default();
-/// # ctx.begin_frame(Default::default());
-/// # let ctx = &ctx;
+/// # egui::__run_test_ctx(|ctx| {
 /// egui::SidePanel::left("my_left_panel").show(ctx, |ui| {
 ///    ui.label("Hello World!");
 /// });
+/// # });
 /// ```
 ///
 /// See also [`TopBottomPanel`].
@@ -350,12 +349,11 @@ impl TopBottomSide {
 /// See the [module level docs](crate::containers::panel) for more details.
 ///
 /// ```
-/// # let mut ctx = egui::CtxRef::default();
-/// # ctx.begin_frame(Default::default());
-/// # let ctx = &ctx;
+/// # egui::__run_test_ctx(|ctx| {
 /// egui::TopBottomPanel::top("my_panel").show(ctx, |ui| {
 ///    ui.label("Hello World!");
 /// });
+/// # });
 /// ```
 ///
 /// See also [`SidePanel`].
@@ -605,12 +603,11 @@ impl TopBottomPanel {
 /// See the [module level docs](crate::containers::panel) for more details.
 ///
 /// ```
-/// # let mut ctx = egui::CtxRef::default();
-/// # ctx.begin_frame(Default::default());
-/// # let ctx = &ctx;
+/// # egui::__run_test_ctx(|ctx| {
 /// egui::CentralPanel::default().show(ctx, |ui| {
 ///    ui.label("Hello World!");
 /// });
+/// # });
 /// ```
 #[must_use = "You should call .show()"]
 #[derive(Default)]

diff --git a/egui/src/containers/popup.rs b/egui/src/containers/popup.rs
@@ -58,12 +58,13 @@ impl MonoState {
 /// Returns `None` if the tooltip could not be placed.
 ///
 /// ```
-/// # let mut ui = egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// if ui.ui_contains_pointer() {
 ///     egui::show_tooltip(ui.ctx(), egui::Id::new("my_tooltip"), |ui| {
 ///         ui.label("Helpful text");
 ///     });
 /// }
+/// # });
 /// ```
 pub fn show_tooltip<R>(ctx: &CtxRef, id: Id, add_contents: impl FnOnce(&mut Ui) -> R) -> Option<R> {
     show_tooltip_at_pointer(ctx, id, add_contents)
@@ -78,12 +79,13 @@ pub fn show_tooltip<R>(ctx: &CtxRef, id: Id, add_contents: impl FnOnce(&mut Ui)
 /// Returns `None` if the tooltip could not be placed.
 ///
 /// ```
-/// # let mut ui = egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// if ui.ui_contains_pointer() {
 ///     egui::show_tooltip_at_pointer(ui.ctx(), egui::Id::new("my_tooltip"), |ui| {
 ///         ui.label("Helpful text");
 ///     });
 /// }
+/// # });
 /// ```
 pub fn show_tooltip_at_pointer<R>(
     ctx: &CtxRef,
@@ -221,10 +223,11 @@ fn show_tooltip_at_avoid_dyn<'c, R>(
 /// Returns `None` if the tooltip could not be placed.
 ///
 /// ```
-/// # let mut ui = egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// if ui.ui_contains_pointer() {
 ///     egui::show_tooltip_text(ui.ctx(), egui::Id::new("my_tooltip"), "Helpful text");
 /// }
+/// # });
 /// ```
 pub fn show_tooltip_text(ctx: &CtxRef, id: Id, text: impl Into<WidgetText>) -> Option<()> {
     show_tooltip(ctx, id, |ui| {
@@ -264,7 +267,7 @@ fn show_tooltip_area_dyn<'c, R>(
 /// Returns `None` if the popup is not open.
 ///
 /// ```
-/// # let ui = &mut egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// let response = ui.button("Open popup");
 /// let popup_id = ui.make_persistent_id("my_unique_id");
 /// if response.clicked() {
@@ -275,6 +278,7 @@ fn show_tooltip_area_dyn<'c, R>(
 ///     ui.label("Some more info, or things you can select:");
 ///     ui.label("…");
 /// });
+/// # });
 /// ```
 pub fn popup_below_widget<R>(
     ui: &Ui,

diff --git a/egui/src/containers/scroll_area.rs b/egui/src/containers/scroll_area.rs
@@ -54,10 +54,12 @@ impl State {
 /// Add vertical and/or horizontal scrolling to a contained [`Ui`].
 ///
 /// ```
-/// # let ui = &mut egui::Ui::__test();
+/// # egui::__run_test_ui(|ui| {
 /// egui::ScrollArea::vertical().show(ui, |ui| {
 ///     // Add a lot of widgets here.
 /// });
+/// # });
+/// ```
 #[derive(Clone, Debug)]
 #[must_use = "You should call .show()"]
 pub struct ScrollArea {
@@ -370,7 +372,7 @@ impl ScrollArea {
     /// Efficiently show only the visible part of a large number of rows.
     ///
     /// ```
-    /// # let ui = &mut egui::Ui::__test();
+    /// # egui::__run_test_ui(|ui| {
     /// let text_style = egui::TextStyle::Body;
     /// let row_height = ui.fonts()[text_style].row_height();
     /// // let row_height = ui.spacing().interact_size.y; // if you are adding buttons instead of labels.
@@ -381,6 +383,8 @@ impl ScrollArea {
     ///         ui.label(text);
     ///     }
     /// });
+    /// # });
+    /// ```
     pub fn show_rows<R>(
         self,
         ui: &mut Ui,

diff --git a/egui/src/containers/window.rs b/egui/src/containers/window.rs
@@ -15,12 +15,11 @@ use super::*;
 /// * if there should be a close button (none by default)
 ///
 /// ```
-/// # let mut ctx = egui::CtxRef::default();
-/// # ctx.begin_frame(Default::default());
-/// # let ctx = &ctx;
+/// # egui::__run_test_ctx(|ctx| {
 /// egui::Window::new("My Window").show(ctx, |ui| {
 ///    ui.label("Hello World!");
 /// });
+/// # });
 #[must_use = "You should call .show()"]
 pub struct Window<'open> {
     title: WidgetText,