migrations/egui
1
0
Fork 0
mirror of https://github.com/emilk/egui.git synced 2026-09-01 22:30:03 -04:00
Code Activity

Rename the viewport types to "immediate" and "deferred"

Browse Source
This commit is contained in:
Emil Ernerfeldt
2023-11-07 11:50:59 +01:00
parent d4fab25fc8
commit f300c951b3
4 changed files with 66 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
crates/egui/src/context.rs
View File

@@ -2525,7 +2525,7 @@ impl Context {
});
}
/// If `true`, [`Self::create_viewport_async`] and [`Self::create_viewport_sync`] will
/// If `true`, [`Self::show_viewport`] and [`Self::show_viewport_immediate`] will
/// embed the new viewports as [`crate::Window`]s instead of spawning a new native window.
///
/// `eframe` sets this to `false` on supported platforms,
@@ -2534,7 +2534,7 @@ impl Context {
self.read(|ctx| ctx.embed_viewports)
}
/// If `true`, [`Self::create_viewport_async`] and [`Self::create_viewport_sync`] will
/// If `true`, [`Self::show_viewport`] and [`Self::show_viewport_immediate`] will
/// embed the new viewports as [`crate::Window`]s instead of spawning a new native window.
///
/// `eframe` sets this to `false` on supported platforms,
@@ -2555,17 +2555,24 @@ impl Context {
/// This creates a new native window, if possible.
///
/// You should call this each frame when the viewport should be visible.
/// You need to call this each frame when the child viewport should exist.
///
/// The given callback will be called whenever the child viewport needs repainting,
/// e.g. on an event or when [`Self::request_repaint`] is called.
/// This means it may be called multiple times, for instance while the
/// parent viewport (the caller) is sleeping but the child viewport is animating.
///
/// You will need to wrap your viewport state in an `Arc<RwLock<T>>` or `Arc<Mutex<T>>`.
/// When this is called again with the same id in `ViewportBuilder` the render function for that viewport will be updated.
/// * `viewport_ui_cb`: will be called when the viewport receives a event or is requested to be rendered
///
/// If this is no more called that viewport will be destroyed.
/// You can also use [`Self::show_viewport_immediate`], which uses a simpler `FnOnce`
/// with no need for `Send` or `Sync`. The downside is that it will require
/// the parent viewport (the caller) to repaint anytime the child is repainted,
/// and vice versa.
///
/// If you use a [`crate::CentralPanel`] you need to check if the viewport is a new window like:
/// `ctx.viewport_id() != ctx.parent_viewport_id` if false you should create a [`crate::Window`].
pub fn create_viewport_async(
pub fn show_viewport(
&self,
viewport_builder: ViewportBuilder,
viewport_ui_cb: impl Fn(&Context) + Send + Sync + 'static,
@@ -2600,25 +2607,23 @@ impl Context {
/// This creates a new native window, if possible.
///
/// You need to call this each frame when the child viewport should exist.
///
/// The given ui function will be called immediately.
/// This can only be called from the main thread.
/// This may only be called on the main thread.
///
/// If [`Context::embed_viewports`] is true, or if the current egui
/// backend does not support sync viewports, the given callback
/// will be called immediately and the function will return.
/// This call will pause the current viewport and render the child viewport in its own window.
/// This means that the child viewport will not be repainted when the parent viewport is repainted, and vice versa.
/// This can lead to unnecessary repaint.
/// To avoid this, use [`Self::show_viewport`] instead.
///
/// When this is called the current viewport will be paused
/// This will render in a native window if is possible.
/// When this finishes then the last viewport will continue drawing
/// This is bad for performance but easy to use.
///
/// For better performance use `Self::create_viewport`
///
/// If this is no more called that viewport will be destroyed.
/// If [`Context::embed_viewports`] is `true` (e.g. if the current egui
/// backend does not support multiple viewports), the given callback
/// will be called immediately, embedding the new viewport in the current one.
///
/// If you use a `egui::CentralPanel` you need to check if the viewport is a new window like:
/// `ctx.viewport_id() != ctx.parent_viewport_id` if false you should create a [`crate::Window`].
pub fn create_viewport_sync<T>(
pub fn show_viewport_immediate<T>(
&self,
viewport_builder: ViewportBuilder,
viewport_ui_cb: impl FnOnce(&Context) -> T,

18
crates/egui/src/viewport.rs
View File

@@ -1,9 +1,11 @@
//! egui supports multiple viewports, corresponding to multiple native windows.
//!
//! Viewports come in two flavors: "sync" and "async".
//! Viewports come in two flavors: "deferred" (the default) and "immediate".
//!
//! * Sync viewports are executed immediately.
//! * Async viewports are executed later.
//! * Deferred viewports have callbacks that are called multiple
//! times as the viewport receives events, or need repaitning.
//! * Immediate viewports are executed immediately with an [`FnOnce`] callback,
//! locking the parent and child viewports together so that they both must update at the same time.
use std::sync::Arc;
@@ -83,7 +85,7 @@ impl ViewportIdPair {
};
}
/// The user-code that shows the ui in the viewport, used for "async" viewports.
/// The user-code that shows the ui in the viewport, used for deferred viewports.
pub type ViewportUiCallback = dyn Fn(&Context) + Sync + Send;
/// Render the given viewport, calling the given ui callback.
@@ -655,9 +657,9 @@ pub(crate) struct Viewport {
/// Has this viewport been updated this frame?
pub(crate) used: bool,
/// The user-code that shows the GUI, used for "async" viewports.
/// The user-code that shows the GUI, used for deferred viewports.
///
/// `None` for "sync" viewports.
/// `None` for immediate viewports.
pub(crate) viewport_ui_cb: Option<Arc<Box<ViewportUiCallback>>>,
}
@@ -668,8 +670,8 @@ pub struct ViewportOutput {
/// Id of us and our parent.
pub id_pair: ViewportIdPair,
/// The user-code that shows the GUI, used for "async" viewports.
/// The user-code that shows the GUI, used for deferred viewports.
///
/// `None` for "sync" viewports.
/// `None` for immediate viewports.
pub viewport_ui_cb: Option<Arc<Box<ViewportUiCallback>>>,
}