From 50cede7b70d780cf6e548b8764bcff166fa5c433 Mon Sep 17 00:00:00 2001 From: Seaotatop Date: Fri, 23 Jun 2023 10:18:57 -0500 Subject: [PATCH] Add documentation --- src/window/window_state.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/window/window_state.rs b/src/window/window_state.rs index e83d1c0..8f11322 100644 --- a/src/window/window_state.rs +++ b/src/window/window_state.rs @@ -10,6 +10,30 @@ pub struct WindowState { pub resize_state: WindowResizeState, } +/// The state of a window's resize operation. +/// +/// A naive implementation of window swapping would probably immediately call +/// [`space.map_element()`] right after setting its size through [`with_pending_state()`] and +/// sending a configure event. However, the client will probably not acknowledge the configure +/// until *after* the window has moved, causing flickering. +/// +/// To solve this, we need to create two additional steps: [`WaitingForAck`] and [`WaitingForCommit`]. +/// If we need to change a window's location when we change its size, instead of +/// calling `map_element()`, we change the window's [`WindowState`] and set +/// its [`resize_state`] to `WaitingForAck` with the new position we want. +/// +/// When the client acks the configure, we can move the state to `WaitingForCommit` in +/// [`XdgShellHandler.ack_configure()`]. Finally, in [`CompositorHandler.commit()`], we set the +/// state back to [`Idle`] and map the window. +/// +/// [`space.map_element()`]: smithay::desktop::space::Space#method.map_element +/// [`with_pending_state()`]: smithay::wayland::shell::xdg::ToplevelSurface#method.with_pending_state +/// [`Idle`]: self::WindowResizeState#variant.Idle +/// [`WaitingForAck`]: self::WindowResizeState#variant.WaitingForAck +/// [`WaitingForCommit`]: self::WindowResizeState#variant.WaitingForCommit +/// [`resize_state`]: WindowState#structfield.resize_state +/// [`XdgShellHandler.ack_configure()`]: smithay::wayland::shell::xdg::XdgShellHandler#method.ack_configure +/// [`CompositorHandler.commit()`]: smithay::wayland::compositor::CompositorHandler#tymethod.commit #[derive(Debug, Default)] pub enum WindowResizeState { #[default]