Add Window::builder, which replaces WindowBuilder::new

src/lib.rs

@@ -13,7 +13,7 @@
 //! Once this is done, there are two ways to create a [`Window`]:
 //!
 //!  - Calling [`Window::new(&event_loop)`][window_new].
-//!  - Calling [`let builder = WindowBuilder::new()`][window_builder_new] then [`builder.build(&event_loop)`][window_builder_build].
+//!  - Calling [`let builder = Window::builder()`][window_builder_new] then [`builder.build(&event_loop)`][window_builder_build].
 //!
 //! The first method is the simplest and will give you default values for everything. The second
 //! method allows you to customize the way your [`Window`] will look and behave by modifying the
@@ -63,11 +63,11 @@
 //! use winit::{
 //!     event::{Event, WindowEvent},
 //!     event_loop::{ControlFlow, EventLoop},
-//!     window::WindowBuilder,
+//!     window::Window,
 //! };
 //!
 //! let event_loop = EventLoop::new().unwrap();
-//! let window = WindowBuilder::new().build(&event_loop).unwrap();
+//! let window = Window::builder().build(&event_loop).unwrap();
 //!
 //! // ControlFlow::Poll continuously runs the event loop, even if the OS hasn't
 //! // dispatched any events. This is ideal for games and similar applications.
@@ -137,7 +137,7 @@
 //! [`WindowId`]: window::WindowId
 //! [`WindowBuilder`]: window::WindowBuilder
 //! [window_new]: window::Window::new
-//! [window_builder_new]: window::WindowBuilder::new
+//! [window_builder_new]: window::Window::builder
 //! [window_builder_build]: window::WindowBuilder::build
 //! [`Window::id()`]: window::Window::id
 //! [`WindowEvent`]: event::WindowEvent

src/platform/pump_events.rs

@@ -51,12 +51,12 @@ pub trait EventLoopExtPumpEvents {
     /// #         event::{Event, WindowEvent},
     /// #         event_loop::EventLoop,
     /// #         platform::pump_events::{EventLoopExtPumpEvents, PumpStatus},
-    /// #         window::WindowBuilder,
+    /// #         window::Window,
     /// #     };
     ///     let mut event_loop = EventLoop::new().unwrap();
     /// #
     /// #   SimpleLogger::new().init().unwrap();
-    ///     let window = WindowBuilder::new()
+    ///     let window = Window::builder()
     ///         .with_title("A fantastic window!")
     ///         .build(&event_loop)
     ///         .unwrap();

src/platform/x11.rs

@@ -159,13 +159,13 @@ pub trait WindowBuilderExtX11 {
     ///
     /// ```
     /// # use winit::dpi::{LogicalSize, PhysicalSize};
-    /// # use winit::window::WindowBuilder;
+    /// # use winit::window::Window;
     /// # use winit::platform::x11::WindowBuilderExtX11;
     /// // Specify the size in logical dimensions like this:
-    /// WindowBuilder::new().with_base_size(LogicalSize::new(400.0, 200.0));
+    /// Window::builder().with_base_size(LogicalSize::new(400.0, 200.0));
     ///
     /// // Or specify the size in physical dimensions like this:
-    /// WindowBuilder::new().with_base_size(PhysicalSize::new(400, 200));
+    /// Window::builder().with_base_size(PhysicalSize::new(400, 200));
     /// ```
     fn with_base_size<S: Into<Size>>(self, base_size: S) -> Self;
 
@@ -174,12 +174,12 @@ pub trait WindowBuilderExtX11 {
     /// # Example
     ///
     /// ```no_run
-    /// use winit::window::WindowBuilder;
+    /// use winit::window::Window;
     /// use winit::platform::x11::{XWindow, WindowBuilderExtX11};
     /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
     /// let event_loop = winit::event_loop::EventLoop::new().unwrap();
     /// let parent_window_id = std::env::args().nth(1).unwrap().parse::<XWindow>()?;
-    /// let window = WindowBuilder::new()
+    /// let window = Window::builder()
     ///     .with_embed_parent_window(parent_window_id)
     ///     .build(&event_loop)?;
     /// # Ok(()) }

src/window.rs

@@ -123,7 +123,9 @@ impl From<u64> for WindowId {
     }
 }
 
-/// Object that allows building windows.
+/// Configure windows before creation.
+///
+/// You can access this from [`Window::builder`].
 #[derive(Clone, Default)]
 #[must_use]
 pub struct WindowBuilder {
@@ -139,7 +141,7 @@ impl fmt::Debug for WindowBuilder {
     }
 }
 
-/// Attributes to use when creating a window.
+/// Attributes used when creating a window.
 #[derive(Debug, Clone)]
 pub struct WindowAttributes {
     pub inner_size: Option<Size>,
@@ -226,6 +228,7 @@ impl WindowAttributes {
 impl WindowBuilder {
     /// Initializes a new builder with default values.
     #[inline]
+    #[deprecated = "use `Window::builder` instead"]
     pub fn new() -> Self {
         Default::default()
     }
@@ -551,7 +554,7 @@ impl WindowBuilder {
 impl Window {
     /// Creates a new Window for platforms where this is appropriate.
     ///
-    /// This function is equivalent to [`WindowBuilder::new().build(event_loop)`].
+    /// This function is equivalent to [`Window::builder().build(event_loop)`].
     ///
     /// Error should be very rare and only occur in case of permission denied, incompatible system,
     ///  out of memory, etc.
@@ -561,11 +564,16 @@ impl Window {
     /// - **Web:** The window is created but not inserted into the web page automatically. Please
     ///   see the web platform module for more information.
     ///
-    /// [`WindowBuilder::new().build(event_loop)`]: WindowBuilder::build
+    /// [`Window::builder().build(event_loop)`]: WindowBuilder::build
     #[inline]
-    pub fn new(event_loop: &EventLoopWindowTarget) -> Result<Window, OsError> {
-        let builder = WindowBuilder::new();
-        builder.build(event_loop)
+    pub fn new<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> {
+        Window::builder().build(event_loop)
+    }
+
+    /// Create a new [`WindowBuilder`] which allows modifying the window's attributes before creation.
+    #[inline]
+    pub fn builder() -> WindowBuilder {
+        WindowBuilder::default()
     }
 
     /// Returns an identifier unique to the window.