Allow eframe apps to be detached

crates/eframe/src/lib.rs

@@ -161,6 +161,10 @@ pub use web::{WebLogger, WebRunner};
 #[cfg(any(feature = "glow", feature = "wgpu"))]
 mod native;
 
+#[cfg(not(target_arch = "wasm32"))]
+#[cfg(any(feature = "glow", feature = "wgpu"))]
+pub use native::run::{Detached, DetachedResult};
+
 #[cfg(not(target_arch = "wasm32"))]
 #[cfg(any(feature = "glow", feature = "wgpu"))]
 #[cfg(feature = "persistence")]
@@ -295,6 +299,94 @@ pub fn run_simple_native(
 
 // ----------------------------------------------------------------------------
 
+/// Execute an app in a detached state.
+///
+/// This allows you to control the event loop itself, which is necessary in a few
+/// occasions, like when you need a screen not managed by `egui`.
+///
+/// See [`Detached`] for more info on how to run detached apps.
+///
+/// # Example
+/// ``` no_run
+/// use eframe::DetachedResult;
+/// use winit::event_loop::ControlFlow;
+///
+/// fn main() {
+///     let native_options = eframe::NativeOptions::default();
+///     let event_loop = eframe::EventLoopBuilder::<eframe::UserEvent>::with_user_event().build();
+///     let mut detached = eframe::run_detached_native(
+///         "MyApp",
+///         &event_loop,
+///         native_options,
+///         Box::new(|cc| Box::new(MyEguiApp::new(cc))),
+///     );
+///     event_loop.run(move |event, event_loop, control_flow| {
+///         *control_flow = match detached.on_event(&event, event_loop).unwrap() {
+///             DetachedResult::UpdateNext => ControlFlow::Poll,
+///             DetachedResult::UpdateAt(next_repaint) => ControlFlow::WaitUntil(next_repaint),
+///             DetachedResult::Exit => ControlFlow::Exit,
+///         }
+///     })
+/// }
+///
+/// #[derive(Default)]
+/// struct MyEguiApp {}
+///
+/// impl MyEguiApp {
+///     fn new(cc: &eframe::CreationContext<'_>) -> Self {
+///         // Customize egui here with cc.egui_ctx.set_fonts and cc.egui_ctx.set_visuals.
+///         // Restore app state using cc.storage (requires the "persistence" feature).
+///         // Use the cc.gl (a glow::Context) to create graphics shaders and buffers that you can use
+///         // for e.g. egui::PaintCallback.
+///         Self::default()
+///     }
+/// }
+///
+/// impl eframe::App for MyEguiApp {
+///     fn update(&mut self, ctx: &egui::Context, frame: &mut eframe::Frame) {
+///         egui::CentralPanel::default().show(ctx, |ui| {
+///             ui.heading("Hello World!");
+///         });
+///     }
+/// }
+/// ```
+#[cfg(not(target_arch = "wasm32"))]
+#[cfg(any(feature = "glow", feature = "wgpu"))]
+#[allow(clippy::needless_pass_by_value)]
+pub fn run_detached_native(
+    app_name: &str,
+    event_loop: &winit::event_loop::EventLoop<UserEvent>,
+    native_options: NativeOptions,
+    app_creator: AppCreator,
+) -> Box<dyn Detached> {
+    let renderer = native_options.renderer;
+
+    match renderer {
+        #[cfg(feature = "glow")]
+        Renderer::Glow => {
+            log::debug!("Using the glow renderer");
+            Box::new(native::run::detached_glow(
+                app_name,
+                event_loop,
+                native_options,
+                app_creator,
+            ))
+        }
+        #[cfg(feature = "wgpu")]
+        Renderer::Wgpu => {
+            log::debug!("Using the wgpu renderer");
+            Box::new(native::run::detached_wgpu(
+                app_name,
+                event_loop,
+                native_options,
+                app_creator,
+            ))
+        }
+    }
+}
+
+// ----------------------------------------------------------------------------
+
 /// The different problems that can occur when trying to run `eframe`.
 #[derive(thiserror::Error, Debug)]
 pub enum Error {