From 8305a7cce5328cac9dab520c822444ac0e73f513 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Sat, 24 Aug 2024 22:48:27 +0200 Subject: [PATCH] Fix documentation --- examples/window.rs | 2 +- src/changelog/unreleased.md | 17 ++++++++ src/event.rs | 14 ++++--- src/platform_impl/linux/wayland/window/mod.rs | 2 +- .../linux/wayland/window/state.rs | 10 ++--- src/platform_impl/windows/event_loop.rs | 2 +- src/window.rs | 39 +++++++++---------- 7 files changed, 53 insertions(+), 33 deletions(-) diff --git a/examples/window.rs b/examples/window.rs index 9ea98f3bb0..719011c1af 100644 --- a/examples/window.rs +++ b/examples/window.rs @@ -740,7 +740,7 @@ impl WindowState { self.resize(new_surface_size); } } else { - info!("Request inner size is asynchronous"); + info!("Requesting surface size is asynchronous"); } } diff --git a/src/changelog/unreleased.md b/src/changelog/unreleased.md index e8b7b1c21e..a5d0fcb88b 100644 --- a/src/changelog/unreleased.md +++ b/src/changelog/unreleased.md @@ -105,6 +105,23 @@ changelog entry. - On iOS, no longer act as-if the application successfully open all URLs. Override `application:didFinishLaunchingWithOptions:` and provide the desired behaviour yourself. - On X11, remove our dependency on libXcursor. (#3749) +- Renamed the following APIs to make it clearer that the sizes apply to the underlying surface: + - `WindowEvent::Resized` to `SurfaceResized`. + - `InnerSizeWriter` to `SurfaceSizeWriter`. + - `WindowAttributes.inner_size` to `surface_size`. + - `WindowAttributes.min_inner_size` to `min_surface_size`. + - `WindowAttributes.max_inner_size` to `max_surface_size`. + - `WindowAttributes.resize_increments` to `surface_resize_increments`. + - `WindowAttributes::with_inner_size` to `with_surface_size`. + - `WindowAttributes::with_min_inner_size` to `with_min_surface_size`. + - `WindowAttributes::with_max_inner_size` to `with_max_surface_size`. + - `WindowAttributes::with_resize_increments` to `with_surface_resize_increments`. + - `Window::inner_size` to `surface_size`. + - `Window::request_inner_size` to `request_surface_size`. + - `Window::set_min_inner_size` to `set_min_surface_size`. + - `Window::set_max_inner_size` to `set_max_surface_size`. + + To migrate, you can probably just replace all instances of `inner_size` with `surface_size` in your codebase. ### Removed diff --git a/src/event.rs b/src/event.rs index 731ee8a297..67ee7a53d2 100644 --- a/src/event.rs +++ b/src/event.rs @@ -148,7 +148,12 @@ pub enum WindowEvent { /// [`request_activation_token`]: crate::platform::startup_notify::WindowExtStartupNotify::request_activation_token ActivationTokenDone { serial: AsyncRequestSerial, token: ActivationToken }, - /// The size of the window has changed. Contains the client area's new dimensions. + /// The size of the window's surface has changed. + /// + /// Contains the new dimensions of the surface (can also be retrieved with + /// [`Window::surface_size`]). + /// + /// [`Window::surface_size`]: crate::window::Window::surface_size SurfaceResized(PhysicalSize), /// The position of the window has changed. Contains the window's new position. @@ -366,7 +371,7 @@ pub enum WindowEvent { /// For more information about DPI in general, see the [`dpi`] crate. ScaleFactorChanged { scale_factor: f64, - /// Handle to update inner size during scale changes. + /// Handle to update surface size during scale changes. /// /// See [`SurfaceSizeWriter`] docs for more details. surface_size_writer: SurfaceSizeWriter, @@ -995,8 +1000,7 @@ pub enum MouseScrollDelta { PixelDelta(PhysicalPosition), } -/// Handle to synchronously change the size of the window from the -/// [`WindowEvent`]. +/// Handle to synchronously change the size of the window from the [`WindowEvent`]. #[derive(Debug, Clone)] pub struct SurfaceSizeWriter { pub(crate) new_surface_size: Weak>>, @@ -1008,7 +1012,7 @@ impl SurfaceSizeWriter { Self { new_surface_size } } - /// Try to request inner size which will be set synchronously on the window. + /// Try to request surface size which will be set synchronously on the window. pub fn request_surface_size( &mut self, new_surface_size: PhysicalSize, diff --git a/src/platform_impl/linux/wayland/window/mod.rs b/src/platform_impl/linux/wayland/window/mod.rs index 2bee894a30..814061dd8f 100644 --- a/src/platform_impl/linux/wayland/window/mod.rs +++ b/src/platform_impl/linux/wayland/window/mod.rs @@ -348,7 +348,7 @@ impl CoreWindow for Window { self.request_redraw(); } - /// Set the maximum inner size for the window. + /// Set the maximum surface size for the window. #[inline] fn set_max_surface_size(&self, max_size: Option) { let scale_factor = self.scale_factor(); diff --git a/src/platform_impl/linux/wayland/window/state.rs b/src/platform_impl/linux/wayland/window/state.rs index 5d3aa809a7..79c1766b60 100644 --- a/src/platform_impl/linux/wayland/window/state.rs +++ b/src/platform_impl/linux/wayland/window/state.rs @@ -46,7 +46,7 @@ pub type WinitFrame = sctk_adwaita::AdwaitaFrame; #[cfg(not(feature = "sctk-adwaita"))] pub type WinitFrame = sctk::shell::xdg::fallback_frame::FallbackFrame; -// Minimum window inner size. +// Minimum window surface size. const MIN_WINDOW_SIZE: LogicalSize = LogicalSize::new(2, 1); /// The state of the window which is being updated from the [`WinitState`]. @@ -112,7 +112,7 @@ pub struct WindowState { /// The text inputs observed on the window. text_inputs: Vec, - /// The inner size of the window, as in without client side decorations. + /// The surface size of the window, as in without client side decorations. size: LogicalSize, /// Whether the CSD fail to create, so we don't try to create them on each iteration. @@ -361,7 +361,7 @@ impl WindowState { } } - /// Compute the bounds for the inner size of the surface. + /// Compute the bounds for the surface size of the surface. fn surface_size_bounds( &self, configure: &WindowConfigure, @@ -636,7 +636,7 @@ impl WindowState { logical_to_physical_rounded(self.surface_size(), self.scale_factor()) } - /// Resize the window to the new inner size. + /// Resize the window to the new surface size. fn resize(&mut self, surface_size: LogicalSize) { self.size = surface_size; @@ -673,7 +673,7 @@ impl WindowState { // Update the target viewport, this is used if and only if fractional scaling is in use. if let Some(viewport) = self.viewport.as_ref() { - // Set inner size without the borders. + // Set surface size without the borders. viewport.set_destination(self.size.width as _, self.size.height as _); } } diff --git a/src/platform_impl/windows/event_loop.rs b/src/platform_impl/windows/event_loop.rs index b71a8f1c73..b63ece77d7 100644 --- a/src/platform_impl/windows/event_loop.rs +++ b/src/platform_impl/windows/event_loop.rs @@ -2131,7 +2131,7 @@ unsafe fn public_window_callback_inner( // New size as suggested by Windows. let suggested_rect = unsafe { *(lparam as *const RECT) }; - // The window rect provided is the window's outer size, not it's inner size. However, + // The window rect provided is the window's outer size, not it's surface size. However, // win32 doesn't provide an `UnadjustWindowRectEx` function to get the client rect from // the outer rect, so we instead adjust the window rect to get the decoration margins // and remove them from the outer size. diff --git a/src/window.rs b/src/window.rs index e01284d4b5..6a3dd62539 100644 --- a/src/window.rs +++ b/src/window.rs @@ -137,7 +137,7 @@ impl WindowAttributes { self.parent_window.as_ref().map(|handle| &handle.0) } - /// Requests the window to be of specific dimensions. + /// Requests the surface to be of specific dimensions. /// /// If this is not set, some platform-specific dimensions will be used. /// @@ -148,10 +148,9 @@ impl WindowAttributes { self } - /// Sets the minimum dimensions a window can have. + /// Sets the minimum dimensions the surface can have. /// - /// If this is not set, the window will have no minimum dimensions (aside - /// from reserved). + /// If this is not set, the surface will have no minimum dimensions (aside from reserved). /// /// See [`Window::set_min_surface_size`] for details. #[inline] @@ -160,9 +159,9 @@ impl WindowAttributes { self } - /// Sets the maximum dimensions a window can have. + /// Sets the maximum dimensions the surface can have. /// - /// If this is not set, the window will have no maximum or will be set to + /// If this is not set, the surface will have no maximum, or the maximum will be restricted to /// the primary monitor's dimensions by the platform. /// /// See [`Window::set_max_surface_size`] for details. @@ -653,9 +652,9 @@ pub trait Window: AsAny + Send + Sync { /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform fn set_outer_position(&self, position: Position); - /// Returns the physical size of the window's client area. + /// Returns the size of the window's render-able surface. /// - /// The client area is the content of the window, excluding the title bar and borders. + /// This is the dimensions you should pass to things like Wgpu or Glutin when configuring. /// /// ## Platform-specific /// @@ -667,14 +666,14 @@ pub trait Window: AsAny + Send + Sync { /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform fn surface_size(&self) -> PhysicalSize; - /// Request the new size for the window. + /// Request the new size for the surface. /// /// On platforms where the size is entirely controlled by the user the /// applied size will be returned immediately, resize event in such case /// may not be generated. /// - /// On platforms where resizing is disallowed by the windowing system, the current - /// inner size is returned immediately, and the user one is ignored. + /// On platforms where resizing is disallowed by the windowing system, the current surface size + /// is returned immediately, and the user one is ignored. /// /// When `None` is returned, it means that the request went to the display system, /// and the actual size will be delivered later with the [`WindowEvent::SurfaceResized`]. @@ -704,10 +703,10 @@ pub trait Window: AsAny + Send + Sync { #[must_use] fn request_surface_size(&self, size: Size) -> Option>; - /// Returns the physical size of the entire window. + /// Returns the size of the entire window. /// - /// These dimensions include the title bar and borders. If you don't want that (and you usually - /// don't), use [`Window::surface_size`] instead. + /// These dimensions include window decorations like the title bar and borders. If you don't + /// want that (and you usually don't), use [`Window::surface_size`] instead. /// /// ## Platform-specific /// @@ -716,7 +715,7 @@ pub trait Window: AsAny + Send + Sync { /// [`Window::surface_size`]._ fn outer_size(&self) -> PhysicalSize; - /// Sets a minimum dimension size for the window. + /// Sets a minimum dimensions of the window's surface. /// /// ```no_run /// # use winit::dpi::{LogicalSize, PhysicalSize}; @@ -735,7 +734,7 @@ pub trait Window: AsAny + Send + Sync { /// - **iOS / Android / Orbital:** Unsupported. fn set_min_surface_size(&self, min_size: Option); - /// Sets a maximum dimension size for the window. + /// Sets a maximum dimensions of the window's surface. /// /// ```no_run /// # use winit::dpi::{LogicalSize, PhysicalSize}; @@ -754,17 +753,17 @@ pub trait Window: AsAny + Send + Sync { /// - **iOS / Android / Orbital:** Unsupported. fn set_max_surface_size(&self, max_size: Option); - /// Returns window resize increments if any were set. + /// Returns surface resize increments if any were set. /// /// ## Platform-specific /// /// - **iOS / Android / Web / Wayland / Orbital:** Always returns [`None`]. fn surface_resize_increments(&self) -> Option>; - /// Sets window resize increments. + /// Sets resize increments of the surface. /// - /// This is a niche constraint hint usually employed by terminal emulators - /// and other apps that need "blocky" resizes. + /// This is a niche constraint hint usually employed by terminal emulators and other such apps + /// that need "blocky" resizes. /// /// ## Platform-specific ///