Make WindowAttributes private (#2134)

* Make `WindowAttributes` private, and move its documentation

* Reorder WindowAttributes title and fullscreen to match method order

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.

src/platform_impl/android/mod.rs

@@ -641,7 +641,7 @@ pub struct PlatformSpecificWindowBuilderAttributes;
 pub struct Window;
 
 impl Window {
-    pub fn new<T: 'static>(
+    pub(crate) fn new<T: 'static>(
         _el: &EventLoopWindowTarget<T>,
         _window_attrs: window::WindowAttributes,
         _: PlatformSpecificWindowBuilderAttributes,

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,

src/platform_impl/ios/window.rs

@@ -375,7 +375,7 @@ impl DerefMut for Window {
 }
 
 impl Window {
-    pub fn new<T>(
+    pub(crate) fn new<T>(
         _event_loop: &EventLoopWindowTarget<T>,
         window_attributes: WindowAttributes,
         platform_attributes: PlatformSpecificWindowBuilderAttributes,

src/platform_impl/linux/mod.rs

@@ -295,7 +295,7 @@ impl VideoMode {
 
 impl Window {
     #[inline]
-    pub fn new<T>(
+    pub(crate) fn new<T>(
         window_target: &EventLoopWindowTarget<T>,
         attribs: WindowAttributes,
         pl_attribs: PlatformSpecificWindowBuilderAttributes,

src/platform_impl/linux/wayland/window/mod.rs

@@ -75,7 +75,7 @@ pub struct Window {
 }
 
 impl Window {
-    pub fn new<T>(
+    pub(crate) fn new<T>(
         event_loop_window_target: &EventLoopWindowTarget<T>,
         attributes: WindowAttributes,
         platform_attributes: PlatformAttributes,

src/platform_impl/linux/x11/mod.rs

@@ -638,7 +638,7 @@ impl Deref for Window {
 }
 
 impl Window {
-    pub fn new<T>(
+    pub(crate) fn new<T>(
         event_loop: &EventLoopWindowTarget<T>,
         attribs: WindowAttributes,
         pl_attribs: PlatformSpecificWindowBuilderAttributes,

src/platform_impl/linux/x11/window.rs

@@ -114,7 +114,7 @@ pub struct UnownedWindow {
 }
 
 impl UnownedWindow {
-    pub fn new<T>(
+    pub(crate) fn new<T>(
         event_loop: &EventLoopWindowTarget<T>,
         window_attrs: WindowAttributes,
         pl_attribs: PlatformSpecificWindowBuilderAttributes,

src/platform_impl/macos/mod.rs

@@ -70,7 +70,7 @@ impl Deref for Window {
 }
 
 impl Window {
-    pub fn new<T: 'static>(
+    pub(crate) fn new<T: 'static>(
         _window_target: &EventLoopWindowTarget<T>,
         attributes: WindowAttributes,
         pl_attribs: PlatformSpecificWindowBuilderAttributes,

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<Self>, IdRef), RootOsError> {

src/platform_impl/web/window.rs

@@ -26,7 +26,7 @@ pub struct Window {
 }
 
 impl Window {
-    pub fn new<T>(
+    pub(crate) fn new<T>(
         target: &EventLoopWindowTarget<T>,
         attr: WindowAttributes,
         platform_attr: PlatformSpecificWindowBuilderAttributes,

src/platform_impl/windows/window.rs

@@ -85,7 +85,7 @@ pub struct Window {
 }
 
 impl Window {
-    pub fn new<T: 'static>(
+    pub(crate) fn new<T: 'static>(
         event_loop: &EventLoopWindowTarget<T>,
         w_attr: WindowAttributes,
         pl_attr: PlatformSpecificWindowBuilderAttributes,

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<Icon>,
         scale_factor: f64,

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 {
+pub(crate) struct WindowAttributes {
-    /// The dimensions of the window. If this is `None`, some platform-specific dimensions will be
-    /// used.
-    ///
-    /// The default is `None`.
     pub inner_size: Option<Size>,
-
-    /// 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<Size>,
-
-    /// 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<Size>,
-
-    /// 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<Position>,
-
-    /// 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<Fullscreen>,
-
-    /// The title of the window in the title bar.
-    ///
-    /// The default is `"winit window"`.
     pub title: String,
-
+    pub fullscreen: Option<Fullscreen>,
-    /// Whether the window should be maximized upon creation.
-    ///
-    /// The default is `false`.
     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<Icon>,
 }
 
@@ -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<P: Into<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