From 44288f62800a9ebabcf770ddf20279b131fd58d0 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Fri, 10 Jun 2022 19:05:28 +0200 Subject: [PATCH] Make `WindowAttributes` private (#2134) * Make `WindowAttributes` private, and move its documentation * Reorder WindowAttributes title and fullscreen to match method order --- CHANGELOG.md | 1 + src/platform_impl/android/mod.rs | 2 +- src/platform_impl/ios/view.rs | 6 +- src/platform_impl/ios/window.rs | 2 +- src/platform_impl/linux/mod.rs | 2 +- src/platform_impl/linux/wayland/window/mod.rs | 2 +- src/platform_impl/linux/x11/mod.rs | 2 +- src/platform_impl/linux/x11/window.rs | 2 +- src/platform_impl/macos/mod.rs | 2 +- src/platform_impl/macos/window.rs | 2 +- src/platform_impl/web/window.rs | 2 +- src/platform_impl/windows/window.rs | 2 +- src/platform_impl/windows/window_state.rs | 2 +- src/window.rs | 143 ++++++++---------- 14 files changed, 74 insertions(+), 98 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b182f9f8..9e139022 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ And please only add new entries to the top of this list, right below the `# Unre # Unreleased +- **Breaking:** Removed the `WindowAttributes` struct, since all its functionality is accessible from `WindowBuilder`. - On macOS, Fix emitting `Event::LoopDestroyed` on CMD+Q. - On macOS, fixed an issue where having multiple windows would prevent run_return from ever returning. - On Wayland, fix bug where the cursor wouldn't hide in GNOME. diff --git a/src/platform_impl/android/mod.rs b/src/platform_impl/android/mod.rs index e8d79a5d..c472e107 100644 --- a/src/platform_impl/android/mod.rs +++ b/src/platform_impl/android/mod.rs @@ -641,7 +641,7 @@ pub struct PlatformSpecificWindowBuilderAttributes; pub struct Window; impl Window { - pub fn new( + pub(crate) fn new( _el: &EventLoopWindowTarget, _window_attrs: window::WindowAttributes, _: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/ios/view.rs b/src/platform_impl/ios/view.rs index e92b119b..b4cb4225 100644 --- a/src/platform_impl/ios/view.rs +++ b/src/platform_impl/ios/view.rs @@ -429,7 +429,7 @@ unsafe fn get_window_class() -> &'static Class { } // requires main thread -pub unsafe fn create_view( +pub(crate) unsafe fn create_view( _window_attributes: &WindowAttributes, platform_attributes: &PlatformSpecificWindowBuilderAttributes, frame: CGRect, @@ -449,7 +449,7 @@ pub unsafe fn create_view( } // requires main thread -pub unsafe fn create_view_controller( +pub(crate) unsafe fn create_view_controller( _window_attributes: &WindowAttributes, platform_attributes: &PlatformSpecificWindowBuilderAttributes, view: id, @@ -505,7 +505,7 @@ pub unsafe fn create_view_controller( } // requires main thread -pub unsafe fn create_window( +pub(crate) unsafe fn create_window( window_attributes: &WindowAttributes, _platform_attributes: &PlatformSpecificWindowBuilderAttributes, frame: CGRect, diff --git a/src/platform_impl/ios/window.rs b/src/platform_impl/ios/window.rs index 7e3e0eaa..b597f934 100644 --- a/src/platform_impl/ios/window.rs +++ b/src/platform_impl/ios/window.rs @@ -375,7 +375,7 @@ impl DerefMut for Window { } impl Window { - pub fn new( + pub(crate) fn new( _event_loop: &EventLoopWindowTarget, window_attributes: WindowAttributes, platform_attributes: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/linux/mod.rs b/src/platform_impl/linux/mod.rs index 6263d116..919d4d74 100644 --- a/src/platform_impl/linux/mod.rs +++ b/src/platform_impl/linux/mod.rs @@ -295,7 +295,7 @@ impl VideoMode { impl Window { #[inline] - pub fn new( + pub(crate) fn new( window_target: &EventLoopWindowTarget, attribs: WindowAttributes, pl_attribs: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/linux/wayland/window/mod.rs b/src/platform_impl/linux/wayland/window/mod.rs index 6cb3daed..f9c10797 100644 --- a/src/platform_impl/linux/wayland/window/mod.rs +++ b/src/platform_impl/linux/wayland/window/mod.rs @@ -75,7 +75,7 @@ pub struct Window { } impl Window { - pub fn new( + pub(crate) fn new( event_loop_window_target: &EventLoopWindowTarget, attributes: WindowAttributes, platform_attributes: PlatformAttributes, diff --git a/src/platform_impl/linux/x11/mod.rs b/src/platform_impl/linux/x11/mod.rs index c2bc4edc..966d5261 100644 --- a/src/platform_impl/linux/x11/mod.rs +++ b/src/platform_impl/linux/x11/mod.rs @@ -638,7 +638,7 @@ impl Deref for Window { } impl Window { - pub fn new( + pub(crate) fn new( event_loop: &EventLoopWindowTarget, attribs: WindowAttributes, pl_attribs: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/linux/x11/window.rs b/src/platform_impl/linux/x11/window.rs index fb2047cc..89ac8e46 100644 --- a/src/platform_impl/linux/x11/window.rs +++ b/src/platform_impl/linux/x11/window.rs @@ -114,7 +114,7 @@ pub struct UnownedWindow { } impl UnownedWindow { - pub fn new( + pub(crate) fn new( event_loop: &EventLoopWindowTarget, window_attrs: WindowAttributes, pl_attribs: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/macos/mod.rs b/src/platform_impl/macos/mod.rs index 301c0003..4608e2fa 100644 --- a/src/platform_impl/macos/mod.rs +++ b/src/platform_impl/macos/mod.rs @@ -70,7 +70,7 @@ impl Deref for Window { } impl Window { - pub fn new( + pub(crate) fn new( _window_target: &EventLoopWindowTarget, attributes: WindowAttributes, pl_attribs: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/macos/window.rs b/src/platform_impl/macos/window.rs index 145906c4..dde004ac 100644 --- a/src/platform_impl/macos/window.rs +++ b/src/platform_impl/macos/window.rs @@ -371,7 +371,7 @@ unsafe impl Send for UnownedWindow {} unsafe impl Sync for UnownedWindow {} impl UnownedWindow { - pub fn new( + pub(crate) fn new( mut win_attribs: WindowAttributes, pl_attribs: PlatformSpecificWindowBuilderAttributes, ) -> Result<(Arc, IdRef), RootOsError> { diff --git a/src/platform_impl/web/window.rs b/src/platform_impl/web/window.rs index aa485694..bd5791cb 100644 --- a/src/platform_impl/web/window.rs +++ b/src/platform_impl/web/window.rs @@ -26,7 +26,7 @@ pub struct Window { } impl Window { - pub fn new( + pub(crate) fn new( target: &EventLoopWindowTarget, attr: WindowAttributes, platform_attr: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/windows/window.rs b/src/platform_impl/windows/window.rs index 29c4d389..3e0d98fd 100644 --- a/src/platform_impl/windows/window.rs +++ b/src/platform_impl/windows/window.rs @@ -85,7 +85,7 @@ pub struct Window { } impl Window { - pub fn new( + pub(crate) fn new( event_loop: &EventLoopWindowTarget, w_attr: WindowAttributes, pl_attr: PlatformSpecificWindowBuilderAttributes, diff --git a/src/platform_impl/windows/window_state.rs b/src/platform_impl/windows/window_state.rs index ed71204f..77f8dcda 100644 --- a/src/platform_impl/windows/window_state.rs +++ b/src/platform_impl/windows/window_state.rs @@ -112,7 +112,7 @@ pub enum ImeState { } impl WindowState { - pub fn new( + pub(crate) fn new( attributes: &WindowAttributes, taskbar_icon: Option, scale_factor: f64, diff --git a/src/window.rs b/src/window.rs index 485c720d..2f8cbbf5 100644 --- a/src/window.rs +++ b/src/window.rs @@ -88,7 +88,7 @@ impl WindowId { #[must_use] pub struct WindowBuilder { /// The attributes to use to create the window. - pub window: WindowAttributes, + pub(crate) window: WindowAttributes, // Platform-specific configuration. pub(crate) platform_specific: platform_impl::PlatformSpecificWindowBuilderAttributes, @@ -104,92 +104,19 @@ impl fmt::Debug for WindowBuilder { /// Attributes to use when creating a window. #[derive(Debug, Clone)] -pub struct WindowAttributes { - /// The dimensions of the window. If this is `None`, some platform-specific dimensions will be - /// used. - /// - /// The default is `None`. +pub(crate) struct WindowAttributes { pub inner_size: Option, - - /// The minimum dimensions a window can be, If this is `None`, the window will have no minimum dimensions (aside from reserved). - /// - /// The default is `None`. pub min_inner_size: Option, - - /// The maximum dimensions a window can be, If this is `None`, the maximum will have no maximum or will be set to the primary monitor's dimensions by the platform. - /// - /// The default is `None`. pub max_inner_size: Option, - - /// The desired position of the window. If this is `None`, some platform-specific position - /// will be chosen. - /// - /// The default is `None`. - /// - /// ## Platform-specific - /// - /// - **macOS**: The top left corner position of the window content, the window's "inner" - /// position. The window title bar will be placed above it. - /// The window will be positioned such that it fits on screen, maintaining - /// set `inner_size` if any. - /// If you need to precisely position the top left corner of the whole window you have to - /// use [`Window::set_outer_position`] after creating the window. - /// - **Windows**: The top left corner position of the window title bar, the window's "outer" - /// position. - /// There may be a small gap between this position and the window due to the specifics of the - /// Window Manager. - /// - **X11**: The top left corner of the window, the window's "outer" position. - /// - **Others**: Ignored. - /// - /// See [`Window::set_outer_position`]. - /// - /// [`Window::set_outer_position`]: crate::window::Window::set_outer_position pub position: Option, - - /// Whether the window is resizable or not. - /// - /// The default is `true`. pub resizable: bool, - - /// Whether the window should be set as fullscreen upon creation. - /// - /// The default is `None`. - pub fullscreen: Option, - - /// The title of the window in the title bar. - /// - /// The default is `"winit window"`. pub title: String, - - /// Whether the window should be maximized upon creation. - /// - /// The default is `false`. + pub fullscreen: Option, pub maximized: bool, - - /// Whether the window should be immediately visible upon creation. - /// - /// The default is `true`. pub visible: bool, - - /// Whether the the window should be transparent. If this is true, writing colors - /// with alpha values different than `1.0` will produce a transparent window. - /// - /// The default is `false`. pub transparent: bool, - - /// Whether the window should have borders and bars. - /// - /// The default is `true`. pub decorations: bool, - - /// Whether the window should always be on top of other windows. - /// - /// The default is `false`. pub always_on_top: bool, - - /// The window icon. - /// - /// The default is `None`. pub window_icon: Option, } @@ -223,6 +150,8 @@ impl WindowBuilder { /// Requests the window to be of specific dimensions. /// + /// If this is not set, some platform-specific dimensions will be used. + /// /// See [`Window::set_inner_size`] for details. /// /// [`Window::set_inner_size`]: crate::window::Window::set_inner_size @@ -232,7 +161,10 @@ impl WindowBuilder { self } - /// Sets a minimum dimension size for the window. + /// Sets the minimum dimensions a window can have. + /// + /// If this is not set, the window will have no minimum dimensions (aside + /// from reserved). /// /// See [`Window::set_min_inner_size`] for details. /// @@ -243,7 +175,10 @@ impl WindowBuilder { self } - /// Sets a maximum dimension size for the window. + /// Sets the maximum dimensions a window can have. + /// + /// If this is not set, the window will have no maximum or will be set to + /// the primary monitor's dimensions by the platform. /// /// See [`Window::set_max_inner_size`] for details. /// @@ -256,9 +191,28 @@ impl WindowBuilder { /// Sets a desired initial position for the window. /// - /// See [`WindowAttributes::position`] for details. + /// If this is not set, some platform-specific position will be chosen. /// - /// [`WindowAttributes::position`]: crate::window::WindowAttributes::position + /// See [`Window::set_outer_position`] for details. + /// + /// ## Platform-specific + /// + /// - **macOS**: The top left corner position of the window content, the + /// window's "inner" position. The window title bar will be placed above + /// it. The window will be positioned such that it fits on screen, + /// maintaining set `inner_size` if any. + /// If you need to precisely position the top left corner of the whole + /// window you have to use [`Window::set_outer_position`] after creating + /// the window. + /// - **Windows**: The top left corner position of the window title bar, + /// the window's "outer" position. + /// There may be a small gap between this position and the window due to + /// the specifics of the Window Manager. + /// - **X11**: The top left corner of the window, the window's "outer" + /// position. + /// - **Others**: Ignored. + /// + /// [`Window::set_outer_position`]: crate::window::Window::set_outer_position #[inline] pub fn with_position>(mut self, position: P) -> Self { self.window.position = Some(position.into()); @@ -267,6 +221,8 @@ impl WindowBuilder { /// Sets whether the window is resizable or not. /// + /// The default is `true`. + /// /// See [`Window::set_resizable`] for details. /// /// [`Window::set_resizable`]: crate::window::Window::set_resizable @@ -276,7 +232,9 @@ impl WindowBuilder { self } - /// Requests a specific title for the window. + /// Sets the initial title of the window in the title bar. + /// + /// The default is `"winit window"`. /// /// See [`Window::set_title`] for details. /// @@ -287,7 +245,9 @@ impl WindowBuilder { self } - /// Sets the window fullscreen state. + /// Sets whether the window should be put into fullscreen upon creation. + /// + /// The default is `None`. /// /// See [`Window::set_fullscreen`] for details. /// @@ -298,7 +258,9 @@ impl WindowBuilder { self } - /// Requests maximized mode. + /// Request that the window is maximized upon creation. + /// + /// The default is `false`. /// /// See [`Window::set_maximized`] for details. /// @@ -309,7 +271,9 @@ impl WindowBuilder { self } - /// Sets whether the window will be initially hidden or visible. + /// Sets whether the window will be initially visible or hidden. + /// + /// The default is to show the window. /// /// See [`Window::set_visible`] for details. /// @@ -321,6 +285,11 @@ impl WindowBuilder { } /// Sets whether the background of the window should be transparent. + /// + /// If this is `true`, writing colors with alpha values different than + /// `1.0` will produce a transparent window. + /// + /// The default is `false`. #[inline] pub fn with_transparent(mut self, transparent: bool) -> Self { self.window.transparent = transparent; @@ -329,6 +298,8 @@ impl WindowBuilder { /// Sets whether the window should have a border, a title bar, etc. /// + /// The default is `true`. + /// /// See [`Window::set_decorations`] for details. /// /// [`Window::set_decorations`]: crate::window::Window::set_decorations @@ -340,6 +311,8 @@ impl WindowBuilder { /// Sets whether or not the window will always be on top of other windows. /// + /// The default is `false`. + /// /// See [`Window::set_always_on_top`] for details. /// /// [`Window::set_always_on_top`]: crate::window::Window::set_always_on_top @@ -351,6 +324,8 @@ impl WindowBuilder { /// Sets the window icon. /// + /// The default is `None`. + /// /// See [`Window::set_window_icon`] for details. /// /// [`Window::set_window_icon`]: crate::window::Window::set_window_icon