pub struct Window { /* private fields */ }
Expand description
An operating system window that can present content and receive user input.
To create a window, use a EventWriter<CreateWindow>
.
Window Sizes
There are three sizes associated with a window. The physical size which is the height and width in physical pixels on the monitor. The logical size which is the physical size scaled by an operating system provided factor to account for monitors with differing pixel densities or user preference. And the requested size, measured in logical pixels, which is the value submitted to the API when creating the window, or requesting that it be resized.
The actual size, in logical pixels, of the window may not match the 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
fn access_window_system(mut windows: ResMut<Windows>){
for mut window in windows.iter_mut() {
window.set_title(String::from("Yay, I'm a window!"));
}
}
To test code that uses Window
s, one can test it with varying Window
parameters by
creating WindowResizeConstraints
or WindowDescriptor
structures.
values by setting
let resize_constraints = WindowResizeConstraints {
min_width: 400.0,
min_height: 300.0,
max_width: 1280.0,
max_height: 1024.0,
};
let window_descriptor = WindowDescriptor {
width: 800.0,
height: 600.0,
resizable: true,
resize_constraints,
..default()
};
let mut window = Window::new(
WindowId::new(),
&window_descriptor,
100, // physical_width
100, // physical_height
1.0, // scale_factor
None, None);
let area = compute_window_area(&window);
assert_eq!(area, 100.0 * 100.0);
grow_window_to_text_size(&mut window, "very long text that does not wrap");
assert_eq!(window.physical_width(), window.requested_width() as u32);
grow_window_to_text_size(&mut window, "very long text that does wrap, creating a maximum width window");
assert_eq!(window.physical_width(), window.requested_width() as u32);
set_new_title(&mut window, "new title".to_string());
let mut found_command = false;
for command in window.drain_commands() {
if command == (WindowCommand::SetTitle{ title: "new title".to_string() }) {
found_command = true;
break;
}
}
assert_eq!(found_command, true);
}
Implementations§
§impl Window
impl Window
pub fn new(
id: WindowId,
window_descriptor: &WindowDescriptor,
physical_width: u32,
physical_height: u32,
scale_factor: f64,
position: Option<IVec2>,
raw_handle: Option<RawHandleWrapper>
) -> Window
pub fn new(
id: WindowId,
window_descriptor: &WindowDescriptor,
physical_width: u32,
physical_height: u32,
scale_factor: f64,
position: Option<IVec2>,
raw_handle: Option<RawHandleWrapper>
) -> Window
Creates a new Window
.
pub fn requested_width(&self) -> f32
pub fn requested_width(&self) -> f32
The requested window client area width in logical pixels from window
creation or the last call to set_resolution
.
This may differ from the actual width depending on OS size limits and the scaling factor for high DPI monitors.
pub fn requested_height(&self) -> f32
pub fn requested_height(&self) -> f32
The requested window client area height in logical pixels from window
creation or the last call to set_resolution
.
This may differ from the actual width depending on OS size limits and the scaling factor for high DPI monitors.
pub fn physical_width(&self) -> u32
pub fn physical_width(&self) -> u32
The window’s client area width in physical pixels.
pub fn physical_height(&self) -> u32
pub fn physical_height(&self) -> u32
The window’s client area height in physical pixels.
pub fn resize_constraints(&self) -> WindowResizeConstraints
pub fn resize_constraints(&self) -> WindowResizeConstraints
The window’s client resize constraint in logical pixels.
pub fn set_maximized(&mut self, maximized: bool)
pub fn set_maximized(&mut self, maximized: bool)
Set whether or not the window is maximized.
pub fn set_minimized(&mut self, minimized: bool)
pub fn set_minimized(&mut self, minimized: bool)
Sets the window to minimized or back.
Platform-specific
- iOS / Android / Web: Unsupported.
- Wayland: Un-minimize is unsupported.
pub fn set_position(&mut self, monitor: MonitorSelection, position: IVec2)
pub fn set_position(&mut self, monitor: MonitorSelection, position: IVec2)
Sets the position
of the window on the selected monitor
in physical pixels.
This automatically un-maximizes the window if it’s maximized.
Platform-specific
- iOS: Can only be called on the main thread. Sets the top left coordinates of the window in the screen space coordinate system.
- Web: Sets the top-left coordinates relative to the viewport.
- Android / Wayland: Unsupported.
pub fn center_window(&mut self, monitor_selection: MonitorSelection)
pub fn center_window(&mut self, monitor_selection: MonitorSelection)
Modifies the position of the window to be in the center of the current monitor
Platform-specific
- iOS: Can only be called on the main thread.
- Web / Android / Wayland: Unsupported.
pub fn set_resize_constraints(
&mut self,
resize_constraints: WindowResizeConstraints
)
pub fn set_resize_constraints(
&mut self,
resize_constraints: WindowResizeConstraints
)
Modifies the minimum and maximum window bounds for resizing in logical pixels.
pub fn set_resolution(&mut self, width: f32, height: f32)
pub fn set_resolution(&mut self, width: f32, height: f32)
Request the OS to resize the window such the client area matches the specified width and height.
pub fn set_scale_factor_override(&mut self, scale_factor: Option<f64>)
pub fn set_scale_factor_override(&mut self, scale_factor: Option<f64>)
Override the os-reported scaling factor.
pub fn update_scale_factor_from_backend(&mut self, scale_factor: f64)
pub fn update_actual_size_from_backend(
&mut self,
physical_width: u32,
physical_height: u32
)
pub fn update_actual_position_from_backend(&mut self, position: IVec2)
pub fn scale_factor(&self) -> f64
pub fn scale_factor(&self) -> f64
The ratio of physical pixels to logical pixels
physical_pixels = logical_pixels * scale_factor
pub fn backend_scale_factor(&self) -> f64
pub fn backend_scale_factor(&self) -> f64
The window scale factor as reported by the window backend.
This value is unaffected by scale_factor_override
.
pub fn scale_factor_override(&self) -> Option<f64>
pub fn scale_factor_override(&self) -> Option<f64>
The scale factor set with set_scale_factor_override
.
This value may be different from the scale factor reported by the window backend.
pub fn present_mode(&self) -> PresentMode
pub fn present_mode(&self) -> PresentMode
Get the window’s PresentMode
.
pub fn alpha_mode(&self) -> CompositeAlphaMode
pub fn alpha_mode(&self) -> CompositeAlphaMode
Get the window’s CompositeAlphaMode
.
pub fn set_present_mode(&mut self, present_mode: PresentMode)
pub fn set_present_mode(&mut self, present_mode: PresentMode)
Set the window’s PresentMode
.
pub fn set_resizable(&mut self, resizable: bool)
pub fn set_resizable(&mut self, resizable: bool)
Set whether or not the window is resizable.
pub fn decorations(&self) -> bool
pub fn decorations(&self) -> bool
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.
pub fn set_decorations(&mut self, decorations: bool)
pub fn set_decorations(&mut self, decorations: bool)
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 cursor_grab_mode(&self) -> CursorGrabMode
pub fn cursor_grab_mode(&self) -> CursorGrabMode
Get whether or how the cursor is grabbed.
Platform-specific
Windows
doesn’t supportCursorGrabMode::Locked
macOS
doesn’t supportCursorGrabMode::Confined
iOS/Android
don’t have cursors.
Since Windows
and macOS
have different CursorGrabMode
support, it’s possible the value returned here is not the same as the one actually sent to winit.
pub fn set_cursor_grab_mode(&mut self, grab_mode: CursorGrabMode)
pub fn set_cursor_grab_mode(&mut self, grab_mode: CursorGrabMode)
Set whether and how the cursor is grabbed.
This doesn’t hide the cursor. For that, use set_cursor_visibility
Platform-specific
Windows
doesn’t supportCursorGrabMode::Locked
macOS
doesn’t supportCursorGrabMode::Confined
iOS/Android
don’t have cursors.
Since Windows
and macOS
have different CursorGrabMode
support, we first try to set the grab mode that was asked for. If it doesn’t work then use the alternate grab mode.
pub fn cursor_visible(&self) -> bool
pub fn cursor_visible(&self) -> bool
Get whether or not the cursor is visible.
Platform-specific
Windows
,X11
, andWayland
: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, useset_cursor_grab_mode
.macOS
: The cursor is hidden only when the window is focused.iOS
andAndroid
do not have cursors
pub fn set_cursor_visibility(&mut self, visible_mode: bool)
pub fn set_cursor_visibility(&mut self, visible_mode: bool)
Set whether or not the cursor is visible.
Platform-specific
Windows
,X11
, andWayland
: The cursor is hidden only when inside the window. To stop the cursor from leaving the window, useset_cursor_grab_mode
.macOS
: The cursor is hidden only when the window is focused.iOS
andAndroid
do not have cursors
pub fn cursor_icon(&self) -> CursorIcon
pub fn cursor_icon(&self) -> CursorIcon
Get the current CursorIcon
pub fn set_cursor_icon(&mut self, icon: CursorIcon)
pub fn set_cursor_icon(&mut self, icon: CursorIcon)
Set the CursorIcon
pub fn physical_cursor_position(&self) -> Option<DVec2>
pub fn physical_cursor_position(&self) -> Option<DVec2>
The current mouse position, in physical pixels.
pub fn cursor_position(&self) -> Option<Vec2>
pub fn cursor_position(&self) -> Option<Vec2>
The current mouse position, in logical pixels, taking into account the screen scale factor.
pub fn set_cursor_position(&mut self, position: Vec2)
pub fn set_cursor_position(&mut self, position: Vec2)
Set the cursor’s position
pub fn update_focused_status_from_backend(&mut self, focused: bool)
pub fn update_cursor_physical_position_from_backend(
&mut self,
cursor_position: Option<DVec2>
)
pub fn mode(&self) -> WindowMode
pub fn mode(&self) -> WindowMode
Get the window’s WindowMode
pub fn set_mode(&mut self, mode: WindowMode)
pub fn set_mode(&mut self, mode: WindowMode)
Set the window’s WindowMode
pub fn close(&mut self)
pub fn close(&mut self)
Close the operating system window corresponding to this Window
.
This will also lead to this Window
being removed from the
Windows
resource.
If the default WindowPlugin
is used, when no windows are
open, the app will exit.
To disable this behaviour, set exit_on_all_closed
on the WindowPlugin
to false
pub fn drain_commands(&mut self) -> impl Iterator<Item = WindowCommand>
pub fn is_focused(&self) -> bool
pub fn is_focused(&self) -> bool
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
pub fn raw_handle(&self) -> Option<RawHandleWrapper>
pub fn raw_handle(&self) -> Option<RawHandleWrapper>
Get the RawHandleWrapper
corresponding to this window if set.
During normal use, this can be safely unwrapped; the value should only be None
when synthetically constructed for tests.
pub fn canvas(&self) -> Option<&str>
pub fn canvas(&self) -> Option<&str>
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.
This value has no effect on non-web platforms.
pub fn fit_canvas_to_parent(&self) -> bool
pub fn fit_canvas_to_parent(&self) -> bool
Whether or not to fit the canvas element’s size to its parent element’s size.
Warning: this will not behave as expected for parents that set their size according to the size of their children. This creates a “feedback loop” that will result in the canvas growing on each resize. When using this feature, ensure the parent’s size is not affected by its children.
This value has no effect on non-web platforms.
Trait Implementations§
Auto Trait Implementations§
impl RefUnwindSafe for Window
impl Send for Window
impl Sync for Window
impl Unpin for Window
impl UnwindSafe for Window
Blanket Implementations§
§impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
§fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
T
ShaderType
for self
. When used in AsBindGroup
derives, it is safe to assume that all images in self
exist. Read more§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read more§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more