From 6e244d12cdc1ee230aef76c16b6e6145391f8359 Mon Sep 17 00:00:00 2001 From: Konkitoman Date: Tue, 5 Sep 2023 16:30:33 +0300 Subject: [PATCH] Improved documentation and added documentation --- crates/egui/src/context.rs | 63 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 3 deletions(-) diff --git a/crates/egui/src/context.rs b/crates/egui/src/context.rs index b8e473036..4b112e92f 100644 --- a/crates/egui/src/context.rs +++ b/crates/egui/src/context.rs @@ -576,6 +576,7 @@ impl Context { self.write(|ctx| ctx.begin_frame_mut(new_input, viewport_id, parent_viewport_id)); } + /// Create a new Context and specify if is desktop pub fn new(desktop: bool) -> Context { let context = Context::default(); context.write(|ctx| { @@ -1174,12 +1175,24 @@ impl Context { /// If called from outside the UI thread, the UI thread will wake up and run, /// provided the egui integration has set that up via [`Self::set_request_repaint_callback`] /// (this will work on `eframe`). + /// + /// This will repaint the current viewport pub fn request_repaint(&self) { // request two frames of repaint, just to cover some corner cases (frame delays): self.write(|ctx| ctx.repaint.request_repaint(ctx.get_viewport_id())); } - pub fn request_repaint_viewport(&self, id: ViewportId) { + /// Call this if there is need to repaint the UI, i.e. if you are showing an animation. + /// + /// If this is called at least once in a frame, then there will be another frame right after this. + /// Call as many times as you wish, only one repaint will be issued. + /// + /// If called from outside the UI thread, the UI thread will wake up and run, + /// provided the egui integration has set that up via [`Self::set_request_repaint_callback`] + /// (this will work on `eframe`). + /// + /// This will repaint the specified viewport + pub fn request_repaint_for(&self, id: ViewportId) { self.write(|ctx| ctx.repaint.request_repaint(id)); } @@ -1212,6 +1225,8 @@ impl Context { /// timeout takes 500 milliseconds AFTER the vsync swap buffer. /// So, its not that we are requesting repaint within X duration. We are rather timing out /// during app idle time where we are not receiving any new input events. + /// + /// This repaints the current viewport pub fn request_repaint_after(&self, duration: std::time::Duration) { // Maybe we can check if duration is ZERO, and call self.request_repaint()? self.write(|ctx| { @@ -1220,7 +1235,38 @@ impl Context { }); } - pub fn request_repaint_viewport_after(&self, duration: std::time::Duration, id: ViewportId) { + /// Request repaint after at most the specified duration elapses. + /// + /// The backend can chose to repaint sooner, for instance if some other code called + /// this method with a lower duration, or if new events arrived. + /// + /// The function can be multiple times, but only the *smallest* duration will be considered. + /// So, if the function is called two times with `1 second` and `2 seconds`, egui will repaint + /// after `1 second` + /// + /// This is primarily useful for applications who would like to save battery by avoiding wasted + /// redraws when the app is not in focus. But sometimes the GUI of the app might become stale + /// and outdated if it is not updated for too long. + /// + /// Lets say, something like a stop watch widget that displays the time in seconds. You would waste + /// resources repainting multiple times within the same second (when you have no input), + /// just calculate the difference of duration between current time and next second change, + /// and call this function, to make sure that you are displaying the latest updated time, but + /// not wasting resources on needless repaints within the same second. + /// + /// NOTE: only works if called before `Context::end_frame()`. to force egui to update, + /// use `Context::request_repaint()` instead. + /// + /// ### Quirk: + /// Duration begins at the next frame. lets say for example that its a very inefficient app + /// and takes 500 milliseconds per frame at 2 fps. The widget / user might want a repaint in + /// next 500 milliseconds. Now, app takes 1000 ms per frame (1 fps) because the backend event + /// timeout takes 500 milliseconds AFTER the vsync swap buffer. + /// So, its not that we are requesting repaint within X duration. We are rather timing out + /// during app idle time where we are not receiving any new input events. + /// + /// This repaints the specified viewport + pub fn request_repaint_after_for(&self, duration: std::time::Duration, id: ViewportId) { self.write(|ctx| ctx.repaint.request_repaint_after(duration, id)); } @@ -1640,18 +1686,26 @@ impl Context { self.input(|i| i.screen_rect()) } + /// This will return the inner position of the current viewport + /// Viewport inner position, only the drowable area pub fn viewport_inner_pos(&self) -> Pos2 { self.input(|i| i.inner_pos) } + /// This will return the outer position of the current viewport + /// Viewport outer position, drowable area + decorations pub fn viewport_outer_pos(&self) -> Pos2 { self.input(|i| i.outer_pos) } + /// This will return the inner size of the current viewport + /// Viewport inner size, only drowable area pub fn viewport_inner_size(&self) -> Pos2 { self.input(|i| i.inner_size) } + /// This will return the outer size of the current viewport + /// Viewport outer size, drowable area + decorations pub fn viewport_outer_size(&self) -> Pos2 { self.input(|i| i.outer_size) } @@ -2254,10 +2308,12 @@ impl Context { self.read(|ctx| ctx.get_parent_viewport_id()) } + /// This will return the `ViewportId` of the specified id pub fn get_viewport_id_by_id(&self, id: impl Into) -> Option { self.read(|ctx| ctx.viewports.get(&id.into()).map(|v| v.1)) } + /// This will return the parent `ViewportId` of the specified id pub fn get_viewport_parent_id_by_id(&self, id: impl Into) -> Option { self.read(|ctx| ctx.viewports.get(&id.into()).map(|v| v.1)) } @@ -2289,11 +2345,12 @@ impl Context { self.write(|ctx| ctx.force_embedding = value || !ctx.is_desktop); } - /// With this you can send a command to a viewport + /// This will send the `ViewportCommand` to the current viewport pub fn viewport_command(&self, command: ViewportCommand) { self.viewport_command_for(self.get_viewport_id(), command); } + /// With this you can send a command to a viewport pub fn viewport_command_for(&self, id: ViewportId, command: ViewportCommand) { self.write(|ctx| ctx.viewport_commands.push((id, command))); }