From 127931ba45cd5ffe3d4be38cf5cf3338316bfdd4 Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Sat, 20 Aug 2022 16:08:59 +0200 Subject: [PATCH] eframe: rename quit/exit to "close" (#1943) Since https://github.com/emilk/egui/pull/1919 we can continue the application after closing the native window. It therefore makes more sense to call `frame.close()` to close the native window, instead of `frame.quit()`. --- crates/eframe/CHANGELOG.md | 1 + crates/eframe/src/epi.rs | 38 +++++++++++++++------ crates/eframe/src/native/epi_integration.rs | 22 ++++++------ crates/eframe/src/native/run.rs | 12 +++---- crates/egui_demo_app/src/backend_panel.rs | 2 +- examples/confirm_exit/src/main.rs | 21 ++++++------ examples/custom_window_frame/src/main.rs | 2 +- examples/serial_windows/src/main.rs | 2 +- 8 files changed, 59 insertions(+), 41 deletions(-) diff --git a/crates/eframe/CHANGELOG.md b/crates/eframe/CHANGELOG.md index 3d99d7fb..f0f3b615 100644 --- a/crates/eframe/CHANGELOG.md +++ b/crates/eframe/CHANGELOG.md @@ -24,6 +24,7 @@ NOTE: [`egui-winit`](../egui-winit/CHANGELOG.md), [`egui_glium`](../egui_glium/C * Fixed mouse cursor change on Linux ([#1747](https://github.com/emilk/egui/pull/1747)). * Added `Frame::set_visible` ([#1808](https://github.com/emilk/egui/pull/1808)). * Added fullscreen support ([#1866](https://github.com/emilk/egui/pull/1866)). +* `Frame::quit` has been renamed to `Frame::close` and `App::on_exit_event` is now `App::on_close_event` ([#1943](https://github.com/emilk/egui/pull/1943)). #### Web: * Added ability to stop/re-run web app from JavaScript. ⚠️ You need to update your CSS with `html, body: { height: 100%; width: 100%; }` ([#1803](https://github.com/emilk/egui/pull/1650)). diff --git a/crates/eframe/src/epi.rs b/crates/eframe/src/epi.rs index 6e22b80b..9fa339bd 100644 --- a/crates/eframe/src/epi.rs +++ b/crates/eframe/src/epi.rs @@ -67,21 +67,25 @@ pub trait App { /// where `APPNAME` is what is given to `eframe::run_native`. fn save(&mut self, _storage: &mut dyn Storage) {} - /// Called before an exit that can be aborted. - /// By returning `false` the exit will be aborted. To continue the exit return `true`. + /// Called when the user attempts to close the desktop window and/or quit the application. + /// + /// By returning `false` the closing will be aborted. To continue the closing return `true`. /// /// A scenario where this method will be run is after pressing the close button on a native /// window, which allows you to ask the user whether they want to do something before exiting. /// See the example at for practical usage. /// /// It will _not_ be called on the web or when the window is forcefully closed. - fn on_exit_event(&mut self) -> bool { + #[cfg(not(target_arch = "wasm32"))] + #[doc(alias = "exit")] + #[doc(alias = "quit")] + fn on_close_event(&mut self) -> bool { true } /// Called once on shutdown, after [`Self::save`]. /// - /// If you need to abort an exit use [`Self::on_exit_event`]. + /// If you need to abort an exit use [`Self::on_close_event`]. /// /// To get a [`glow`] context you need to compile with the `glow` feature flag, /// and run eframe with the glow backend. @@ -90,7 +94,7 @@ pub trait App { /// Called once on shutdown, after [`Self::save`]. /// - /// If you need to abort an exit use [`Self::on_exit_event`]. + /// If you need to abort an exit use [`Self::on_close_event`]. #[cfg(not(feature = "glow"))] fn on_exit(&mut self) {} @@ -571,11 +575,24 @@ impl Frame { self.wgpu_render_state.as_ref() } - /// Signal the app to stop/exit/quit the app (only works for native apps, not web apps). - /// The framework will not quit immediately, but at the end of the this frame. + /// Tell `eframe` to close the desktop window. + /// + /// The window will not close immediately, but at the end of the this frame. + /// + /// Calling this will likely result in the app quitting, unless + /// you have more code after the call to [`crate::run_native`]. #[cfg(not(target_arch = "wasm32"))] + #[doc(alias = "exit")] + #[doc(alias = "quit")] + pub fn close(&mut self) { + self.output.close = true; + } + + /// Tell `eframe` to close the desktop window. + #[cfg(not(target_arch = "wasm32"))] + #[deprecated = "Renamed `close`"] pub fn quit(&mut self) { - self.output.quit = true; + self.close(); } /// Set the desired inner size of the window (in egui points). @@ -797,10 +814,9 @@ pub(crate) mod backend { #[derive(Clone, Debug, Default)] #[must_use] pub struct AppOutput { - /// Set to `true` to stop the app. - /// This does nothing for web apps. + /// Set to `true` to close the native window (which often quits the app). #[cfg(not(target_arch = "wasm32"))] - pub quit: bool, + pub close: bool, /// Set to some size to resize the outer window (e.g. glium window) to this size. #[cfg(not(target_arch = "wasm32"))] diff --git a/crates/eframe/src/native/epi_integration.rs b/crates/eframe/src/native/epi_integration.rs index ee32f1b2..335683f4 100644 --- a/crates/eframe/src/native/epi_integration.rs +++ b/crates/eframe/src/native/epi_integration.rs @@ -115,7 +115,7 @@ pub fn handle_app_output( app_output: epi::backend::AppOutput, ) { let epi::backend::AppOutput { - quit: _, + close: _, window_size, window_title, decorated, @@ -183,8 +183,8 @@ pub struct EpiIntegration { pub egui_ctx: egui::Context, pending_full_output: egui::FullOutput, egui_winit: egui_winit::State, - /// When set, it is time to quit - quit: bool, + /// When set, it is time to close the native window. + close: bool, can_drag_window: bool, } @@ -228,7 +228,7 @@ impl EpiIntegration { egui_ctx, egui_winit, pending_full_output: Default::default(), - quit: false, + close: false, can_drag_window: false, } } @@ -243,17 +243,17 @@ impl EpiIntegration { self.egui_ctx.clear_animations(); } - /// If `true`, it is time to shut down. - pub fn should_quit(&self) -> bool { - self.quit + /// If `true`, it is time to close the native window. + pub fn should_close(&self) -> bool { + self.close } pub fn on_event(&mut self, app: &mut dyn epi::App, event: &winit::event::WindowEvent<'_>) { use winit::event::{ElementState, MouseButton, WindowEvent}; match event { - WindowEvent::CloseRequested => self.quit = app.on_exit_event(), - WindowEvent::Destroyed => self.quit = true, + WindowEvent::CloseRequested => self.close = app.on_close_event(), + WindowEvent::Destroyed => self.close = true, WindowEvent::MouseInput { button: MouseButton::Left, state: ElementState::Pressed, @@ -285,8 +285,8 @@ impl EpiIntegration { let mut app_output = self.frame.take_app_output(); app_output.drag_window &= self.can_drag_window; // Necessary on Windows; see https://github.com/emilk/egui/pull/1108 self.can_drag_window = false; - if app_output.quit { - self.quit = app.on_exit_event(); + if app_output.close { + self.close = app.on_close_event(); } handle_app_output(window, self.egui_ctx.pixels_per_point(), app_output); } diff --git a/crates/eframe/src/native/run.rs b/crates/eframe/src/native/run.rs index 217d2f72..9331a8c1 100644 --- a/crates/eframe/src/native/run.rs +++ b/crates/eframe/src/native/run.rs @@ -373,7 +373,7 @@ mod glow_integration { gl_window.swap_buffers().unwrap(); } - let control_flow = if integration.should_quit() { + let control_flow = if integration.should_close() { EventResult::Exit } else if repaint_after.is_zero() { EventResult::RepaintAsap @@ -426,7 +426,7 @@ mod glow_integration { self.gl_window.resize(**new_inner_size); } winit::event::WindowEvent::CloseRequested - if self.integration.should_quit() => + if self.integration.should_close() => { return EventResult::Exit } @@ -435,7 +435,7 @@ mod glow_integration { self.integration.on_event(self.app.as_mut(), &event); - if self.integration.should_quit() { + if self.integration.should_close() { EventResult::Exit } else { // TODO(emilk): ask egui if the event warrants a repaint @@ -624,7 +624,7 @@ mod wgpu_integration { integration.post_rendering(app.as_mut(), window); - let control_flow = if integration.should_quit() { + let control_flow = if integration.should_close() { EventResult::Exit } else if repaint_after.is_zero() { EventResult::RepaintAsap @@ -690,7 +690,7 @@ mod wgpu_integration { .on_window_resized(new_inner_size.width, new_inner_size.height); } winit::event::WindowEvent::CloseRequested - if self.integration.should_quit() => + if self.integration.should_close() => { return EventResult::Exit } @@ -698,7 +698,7 @@ mod wgpu_integration { }; self.integration.on_event(self.app.as_mut(), &event); - if self.integration.should_quit() { + if self.integration.should_close() { EventResult::Exit } else { // TODO(emilk): ask egui if the event warrants a repaint diff --git a/crates/egui_demo_app/src/backend_panel.rs b/crates/egui_demo_app/src/backend_panel.rs index e8981d05..4fe61728 100644 --- a/crates/egui_demo_app/src/backend_panel.rs +++ b/crates/egui_demo_app/src/backend_panel.rs @@ -140,7 +140,7 @@ impl BackendPanel { { ui.separator(); if ui.button("Quit").clicked() { - frame.quit(); + frame.close(); } } } diff --git a/examples/confirm_exit/src/main.rs b/examples/confirm_exit/src/main.rs index 27c6832d..aa0e372a 100644 --- a/examples/confirm_exit/src/main.rs +++ b/examples/confirm_exit/src/main.rs @@ -13,14 +13,14 @@ fn main() { #[derive(Default)] struct MyApp { - can_exit: bool, - is_exiting: bool, + allowed_to_close: bool, + show_confirmation_dialog: bool, } impl eframe::App for MyApp { - fn on_exit_event(&mut self) -> bool { - self.is_exiting = true; - self.can_exit + fn on_close_event(&mut self) -> bool { + self.show_confirmation_dialog = true; + self.allowed_to_close } fn update(&mut self, ctx: &egui::Context, frame: &mut eframe::Frame) { @@ -28,19 +28,20 @@ impl eframe::App for MyApp { ui.heading("Try to close the window"); }); - if self.is_exiting { + if self.show_confirmation_dialog { + // Show confirmation dialog: egui::Window::new("Do you want to quit?") .collapsible(false) .resizable(false) .show(ctx, |ui| { ui.horizontal(|ui| { - if ui.button("Not yet").clicked() { - self.is_exiting = false; + if ui.button("Cancel").clicked() { + self.show_confirmation_dialog = false; } if ui.button("Yes!").clicked() { - self.can_exit = true; - frame.quit(); + self.allowed_to_close = true; + frame.close(); } }); }); diff --git a/examples/custom_window_frame/src/main.rs b/examples/custom_window_frame/src/main.rs index 64e01b28..b9d636fb 100644 --- a/examples/custom_window_frame/src/main.rs +++ b/examples/custom_window_frame/src/main.rs @@ -89,7 +89,7 @@ fn custon_window_frame( Button::new(RichText::new("❌").size(height - 4.0)).frame(false), ); if close_response.clicked() { - frame.quit(); + frame.close(); } // Interact with the title bar (drag to move window): diff --git a/examples/serial_windows/src/main.rs b/examples/serial_windows/src/main.rs index 79362ca1..72981164 100644 --- a/examples/serial_windows/src/main.rs +++ b/examples/serial_windows/src/main.rs @@ -46,7 +46,7 @@ impl eframe::App for MyApp { egui::CentralPanel::default().show(ctx, |ui| { if ui.button("Close").clicked() { eprintln!("Pressed Close button"); - frame.quit(); + frame.close(); } }); }