From f25ddb3aa673037153b87c83a31c9130d448f16f Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:04:25 -0400 Subject: [PATCH 01/22] Add documentation comments to `bevy_window` --- crates/bevy_window/src/cursor.rs | 40 ++++++ crates/bevy_window/src/event.rs | 6 +- crates/bevy_window/src/lib.rs | 2 + crates/bevy_window/src/raw_window_handle.rs | 2 +- crates/bevy_window/src/system.rs | 1 + crates/bevy_window/src/window.rs | 134 +++++++++++--------- 6 files changed, 121 insertions(+), 64 deletions(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index 8fa0edfae1548..22db21d674378 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -1,39 +1,79 @@ /// The icon to display for a window's cursor +/// Examples of all of these cursors can be found [here](https://www.w3schools.com/cssref/playit.asp?filename=playcss_cursor) +/// This `enum` is simply a copy of a similar `enum` found in `winit`. +/// `winit`, in turn, simply used cursor types avilable in the browser. #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)] pub enum CursorIcon { + /// The platform-dependent default cursor. Default, + /// A simple crosshair. Crosshair, + /// A hand (often used to indicate links in web browsers). Hand, + /// Self explanatory. Arrow, + /// Indicates something is to be moved. Move, + /// Indicates text that may be selected or edited. Text, + /// Program busy indicator. Wait, + /// Help indicator (often rendered as a "?") Help, + /// Progress indicator. Shows that processing is being done. But in contrast + /// with "Wait" the user may still interact with the program. Often rendered + /// as a spinning beach ball, or an arrow with a watch or hourglass. Progress, + /// Cursor showing that something cannot be done. NotAllowed, + /// Indicates that a context menu is available ContextMenu, + /// Indicates that a cell (or set of cells) may be selected Cell, + /// Indicates vertical text that may be selected or edited VerticalText, + /// Indicates that an alias of something is to be created Alias, + /// Indicates something is to be copied Copy, + /// Indicates that the dragged item cannot be dropped here NoDrop, + /// Indicates that something can be grabbed Grab, + /// Indicates that something is grabbed. Grabbing, + /// Indicates that the user can scroll by dragging the mouse. AllScroll, + /// Indicates that the user can zoom in ZoomIn, + /// Indicates that the user can zoom out ZoomOut, + /// Indicates that an edge of a box is to be moved right (east) EResize, + /// Indicates that an edge of a box is to be moved up (north) NResize, + /// Indicates that an edge of a box is to be moved up and right (north/east) NeResize, + /// indicates that an edge of a box is to be moved up and left (north/west) NwResize, + /// Indicates that an edge of a box is to be moved down (south) SResize, + /// The cursor indicates that an edge of a box is to be moved down and right (south/east) SeResize, + /// The cursor indicates that an edge of a box is to be moved down and left (south/west) SwResize, + /// Indicates that an edge of a box is to be moved left (west) WResize, + /// Indicates a bidirectional resize cursor EwResize, + /// Indicates a bidirectional resize cursor NsResize, + /// Indicates a bidirectional resize cursor NeswResize, + /// Indicates a bidirectional resize cursor NwseResize, + /// Indicates that a column can be resized horizontally ColResize, + /// Indicates that the row can be resized vertically RowResize, } diff --git a/crates/bevy_window/src/event.rs b/crates/bevy_window/src/event.rs index 8673edf550c89..cfc1edb6f35ca 100644 --- a/crates/bevy_window/src/event.rs +++ b/crates/bevy_window/src/event.rs @@ -43,18 +43,18 @@ pub struct WindowCreated { pub struct WindowCloseRequested { pub id: WindowId, } - +/// An event that is sent whenenver the user's cursor moves. #[derive(Debug, Clone)] pub struct CursorMoved { pub id: WindowId, pub position: Vec2, } - +/// An event that is sent whenever the user's cursor enters a window. #[derive(Debug, Clone)] pub struct CursorEntered { pub id: WindowId, } - +/// An event that is sent whenever the user's cursor leaves a window. #[derive(Debug, Clone)] pub struct CursorLeft { pub id: WindowId, diff --git a/crates/bevy_window/src/lib.rs b/crates/bevy_window/src/lib.rs index 37cac585e0701..7e6bd0e85d461 100644 --- a/crates/bevy_window/src/lib.rs +++ b/crates/bevy_window/src/lib.rs @@ -1,3 +1,4 @@ +#[warn(missing_docs)] mod cursor; mod event; mod raw_window_handle; @@ -23,6 +24,7 @@ pub mod prelude { use bevy_app::prelude::*; use bevy_ecs::event::Events; +/// A plugin that defines an interface for windowing support in Bevy. pub struct WindowPlugin { pub add_primary_window: bool, pub exit_on_close: bool, diff --git a/crates/bevy_window/src/raw_window_handle.rs b/crates/bevy_window/src/raw_window_handle.rs index 76f1411261c80..52fbded56c928 100644 --- a/crates/bevy_window/src/raw_window_handle.rs +++ b/crates/bevy_window/src/raw_window_handle.rs @@ -26,7 +26,7 @@ impl RawWindowHandleWrapper { // https://github.com/rust-windowing/raw-window-handle/issues/59 unsafe impl Send for RawWindowHandleWrapper {} unsafe impl Sync for RawWindowHandleWrapper {} - +#[allow(missing_docs)] // Almost nobody uses this struct. pub struct HasRawWindowHandleWrapper(RawWindowHandle); // SAFE: the caller has validated that this is a valid context to get RawWindowHandle diff --git a/crates/bevy_window/src/system.rs b/crates/bevy_window/src/system.rs index 3dc8f6a45cb9b..b10482c0e7866 100644 --- a/crates/bevy_window/src/system.rs +++ b/crates/bevy_window/src/system.rs @@ -2,6 +2,7 @@ use crate::WindowCloseRequested; use bevy_app::AppExit; use bevy_ecs::event::{EventReader, EventWriter}; +/// A system that will automatically exit the app when the window is closed pub fn exit_on_window_close_system( mut app_exit_events: EventWriter, mut window_close_requested_events: EventReader, diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index 47c03d085ce7e..152b4d6444999 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -3,6 +3,7 @@ use bevy_utils::{tracing::warn, Uuid}; use raw_window_handle::RawWindowHandle; #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] +/// A unique ID for a [`Window`] pub struct WindowId(Uuid); /// Presentation mode for a window. @@ -39,14 +40,15 @@ pub enum PresentMode { } impl WindowId { + /// Creates a new [`WindowId`] pub fn new() -> Self { WindowId(Uuid::new_v4()) } - + /// The [`WindowId`] for the primary window pub fn primary() -> Self { WindowId(Uuid::from_u128(0)) } - + /// Get whether or not this [`WindowId`] is for the primary window pub fn is_primary(&self) -> bool { *self == WindowId::primary() } @@ -169,53 +171,45 @@ pub struct Window { pub canvas: Option, command_queue: Vec, } - +/// A command to be sent to a window. #[derive(Debug)] pub enum WindowCommand { + /// Set the window's [`WindowMode`] SetWindowMode { mode: WindowMode, resolution: (u32, u32), }, - SetTitle { - title: String, - }, - SetScaleFactor { - scale_factor: f64, - }, + /// Set the window's title + SetTitle { title: String }, + /// Set the window's scale factor + SetScaleFactor { scale_factor: f64 }, + /// Set the window's resolution SetResolution { logical_resolution: (f32, f32), scale_factor: f64, }, - SetPresentMode { - present_mode: PresentMode, - }, - SetResizable { - resizable: bool, - }, - SetDecorations { - decorations: bool, - }, - SetCursorLockMode { - locked: bool, - }, - SetCursorIcon { - icon: CursorIcon, - }, - SetCursorVisibility { - visible: bool, - }, - SetCursorPosition { - position: Vec2, - }, - SetMaximized { - maximized: bool, - }, - SetMinimized { - minimized: bool, - }, - SetPosition { - position: IVec2, - }, + /// Set the window's [`PresentMode`] + SetPresentMode { present_mode: PresentMode }, + /// Set whether or not the window is resizable + SetResizable { resizable: bool }, + /// Set whether or not the window has decorations + /// Examples of decorations include the close, full screen, and minimize buttons + SetDecorations { decorations: bool }, + /// Set whether or not the cursor's postition is locked + SetCursorLockMode { locked: bool }, + /// Set the cursor's [`CursorIcon`] + SetCursorIcon { icon: CursorIcon }, + /// Set whether or not the cursor is visible + SetCursorVisibility { visible: bool }, + /// Set the cursor's position + SetCursorPosition { position: Vec2 }, + /// Set whether or not the window is maxizimed + SetMaximized { maximized: bool }, + /// Set whether or not the window is minimized + SetMinimized { minimized: bool }, + /// Set the window's position on the screen + SetPosition { position: IVec2 }, + /// Set the window's [`WindowResizeConstraints`] SetResizeConstraints { resize_constraints: WindowResizeConstraints, }, @@ -236,6 +230,7 @@ pub enum WindowMode { } impl Window { + /// Creates a new [`Window`] pub fn new( id: WindowId, window_descriptor: &WindowDescriptor, @@ -271,7 +266,7 @@ impl Window { command_queue: Vec::new(), } } - + /// Get the window's [`WindowId`] #[inline] pub fn id(&self) -> WindowId { self.id @@ -332,7 +327,7 @@ impl Window { pub fn position(&self) -> Option { self.position } - + /// Set whether or not the window is maximized #[inline] pub fn set_maximized(&mut self, maximized: bool) { self.command_queue @@ -447,12 +442,12 @@ impl Window { pub fn scale_factor_override(&self) -> Option { self.scale_factor_override } - + /// Get the window's title #[inline] pub fn title(&self) -> &str { &self.title } - + /// Set the window's title pub fn set_title(&mut self, title: String) { self.title = title.to_string(); self.command_queue.push(WindowCommand::SetTitle { title }); @@ -460,68 +455,72 @@ impl Window { #[inline] #[doc(alias = "vsync")] + /// Get the window's [`PresentMode`] pub fn present_mode(&self) -> PresentMode { self.present_mode } #[inline] #[doc(alias = "set_vsync")] + /// Set the window's [`PresentMode`] pub fn set_present_mode(&mut self, present_mode: PresentMode) { self.present_mode = present_mode; self.command_queue .push(WindowCommand::SetPresentMode { present_mode }); } - + /// Get whether or not the window is resizable #[inline] pub fn resizable(&self) -> bool { self.resizable } - + /// Set whether or not the window is resizable pub fn set_resizable(&mut self, resizable: bool) { self.resizable = resizable; self.command_queue .push(WindowCommand::SetResizable { resizable }); } - + /// Get whether or not decorations are enabled + /// (Decorations are the minimize, maximize, and close buttons on desktop apps) #[inline] pub fn decorations(&self) -> bool { self.decorations } - + /// Set whether or not decorations are enabled + /// (Decorations are the minimize, maximize, and close buttons on desktop apps) pub fn set_decorations(&mut self, decorations: bool) { self.decorations = decorations; self.command_queue .push(WindowCommand::SetDecorations { decorations }); } - + /// Get whether or not the cursor is locked #[inline] pub fn cursor_locked(&self) -> bool { self.cursor_locked } - + /// Set whether or not the cursor is locked pub fn set_cursor_lock_mode(&mut self, lock_mode: bool) { self.cursor_locked = lock_mode; self.command_queue .push(WindowCommand::SetCursorLockMode { locked: lock_mode }); } - + /// Get whether or not the cursor is visible #[inline] pub fn cursor_visible(&self) -> bool { self.cursor_visible } - + /// Set whether or not the cursor is visible pub fn set_cursor_visibility(&mut self, visibile_mode: bool) { self.cursor_visible = visibile_mode; self.command_queue.push(WindowCommand::SetCursorVisibility { visible: visibile_mode, }); } - + /// Get the current [`CursorIcon`] #[inline] pub fn cursor_icon(&self) -> CursorIcon { self.cursor_icon } - + /// Set the [`CursorIcon`] pub fn set_cursor_icon(&mut self, icon: CursorIcon) { self.command_queue .push(WindowCommand::SetCursorIcon { icon }); @@ -540,7 +539,7 @@ impl Window { self.physical_cursor_position .map(|p| (p / self.scale_factor()).as_vec2()) } - + /// Set the cursor's position pub fn set_cursor_position(&mut self, position: Vec2) { self.command_queue .push(WindowCommand::SetCursorPosition { position }); @@ -557,12 +556,12 @@ impl Window { pub fn update_cursor_physical_position_from_backend(&mut self, cursor_position: Option) { self.physical_cursor_position = cursor_position; } - + /// Get the window's [`WindowMode`] #[inline] pub fn mode(&self) -> WindowMode { self.mode } - + /// Set the window's [`WindowMode`] pub fn set_mode(&mut self, mode: WindowMode) { self.mode = mode; self.command_queue.push(WindowCommand::SetWindowMode { @@ -570,36 +569,50 @@ impl Window { resolution: (self.physical_width, self.physical_height), }); } - + /// Removes all commands from the window's command queue and returns them #[inline] pub fn drain_commands(&mut self) -> impl Iterator + '_ { self.command_queue.drain(..) } - + /// Get whether or not the window has focus + /// A window loses focus when the user switches to another window, and regains focus when the user uses the window again #[inline] pub fn is_focused(&self) -> bool { self.focused } - + /// Get the [`RawWindowHandleWrapper`] corresponding to this window pub fn raw_window_handle(&self) -> RawWindowHandleWrapper { self.raw_window_handle.clone() } } - +/// A [`Window`]'s properties #[derive(Debug, Clone)] pub struct WindowDescriptor { + /// The window's width pub width: f32, + /// The window's height pub height: f32, + /// The window's position on the screen pub position: Option, + /// The size limits of the window pub resize_constraints: WindowResizeConstraints, pub scale_factor_override: Option, + /// The window's title pub title: String, #[doc(alias = "vsync")] + /// The window's [`PresentMode`] + /// Used to select whether or not VSync is used pub present_mode: PresentMode, + /// Whether or not the window can be resized pub resizable: bool, + /// Whether or not the window has decorations + /// On desktop platforms, decorations are the minimize, maximize, and exit buttons on a window pub decorations: bool, + /// Whether or not the cursor is visible pub cursor_visible: bool, + /// Whether or not the cursor is locked to a particular position pub cursor_locked: bool, + /// The window's [`WindowMode`] pub mode: WindowMode, /// Sets whether the background of the window should be transparent. /// # Platform-specific @@ -609,6 +622,7 @@ pub struct WindowDescriptor { /// macOS X transparent works with winit out of the box, so this issue might be related to: /// Windows 11 is related to pub transparent: bool, + /// The selector used to locate the that Bevy will draw on #[cfg(target_arch = "wasm32")] pub canvas: Option, } From 1f0b6f758bcc4f8d8bf137dad2c1797c5c873312 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:15:14 -0400 Subject: [PATCH 02/22] Cargo fmt for `bevy_window` documentation comments --- crates/bevy_window/src/cursor.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index 22db21d674378..915d246ffb4eb 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -1,6 +1,6 @@ /// The icon to display for a window's cursor /// Examples of all of these cursors can be found [here](https://www.w3schools.com/cssref/playit.asp?filename=playcss_cursor) -/// This `enum` is simply a copy of a similar `enum` found in `winit`. +/// This `enum` is simply a copy of a similar `enum` found in `winit`. /// `winit`, in turn, simply used cursor types avilable in the browser. #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)] pub enum CursorIcon { From c15fd98ec340b6d0365bd937c94a3595528746aa Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:42:39 -0400 Subject: [PATCH 03/22] Fix explanation for `CursorIcon::Arrow` --- crates/bevy_window/src/cursor.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index 915d246ffb4eb..e0db9dbcd50ab 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -10,7 +10,7 @@ pub enum CursorIcon { Crosshair, /// A hand (often used to indicate links in web browsers). Hand, - /// Self explanatory. + /// An arrow. This is the default cursor on most systems. Arrow, /// Indicates something is to be moved. Move, From faa5318d6b226eaf1e9af559d7d9c54f081fd8e7 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:45:18 -0400 Subject: [PATCH 04/22] Link to `winit` in `bevy_window::CursorIcon` --- crates/bevy_window/src/cursor.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index e0db9dbcd50ab..45ec46204dd44 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -1,7 +1,7 @@ /// The icon to display for a window's cursor /// Examples of all of these cursors can be found [here](https://www.w3schools.com/cssref/playit.asp?filename=playcss_cursor) -/// This `enum` is simply a copy of a similar `enum` found in `winit`. -/// `winit`, in turn, simply used cursor types avilable in the browser. +/// This `enum` is simply a copy of a similar `enum` found in [`winit`](https://docs.rs/winit/latest/winit/window/enum.CursorIcon.html). +/// `winit`, in turn, mostly copied cursor types avilable in the browser. #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)] pub enum CursorIcon { /// The platform-dependent default cursor. From 6589334fc6b6037e27b62f98753ab6a24d738fd8 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Fri, 25 Mar 2022 16:54:23 -0400 Subject: [PATCH 05/22] Improve documentation for `bevy_window::WindowDescriptor` --- crates/bevy_window/src/window.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index 152b4d6444999..36a31451afd54 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -586,6 +586,19 @@ impl Window { } } /// A [`Window`]'s properties +/// # Creating a `WindowDescriptor` +/// As `WindowDescriptor` is simply a `struct` that implements `Default`, creating one isn't any different from any other `struct`. +/// However, for Bevy to use it, you need to add it to your [`bevy_app::App`] with [`bevy_app::App:insert_resource()`]. +/// ```rust +/// # use bevy_app::App; +/// # use bevy_window::WindowDescriptor; +/// # fn main(){ +/// App::new().insert_resource(WindowDescriptor{ +/// title: String::from("Creating a WindowDescriptor"), +/// ..Default::default() +/// }); +/// # } +/// ``` #[derive(Debug, Clone)] pub struct WindowDescriptor { /// The window's width From 2d7a807308800bdfa47f05593e0b89545157ba94 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sat, 26 Mar 2022 09:20:39 -0400 Subject: [PATCH 06/22] Change a comment in crates/bevy_window/src/raw_window_handle.rs Co-authored-by: Alice Cecile --- crates/bevy_window/src/raw_window_handle.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_window/src/raw_window_handle.rs b/crates/bevy_window/src/raw_window_handle.rs index 52fbded56c928..4cb62a7155483 100644 --- a/crates/bevy_window/src/raw_window_handle.rs +++ b/crates/bevy_window/src/raw_window_handle.rs @@ -26,7 +26,7 @@ impl RawWindowHandleWrapper { // https://github.com/rust-windowing/raw-window-handle/issues/59 unsafe impl Send for RawWindowHandleWrapper {} unsafe impl Sync for RawWindowHandleWrapper {} -#[allow(missing_docs)] // Almost nobody uses this struct. +#[doc(hidden)] // Add docs later; this is an obscure implementation detail pub struct HasRawWindowHandleWrapper(RawWindowHandle); // SAFE: the caller has validated that this is a valid context to get RawWindowHandle From 6fe9f488ee584a1a3231ac86f49484da8632b4f5 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sat, 26 Mar 2022 09:25:28 -0400 Subject: [PATCH 07/22] Add a link in crates/bevy_window/src/lib.rs Co-authored-by: Alice Cecile --- crates/bevy_window/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_window/src/lib.rs b/crates/bevy_window/src/lib.rs index 7e6bd0e85d461..a507336dc167c 100644 --- a/crates/bevy_window/src/lib.rs +++ b/crates/bevy_window/src/lib.rs @@ -24,7 +24,7 @@ pub mod prelude { use bevy_app::prelude::*; use bevy_ecs::event::Events; -/// A plugin that defines an interface for windowing support in Bevy. +/// A [`Plugin`] that defines an interface for windowing support in Bevy. pub struct WindowPlugin { pub add_primary_window: bool, pub exit_on_close: bool, From 81f178ca6427a27ce919dbf1f728c0f4ec88650f Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sat, 26 Mar 2022 09:34:32 -0400 Subject: [PATCH 08/22] Fix a typo in `bevy_window::WindowDescriptor` --- crates/bevy_window/src/window.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index 36a31451afd54..bb75280a24f23 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -172,6 +172,7 @@ pub struct Window { command_queue: Vec, } /// A command to be sent to a window. +/// This is used when writing a plugin #[derive(Debug)] pub enum WindowCommand { /// Set the window's [`WindowMode`] @@ -588,7 +589,7 @@ impl Window { /// A [`Window`]'s properties /// # Creating a `WindowDescriptor` /// As `WindowDescriptor` is simply a `struct` that implements `Default`, creating one isn't any different from any other `struct`. -/// However, for Bevy to use it, you need to add it to your [`bevy_app::App`] with [`bevy_app::App:insert_resource()`]. +/// However, for Bevy to use it, you need to add it to your [`bevy_app::App`] with [`bevy_app::App::insert_resource()`]. /// ```rust /// # use bevy_app::App; /// # use bevy_window::WindowDescriptor; From 8edd7a4e908617119eed872dd3f9e8f837dae006 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sat, 26 Mar 2022 10:04:34 -0400 Subject: [PATCH 09/22] Clarify `WindowCommand` --- crates/bevy_window/src/window.rs | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index bb75280a24f23..4b7f5f34fefb8 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -131,7 +131,8 @@ impl WindowResizeConstraints { } /// An operating system window that can present content and receive user input. -/// +/// To create a window, use a [`bevy_ecs::event::EventWriter`]`<`[`crate::CreateWindow`]`>` +/// /// ## Window Sizes /// /// There are three sizes associated with a window. The physical size which is @@ -145,6 +146,23 @@ impl WindowResizeConstraints { /// requested size due to operating system limits on the window size, or the /// quantization of the logical size when converting the physical size to the /// logical size through the scaling factor. +/// +/// ## Accessing a `Window` from a system +/// To access a `Window` from a system, use [`bevy_ecs::change_detection::ResMut`]`<`[`crate::Windows`]`>` +/// ### Example +/// ```no_run +/// # use bevy_app::App; +/// # use bevy_window::Windows; +/// # use bevy_ecs::change_detection::ResMut; +/// # fn main(){ +/// # App::new().add_system(access_window_system).run(); +/// # } +/// fn access_window_system(mut windows: ResMut){ +/// for mut window in windows.iter_mut(){ +/// window.set_title(String::from("Yay, I'm a window!")); +/// } +/// } +/// ``` #[derive(Debug)] pub struct Window { id: WindowId, @@ -172,7 +190,8 @@ pub struct Window { command_queue: Vec, } /// A command to be sent to a window. -/// This is used when writing a plugin +/// Bevy apps don't interact with this `enum` directly. Instead, they should use the methods on [`Window`]. +/// This `enum` is meant for authors of windowing plugins. See the documentation on [`crate::WindowPlugin`] for more information. #[derive(Debug)] pub enum WindowCommand { /// Set the window's [`WindowMode`] From 2ac5ab6bfe64df58b7377c94909bd114c672d8d8 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sat, 26 Mar 2022 10:06:26 -0400 Subject: [PATCH 10/22] Fix `cargo fmt` error --- crates/bevy_window/src/window.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index 4b7f5f34fefb8..e120efa02a2cb 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -132,7 +132,7 @@ impl WindowResizeConstraints { /// An operating system window that can present content and receive user input. /// To create a window, use a [`bevy_ecs::event::EventWriter`]`<`[`crate::CreateWindow`]`>` -/// +/// /// ## Window Sizes /// /// There are three sizes associated with a window. The physical size which is @@ -146,7 +146,7 @@ impl WindowResizeConstraints { /// requested size due to operating system limits on the window size, or the /// quantization of the logical size when converting the physical size to the /// logical size through the scaling factor. -/// +/// /// ## Accessing a `Window` from a system /// To access a `Window` from a system, use [`bevy_ecs::change_detection::ResMut`]`<`[`crate::Windows`]`>` /// ### Example From 465107cf7d8e231fc0455a474c5cbc2b2e5310eb Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sun, 27 Mar 2022 08:41:34 -0400 Subject: [PATCH 11/22] Add newlines to crates/bevy_window/src/window.rs Co-authored-by: Alice Cecile --- crates/bevy_window/src/window.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index e120efa02a2cb..4989fd559f036 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -606,7 +606,9 @@ impl Window { } } /// A [`Window`]'s properties +/// /// # Creating a `WindowDescriptor` +/// /// As `WindowDescriptor` is simply a `struct` that implements `Default`, creating one isn't any different from any other `struct`. /// However, for Bevy to use it, you need to add it to your [`bevy_app::App`] with [`bevy_app::App::insert_resource()`]. /// ```rust From 84f8e6a2246e114902715af2262495d776deeb5b Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sun, 27 Mar 2022 08:44:19 -0400 Subject: [PATCH 12/22] Change a doc comment in crates/bevy_window/src/window.rs Co-authored-by: Alice Cecile --- crates/bevy_window/src/window.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index 4989fd559f036..ae705ee264d4d 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -131,7 +131,7 @@ impl WindowResizeConstraints { } /// An operating system window that can present content and receive user input. -/// To create a window, use a [`bevy_ecs::event::EventWriter`]`<`[`crate::CreateWindow`]`>` +/// To create a window, use a [`EventWriter`]`(`crate::CreateWindow). /// /// ## Window Sizes /// From afa3506d6f831583d5ecd627a181a30dcb0be996 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Sun, 27 Mar 2022 15:52:23 -0400 Subject: [PATCH 13/22] Fix yet another typo --- crates/bevy_window/src/window.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index ae705ee264d4d..d2d56cb750c22 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -131,7 +131,7 @@ impl WindowResizeConstraints { } /// An operating system window that can present content and receive user input. -/// To create a window, use a [`EventWriter`]`(`crate::CreateWindow). +/// To create a window, use a [`EventWriter`](`crate::CreateWindow`). /// /// ## Window Sizes /// From dd6f26879f92b8014482a373a72c337f0be396ad Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Wed, 15 Jun 2022 14:05:34 -0400 Subject: [PATCH 14/22] Improve formatting for `bevy_window` doc comments Co-authored-by: Nicola Papale --- crates/bevy_window/src/cursor.rs | 5 +++-- crates/bevy_window/src/system.rs | 2 +- crates/bevy_window/src/window.rs | 22 +++++++++++++--------- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index 45ec46204dd44..c80d7af3c62fa 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -1,5 +1,6 @@ -/// The icon to display for a window's cursor -/// Examples of all of these cursors can be found [here](https://www.w3schools.com/cssref/playit.asp?filename=playcss_cursor) +/// The icon to display for a window's cursor. +/// +/// Examples of all of these cursors can be found [here](https://www.w3schools.com/cssref/playit.asp?filename=playcss_cursor). /// This `enum` is simply a copy of a similar `enum` found in [`winit`](https://docs.rs/winit/latest/winit/window/enum.CursorIcon.html). /// `winit`, in turn, mostly copied cursor types avilable in the browser. #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)] diff --git a/crates/bevy_window/src/system.rs b/crates/bevy_window/src/system.rs index b10482c0e7866..6d46df31c8fc2 100644 --- a/crates/bevy_window/src/system.rs +++ b/crates/bevy_window/src/system.rs @@ -2,7 +2,7 @@ use crate::WindowCloseRequested; use bevy_app::AppExit; use bevy_ecs::event::{EventReader, EventWriter}; -/// A system that will automatically exit the app when the window is closed +/// A system that will automatically exit the app when the window is closed. pub fn exit_on_window_close_system( mut app_exit_events: EventWriter, mut window_close_requested_events: EventReader, diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index d2d56cb750c22..8873c59b79944 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -3,7 +3,7 @@ use bevy_utils::{tracing::warn, Uuid}; use raw_window_handle::RawWindowHandle; #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -/// A unique ID for a [`Window`] +/// A unique ID for a [`Window`]. pub struct WindowId(Uuid); /// Presentation mode for a window. @@ -40,15 +40,15 @@ pub enum PresentMode { } impl WindowId { - /// Creates a new [`WindowId`] + /// Creates a new [`WindowId`]. pub fn new() -> Self { WindowId(Uuid::new_v4()) } - /// The [`WindowId`] for the primary window + /// The [`WindowId`] for the primary window. pub fn primary() -> Self { WindowId(Uuid::from_u128(0)) } - /// Get whether or not this [`WindowId`] is for the primary window + /// Get whether or not this [`WindowId`] is for the primary window. pub fn is_primary(&self) -> bool { *self == WindowId::primary() } @@ -131,6 +131,7 @@ impl WindowResizeConstraints { } /// An operating system window that can present content and receive user input. +/// /// To create a window, use a [`EventWriter`](`crate::CreateWindow`). /// /// ## Window Sizes @@ -148,7 +149,9 @@ impl WindowResizeConstraints { /// logical size through the scaling factor. /// /// ## Accessing a `Window` from a system -/// To access a `Window` from a system, use [`bevy_ecs::change_detection::ResMut`]`<`[`crate::Windows`]`>` +/// +/// To access a `Window` from a system, use [`bevy_ecs::change_detection::ResMut`]`<`[`crate::Windows`]`>`. +/// /// ### Example /// ```no_run /// # use bevy_app::App; @@ -190,20 +193,21 @@ pub struct Window { command_queue: Vec, } /// A command to be sent to a window. +/// /// Bevy apps don't interact with this `enum` directly. Instead, they should use the methods on [`Window`]. /// This `enum` is meant for authors of windowing plugins. See the documentation on [`crate::WindowPlugin`] for more information. #[derive(Debug)] pub enum WindowCommand { - /// Set the window's [`WindowMode`] + /// Set the window's [`WindowMode`]. SetWindowMode { mode: WindowMode, resolution: (u32, u32), }, - /// Set the window's title + /// Set the window's title. SetTitle { title: String }, - /// Set the window's scale factor + /// Set the window's scale factor. SetScaleFactor { scale_factor: f64 }, - /// Set the window's resolution + /// Set the window's resolution. SetResolution { logical_resolution: (f32, f32), scale_factor: f64, From 0b8537445e45f2867e9aeaf6011f9311995f3435 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Wed, 15 Jun 2022 14:16:36 -0400 Subject: [PATCH 15/22] Reformat `window.rs` --- crates/bevy_window/src/window.rs | 48 ++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 12 deletions(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index d890186c2cd11..7c3fa4c77efb2 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -204,35 +204,59 @@ pub enum WindowCommand { resolution: (u32, u32), }, /// Set the window's title. - SetTitle { title: String }, + SetTitle { + title: String, + }, /// Set the window's scale factor. - SetScaleFactor { scale_factor: f64 }, + SetScaleFactor { + scale_factor: f64, + }, /// Set the window's resolution. SetResolution { logical_resolution: (f32, f32), scale_factor: f64, }, /// Set the window's [`PresentMode`] - SetPresentMode { present_mode: PresentMode }, + SetPresentMode { + present_mode: PresentMode, + }, /// Set whether or not the window is resizable - SetResizable { resizable: bool }, + SetResizable { + resizable: bool, + }, /// Set whether or not the window has decorations /// Examples of decorations include the close, full screen, and minimize buttons - SetDecorations { decorations: bool }, + SetDecorations { + decorations: bool, + }, /// Set whether or not the cursor's postition is locked - SetCursorLockMode { locked: bool }, + SetCursorLockMode { + locked: bool, + }, /// Set the cursor's [`CursorIcon`] - SetCursorIcon { icon: CursorIcon }, + SetCursorIcon { + icon: CursorIcon, + }, /// Set whether or not the cursor is visible - SetCursorVisibility { visible: bool }, + SetCursorVisibility { + visible: bool, + }, /// Set the cursor's position - SetCursorPosition { position: Vec2 }, + SetCursorPosition { + position: Vec2, + }, /// Set whether or not the window is maxizimed - SetMaximized { maximized: bool }, + SetMaximized { + maximized: bool, + }, /// Set whether or not the window is minimized - SetMinimized { minimized: bool }, + SetMinimized { + minimized: bool, + }, /// Set the window's position on the screen - SetPosition { position: IVec2 }, + SetPosition { + position: IVec2, + }, /// Set the window's [`WindowResizeConstraints`] SetResizeConstraints { resize_constraints: WindowResizeConstraints, From 1bb7b10ea2c72f591ffa9c250694d4ed174ad354 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Wed, 15 Jun 2022 14:56:10 -0400 Subject: [PATCH 16/22] More documentation improvements for `window.rs` --- crates/bevy_window/src/window.rs | 130 ++++++++++++++++++++++--------- 1 file changed, 92 insertions(+), 38 deletions(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index 7c3fa4c77efb2..c3f94a829e8e4 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -72,6 +72,7 @@ impl Default for WindowId { } /// The size limits on a window. +/// /// These values are measured in logical pixels, so the user's /// scale factor does affect the size limits on the window. /// Please note that if the window is resizable, then when the window is @@ -216,44 +217,45 @@ pub enum WindowCommand { logical_resolution: (f32, f32), scale_factor: f64, }, - /// Set the window's [`PresentMode`] + /// Set the window's [`PresentMode`]. SetPresentMode { present_mode: PresentMode, }, - /// Set whether or not the window is resizable + /// Set whether or not the window is resizable. SetResizable { resizable: bool, }, - /// Set whether or not the window has decorations + /// Set whether or not the window has decorations. + /// /// Examples of decorations include the close, full screen, and minimize buttons SetDecorations { decorations: bool, }, - /// Set whether or not the cursor's postition is locked + /// Set whether or not the cursor's postition is locked. SetCursorLockMode { locked: bool, }, - /// Set the cursor's [`CursorIcon`] + /// Set the cursor's [`CursorIcon`]. SetCursorIcon { icon: CursorIcon, }, - /// Set whether or not the cursor is visible + /// Set whether or not the cursor is visible. SetCursorVisibility { visible: bool, }, - /// Set the cursor's position + /// Set the cursor's position. SetCursorPosition { position: Vec2, }, - /// Set whether or not the window is maxizimed + /// Set whether or not the window is maxizimed. SetMaximized { maximized: bool, }, - /// Set whether or not the window is minimized + /// Set whether or not the window is minimized. SetMinimized { minimized: bool, }, - /// Set the window's position on the screen + /// Set the window's position on the screen. SetPosition { position: IVec2, }, @@ -264,22 +266,23 @@ pub enum WindowCommand { Close, } -/// Defines the way a window is displayed +/// Defines the way a window is displayed. #[derive(Debug, Clone, Copy, PartialEq)] pub enum WindowMode { - /// Creates a window that uses the given size + /// Creates a window that uses the given size. Windowed, - /// Creates a borderless window that uses the full size of the screen + /// Creates a borderless window that uses the full size of the screen. BorderlessFullscreen, - /// Creates a fullscreen window that will render at desktop resolution. The app will use the closest supported size - /// from the given size and scale it to fit the screen. + /// Creates a fullscreen window that will render at desktop resolution. + /// + /// The app will use the closest supported size from the given size and scale it to fit the screen. SizedFullscreen, - /// Creates a fullscreen window that uses the maximum supported size + /// Creates a fullscreen window that uses the maximum supported size. Fullscreen, } impl Window { - /// Creates a new [`Window`] + /// Creates a new [`Window`]. pub fn new( id: WindowId, window_descriptor: &WindowDescriptor, @@ -315,7 +318,7 @@ impl Window { command_queue: Vec::new(), } } - /// Get the window's [`WindowId`] + /// Get the window's [`WindowId`]. #[inline] pub fn id(&self) -> WindowId { self.id @@ -376,7 +379,7 @@ impl Window { pub fn position(&self) -> Option { self.position } - /// Set whether or not the window is maximized + /// Set whether or not the window is maximized. #[inline] pub fn set_maximized(&mut self, maximized: bool) { self.command_queue @@ -436,7 +439,7 @@ impl Window { }); } - /// Override the os-reported scaling factor + /// Override the os-reported scaling factor. #[allow(clippy::float_cmp)] pub fn set_scale_factor_override(&mut self, scale_factor: Option) { if self.scale_factor_override == scale_factor { @@ -481,22 +484,25 @@ impl Window { } /// The window scale factor as reported by the window backend. + /// /// This value is unaffected by [`scale_factor_override`](Window::scale_factor_override). #[inline] pub fn backend_scale_factor(&self) -> f64 { self.backend_scale_factor } - + /// The scale factor set with [`set_scale_factor_override`](Window::set_scale_factor_override). + /// + /// This value may be different from the scale factor reported by the window backend. #[inline] pub fn scale_factor_override(&self) -> Option { self.scale_factor_override } - /// Get the window's title + /// Get the window's title. #[inline] pub fn title(&self) -> &str { &self.title } - /// Set the window's title + /// Set the window's title. pub fn set_title(&mut self, title: String) { self.title = title.to_string(); self.command_queue.push(WindowCommand::SetTitle { title }); @@ -504,60 +510,94 @@ impl Window { #[inline] #[doc(alias = "vsync")] - /// Get the window's [`PresentMode`] + /// Get the window's [`PresentMode`]. pub fn present_mode(&self) -> PresentMode { self.present_mode } #[inline] #[doc(alias = "set_vsync")] - /// Set the window's [`PresentMode`] + /// Set the window's [`PresentMode`]. pub fn set_present_mode(&mut self, present_mode: PresentMode) { self.present_mode = present_mode; self.command_queue .push(WindowCommand::SetPresentMode { present_mode }); } - /// Get whether or not the window is resizable + /// Get whether or not the window is resizable. #[inline] pub fn resizable(&self) -> bool { self.resizable } - /// Set whether or not the window is resizable + /// Set whether or not the window is resizable. pub fn set_resizable(&mut self, resizable: bool) { self.resizable = resizable; self.command_queue .push(WindowCommand::SetResizable { resizable }); } - /// Get whether or not decorations are enabled + /// Get whether or not decorations are enabled. + /// /// (Decorations are the minimize, maximize, and close buttons on desktop apps) + /// + /// ## Platform-specific + /// + /// **iOS**, **Android**, and the **Web** do not have decorations. #[inline] pub fn decorations(&self) -> bool { self.decorations } - /// Set whether or not decorations are enabled + /// Set whether or not decorations are enabled. + /// /// (Decorations are the minimize, maximize, and close buttons on desktop apps) + /// + /// ## Platform-specific + /// + /// **iOS**, **Android**, and the **Web** do not have decorations. pub fn set_decorations(&mut self, decorations: bool) { self.decorations = decorations; self.command_queue .push(WindowCommand::SetDecorations { decorations }); } - /// Get whether or not the cursor is locked + /// Get whether or not the cursor is locked. + /// + /// ## Platform-specific + /// + /// - **macOS** doesn't support cursor lock, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information. + /// - **iOS/Android** don't have cursors. #[inline] pub fn cursor_locked(&self) -> bool { self.cursor_locked } - /// Set whether or not the cursor is locked + /// Set whether or not the cursor is locked. + /// + /// This doesn't hide the cursor. For that, use [`set_cursor_visibility`](Window::set_cursor_visibility) + /// + /// ## Platform-specific + /// + /// - **macOS** doesn't support cursor lock, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information. + /// - **iOS/Android** don't have cursors. pub fn set_cursor_lock_mode(&mut self, lock_mode: bool) { self.cursor_locked = lock_mode; self.command_queue .push(WindowCommand::SetCursorLockMode { locked: lock_mode }); } - /// Get whether or not the cursor is visible + /// Get whether or not the cursor is visible. + /// + /// ## Platform-specific + /// + /// - **Windows**, **X11**, and **Wayland**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_lock_mode`](Window::set_cursor_lock_mode). + /// - **macOS**: The cursor is hidden only when the window is focused. + /// - **iOS** and **Android** do not have cursors #[inline] pub fn cursor_visible(&self) -> bool { self.cursor_visible } - /// Set whether or not the cursor is visible + /// Set whether or not the cursor is visible. + /// + /// ## Platform-specific + /// + /// - **Windows**, **X11**, and **Wayland**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_lock_mode`](Window::set_cursor_lock_mode). + /// - **macOS**: The cursor is hidden only when the window is focused. + /// - **iOS** and **Android** do not have cursors pub fn set_cursor_visibility(&mut self, visibile_mode: bool) { self.cursor_visible = visibile_mode; self.command_queue.push(WindowCommand::SetCursorVisibility { @@ -618,7 +658,8 @@ impl Window { resolution: (self.physical_width, self.physical_height), }); } - /// Close the operating system window corresponding to this [`Window`]. + /// Close the operating system window corresponding to this [`Window`]. + /// /// This will also lead to this [`Window`] being removed from the /// [`Windows`] resource. /// @@ -636,7 +677,8 @@ impl Window { pub fn drain_commands(&mut self) -> impl Iterator + '_ { self.command_queue.drain(..) } - /// Get whether or not the window has focus + /// Get whether or not the window has focus. + /// /// A window loses focus when the user switches to another window, and regains focus when the user uses the window again #[inline] pub fn is_focused(&self) -> bool { @@ -647,7 +689,9 @@ impl Window { self.raw_window_handle.clone() } - /// The "html canvas" element selector. If set, this selector will be used to find a matching html canvas element, + /// The "html canvas" element selector. + /// + /// If set, this selector will be used to find a matching html canvas element, /// rather than creating a new one. /// Uses the [CSS selector format](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector). /// @@ -681,29 +725,36 @@ impl Window { #[derive(Debug, Clone)] pub struct WindowDescriptor { /// The requested logical width of the window's client area. + /// /// May vary from the physical width due to different pixel density on different monitors. pub width: f32, /// The requested logical height of the window's client area. + /// /// May vary from the physical height due to different pixel density on different monitors. pub height: f32, /// The position on the screen that the window will be centered at. + /// /// If set to `None`, some platform-specific position will be chosen. pub position: Option, /// Sets minimum and maximum resize limits. pub resize_constraints: WindowResizeConstraints, /// Overrides the window's ratio of physical pixels to logical pixels. + /// /// If there are some scaling problems on X11 try to set this option to `Some(1.0)`. pub scale_factor_override: Option, /// Sets the title that displays on the window top bar, on the system task bar and other OS specific places. + /// /// ## Platform-specific /// - Web: Unsupported. pub title: String, /// Controls when a frame is presented to the screen. #[doc(alias = "vsync")] - /// The window's [`PresentMode`] + /// The window's [`PresentMode`]. + /// /// Used to select whether or not VSync is used pub present_mode: PresentMode, /// Sets whether the window is resizable. + /// /// ## Platform-specific /// - iOS / Android / Web: Unsupported. pub resizable: bool, @@ -716,6 +767,7 @@ pub struct WindowDescriptor { /// Sets the [`WindowMode`](crate::WindowMode). pub mode: WindowMode, /// Sets whether the background of the window should be transparent. + /// /// ## Platform-specific /// - iOS / Android / Web: Unsupported. /// - macOS X: Not working as expected. @@ -723,7 +775,9 @@ pub struct WindowDescriptor { /// macOS X transparent works with winit out of the box, so this issue might be related to: /// Windows 11 is related to pub transparent: bool, - /// The "html canvas" element selector. If set, this selector will be used to find a matching html canvas element, + /// The "html canvas" element selector. + /// + /// If set, this selector will be used to find a matching html canvas element, /// rather than creating a new one. /// Uses the [CSS selector format](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector). /// From d712feaad1c613b7a197d0b587263c31692fbba0 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Thu, 16 Jun 2022 09:08:17 -0400 Subject: [PATCH 17/22] Improve formatting for `cursor.rs` --- crates/bevy_window/src/cursor.rs | 55 ++++++++++++++++---------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index c80d7af3c62fa..1e2ee7e113dd0 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -21,60 +21,61 @@ pub enum CursorIcon { Wait, /// Help indicator (often rendered as a "?") Help, - /// Progress indicator. Shows that processing is being done. But in contrast - /// with "Wait" the user may still interact with the program. Often rendered - /// as a spinning beach ball, or an arrow with a watch or hourglass. + /// Progress indicator. Shows that processing is being done. + /// + /// But in contrast with "Wait" the user may still interact with the program. + /// Often rendered as a spinning beach ball, or an arrow with a watch or hourglass. Progress, /// Cursor showing that something cannot be done. NotAllowed, - /// Indicates that a context menu is available + /// Indicates that a context menu is available. ContextMenu, - /// Indicates that a cell (or set of cells) may be selected + /// Indicates that a cell (or set of cells) may be selected. Cell, - /// Indicates vertical text that may be selected or edited + /// Indicates vertical text that may be selected or edited. VerticalText, - /// Indicates that an alias of something is to be created + /// Indicates that an alias of something is to be created. Alias, - /// Indicates something is to be copied + /// Indicates something is to be copied. Copy, - /// Indicates that the dragged item cannot be dropped here + /// Indicates that the dragged item cannot be dropped here. NoDrop, - /// Indicates that something can be grabbed + /// Indicates that something can be grabbed. Grab, - /// Indicates that something is grabbed. + /// Indicates that something is grabbed. Grabbing, /// Indicates that the user can scroll by dragging the mouse. AllScroll, - /// Indicates that the user can zoom in + /// Indicates that the user can zoom in. ZoomIn, - /// Indicates that the user can zoom out + /// Indicates that the user can zoom out. ZoomOut, - /// Indicates that an edge of a box is to be moved right (east) + /// Indicates that an edge of a box is to be moved right (east). EResize, - /// Indicates that an edge of a box is to be moved up (north) + /// Indicates that an edge of a box is to be moved up (north). NResize, - /// Indicates that an edge of a box is to be moved up and right (north/east) + /// Indicates that an edge of a box is to be moved up and right (north/east). NeResize, - /// indicates that an edge of a box is to be moved up and left (north/west) + /// indicates that an edge of a box is to be moved up and left (north/west). NwResize, - /// Indicates that an edge of a box is to be moved down (south) + /// Indicates that an edge of a box is to be moved down (south). SResize, - /// The cursor indicates that an edge of a box is to be moved down and right (south/east) + /// The cursor indicates that an edge of a box is to be moved down and right (south/east). SeResize, - /// The cursor indicates that an edge of a box is to be moved down and left (south/west) + /// The cursor indicates that an edge of a box is to be moved down and left (south/west). SwResize, - /// Indicates that an edge of a box is to be moved left (west) + /// Indicates that an edge of a box is to be moved left (west). WResize, - /// Indicates a bidirectional resize cursor + /// Indicates a bidirectional resize cursor. EwResize, - /// Indicates a bidirectional resize cursor + /// Indicates a bidirectional resize cursor. NsResize, - /// Indicates a bidirectional resize cursor + /// Indicates a bidirectional resize cursor. NeswResize, - /// Indicates a bidirectional resize cursor + /// Indicates a bidirectional resize cursor. NwseResize, - /// Indicates that a column can be resized horizontally + /// Indicates that a column can be resized horizontally. ColResize, - /// Indicates that the row can be resized vertically + /// Indicates that the row can be resized vertically. RowResize, } From 5290b879d90d190eb81f3c7220fae690411ae395 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Thu, 16 Jun 2022 09:09:32 -0400 Subject: [PATCH 18/22] Improve formatting for `event.rs` documentation --- crates/bevy_window/src/event.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/bevy_window/src/event.rs b/crates/bevy_window/src/event.rs index 95556285692ad..c57222973b84a 100644 --- a/crates/bevy_window/src/event.rs +++ b/crates/bevy_window/src/event.rs @@ -3,13 +3,13 @@ use std::path::PathBuf; use super::{WindowDescriptor, WindowId}; use bevy_math::{IVec2, Vec2}; -/// A window event that is sent whenever a windows logical size has changed +/// A window event that is sent whenever a window's logical size has changed. #[derive(Debug, Clone)] pub struct WindowResized { pub id: WindowId, - /// The new logical width of the window + /// The new logical width of the window. pub width: f32, - /// The new logical height of the window + /// The new logical height of the window. pub height: f32, } From 027d94c977526752952f85eebc55080a99f7f7aa Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Thu, 16 Jun 2022 09:10:40 -0400 Subject: [PATCH 19/22] Improve formatting for `lib.rs` documentation --- crates/bevy_window/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/bevy_window/src/lib.rs b/crates/bevy_window/src/lib.rs index 1b03ac140b025..07c759bbe1905 100644 --- a/crates/bevy_window/src/lib.rs +++ b/crates/bevy_window/src/lib.rs @@ -32,6 +32,7 @@ pub struct WindowPlugin { /// due to [`exit_on_all_closed`]. pub add_primary_window: bool, /// Whether to exit the app when there are no open windows. + /// /// If disabling this, ensure that you send the [`bevy_app::AppExit`] /// event when the app should exit. If this does not occur, you will /// create 'headless' processes (processes without windows), which may @@ -40,7 +41,7 @@ pub struct WindowPlugin { /// If true, this plugin will add [`exit_on_all_closed`] to [`CoreStage::Update`]. pub exit_on_all_closed: bool, /// Whether to close windows when they are requested to be closed (i.e. - /// when the close button is pressed) + /// when the close button is pressed). /// /// If true, this plugin will add [`close_when_requested`] to [`CoreStage::Update`]. /// If this system (or a replacement) is not running, the close button will have no effect. From e01ca5c32e128e04c1fa88c5b745c0e3d9cdd871 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Thu, 16 Jun 2022 09:12:35 -0400 Subject: [PATCH 20/22] Improve formatting of `windows.rs` documentation --- crates/bevy_window/src/windows.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/crates/bevy_window/src/windows.rs b/crates/bevy_window/src/windows.rs index df20688018133..608009b7b2c52 100644 --- a/crates/bevy_window/src/windows.rs +++ b/crates/bevy_window/src/windows.rs @@ -13,7 +13,7 @@ impl Windows { self.windows.insert(window.id(), window); } - /// Get a reference to the [`Window`] of `id` + /// Get a reference to the [`Window`] of `id`. pub fn get(&self, id: WindowId) -> Option<&Window> { self.windows.get(&id) } @@ -32,7 +32,7 @@ impl Windows { /// /// # Panics /// - /// Panics if the primary window does not exist in [`Windows`] + /// Panics if the primary window does not exist in [`Windows`]. pub fn primary(&self) -> &Window { self.get_primary().expect("Primary window does not exist") } @@ -46,7 +46,7 @@ impl Windows { /// /// # Panics /// - /// Panics if the primary window does not exist in [`Windows`] + /// Panics if the primary window does not exist in [`Windows`]. pub fn primary_mut(&mut self) -> &mut Window { self.get_primary_mut() .expect("Primary window does not exist") @@ -61,12 +61,12 @@ impl Windows { } } - /// An iterator over all registered [`Window`]s + /// An iterator over all registered [`Window`]s. pub fn iter(&self) -> impl Iterator { self.windows.values() } - /// A mutable iterator over all registered [`Window`]s + /// A mutable iterator over all registered [`Window`]s. pub fn iter_mut(&mut self) -> impl Iterator { self.windows.values_mut() } From 6dce308b74e983c89e3572f73d3813eb54aaac7f Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Thu, 16 Jun 2022 09:13:57 -0400 Subject: [PATCH 21/22] Improve formatting for `bevy_window` docs --- crates/bevy_window/src/cursor.rs | 2 +- crates/bevy_window/src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_window/src/cursor.rs b/crates/bevy_window/src/cursor.rs index 1e2ee7e113dd0..c3926d1b04726 100644 --- a/crates/bevy_window/src/cursor.rs +++ b/crates/bevy_window/src/cursor.rs @@ -22,7 +22,7 @@ pub enum CursorIcon { /// Help indicator (often rendered as a "?") Help, /// Progress indicator. Shows that processing is being done. - /// + /// /// But in contrast with "Wait" the user may still interact with the program. /// Often rendered as a spinning beach ball, or an arrow with a watch or hourglass. Progress, diff --git a/crates/bevy_window/src/lib.rs b/crates/bevy_window/src/lib.rs index 07c759bbe1905..ca57cde6fac6b 100644 --- a/crates/bevy_window/src/lib.rs +++ b/crates/bevy_window/src/lib.rs @@ -32,7 +32,7 @@ pub struct WindowPlugin { /// due to [`exit_on_all_closed`]. pub add_primary_window: bool, /// Whether to exit the app when there are no open windows. - /// + /// /// If disabling this, ensure that you send the [`bevy_app::AppExit`] /// event when the app should exit. If this does not occur, you will /// create 'headless' processes (processes without windows), which may From a44127799d5f5d4628a70ef0fe58a543c707b518 Mon Sep 17 00:00:00 2001 From: Arnav Choubey <56453634+x-52@users.noreply.github.com> Date: Thu, 16 Jun 2022 09:19:54 -0400 Subject: [PATCH 22/22] Add backticks to `window.rs` docs --- crates/bevy_window/src/window.rs | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/crates/bevy_window/src/window.rs b/crates/bevy_window/src/window.rs index c3f94a829e8e4..6557d414c590d 100644 --- a/crates/bevy_window/src/window.rs +++ b/crates/bevy_window/src/window.rs @@ -540,7 +540,7 @@ impl Window { /// /// ## Platform-specific /// - /// **iOS**, **Android**, and the **Web** do not have decorations. + /// **`iOS`**, **`Android`**, and the **`Web`** do not have decorations. #[inline] pub fn decorations(&self) -> bool { self.decorations @@ -551,7 +551,7 @@ impl Window { /// /// ## Platform-specific /// - /// **iOS**, **Android**, and the **Web** do not have decorations. + /// **`iOS`**, **`Android`**, and the **`Web`** do not have decorations. pub fn set_decorations(&mut self, decorations: bool) { self.decorations = decorations; self.command_queue @@ -561,8 +561,8 @@ impl Window { /// /// ## Platform-specific /// - /// - **macOS** doesn't support cursor lock, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information. - /// - **iOS/Android** don't have cursors. + /// - **`macOS`** doesn't support cursor lock, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information. + /// - **`iOS/Android`** don't have cursors. #[inline] pub fn cursor_locked(&self) -> bool { self.cursor_locked @@ -573,8 +573,8 @@ impl Window { /// /// ## Platform-specific /// - /// - **macOS** doesn't support cursor lock, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information. - /// - **iOS/Android** don't have cursors. + /// - **`macOS`** doesn't support cursor lock, but most windowing plugins can emulate it. See [issue #4875](https://github.com/bevyengine/bevy/issues/4875#issuecomment-1153977546) for more information. + /// - **`iOS/Android`** don't have cursors. pub fn set_cursor_lock_mode(&mut self, lock_mode: bool) { self.cursor_locked = lock_mode; self.command_queue @@ -584,9 +584,9 @@ impl Window { /// /// ## Platform-specific /// - /// - **Windows**, **X11**, and **Wayland**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_lock_mode`](Window::set_cursor_lock_mode). - /// - **macOS**: The cursor is hidden only when the window is focused. - /// - **iOS** and **Android** do not have cursors + /// - **`Windows`**, **`X11`**, and **`Wayland`**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_lock_mode`](Window::set_cursor_lock_mode). + /// - **`macOS`**: The cursor is hidden only when the window is focused. + /// - **`iOS`** and **`Android`** do not have cursors #[inline] pub fn cursor_visible(&self) -> bool { self.cursor_visible @@ -595,9 +595,9 @@ impl Window { /// /// ## Platform-specific /// - /// - **Windows**, **X11**, and **Wayland**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_lock_mode`](Window::set_cursor_lock_mode). - /// - **macOS**: The cursor is hidden only when the window is focused. - /// - **iOS** and **Android** do not have cursors + /// - **`Windows`**, **`X11`**, and **`Wayland`**: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, use [`set_cursor_lock_mode`](Window::set_cursor_lock_mode). + /// - **`macOS`**: The cursor is hidden only when the window is focused. + /// - **`iOS`** and **`Android`** do not have cursors pub fn set_cursor_visibility(&mut self, visibile_mode: bool) { self.cursor_visible = visibile_mode; self.command_queue.push(WindowCommand::SetCursorVisibility {