pub struct Window { /* private fields */ }
Expand description
Represents a window.
Example
use winit::{
event::{Event, WindowEvent},
event_loop::EventLoop,
window::Window,
};
let mut event_loop = EventLoop::new();
let window = Window::new(&event_loop).unwrap();
event_loop.run(move |event, _, control_flow| {
control_flow.set_wait();
match event {
Event::WindowEvent {
event: WindowEvent::CloseRequested,
..
} => control_flow.set_exit(),
_ => (),
}
});
Implementations§
source§impl Window
impl Window
Base Window functions.
sourcepub fn new<T: 'static>(
event_loop: &EventLoopWindowTarget<T>
) -> Result<Window, OsError>
pub fn new<T: 'static>( event_loop: &EventLoopWindowTarget<T> ) -> Result<Window, OsError>
Creates a new Window for platforms where this is appropriate.
This function is equivalent to WindowBuilder::new().build(event_loop)
.
Error should be very rare and only occur in case of permission denied, incompatible system, out of memory, etc.
Platform-specific
- Web: The window is created but not inserted into the web page automatically. Please see the web platform module for more information.
sourcepub fn scale_factor(&self) -> f64
pub fn scale_factor(&self) -> f64
Returns the scale factor that can be used to map logical pixels to physical pixels, and vice versa.
See the dpi
module for more information.
Note that this value can change depending on user action (for example if the window is
moved to another screen); as such, tracking WindowEvent::ScaleFactorChanged
events is
the most robust way to track the DPI you need to use to draw.
Platform-specific
- X11: This respects Xft.dpi, and can be overridden using the
WINIT_X11_SCALE_FACTOR
environment variable. - Wayland: Uses the wp-fractional-scale protocol if available. Falls back to integer-scale factors otherwise.
- Android: Always returns 1.0.
- iOS: Can only be called on the main thread. Returns the underlying
UIView
’scontentScaleFactor
.
sourcepub fn request_redraw(&self)
pub fn request_redraw(&self)
Emits a Event::RedrawRequested
event in the associated event loop after all OS
events have been processed by the event loop.
This is the strongly encouraged method of redrawing windows, as it can integrate with OS-requested redraws (e.g. when a window gets resized).
This function can cause RedrawRequested
events to be emitted after Event::MainEventsCleared
but before Event::NewEvents
if called in the following circumstances:
- While processing
MainEventsCleared
. - While processing a
RedrawRequested
event that was sent duringMainEventsCleared
or any directly subsequentRedrawRequested
event.
Platform-specific
- iOS: Can only be called on the main thread.
- Android: Subsequent calls after
MainEventsCleared
are not handled.
source§impl Window
impl Window
Position and size functions.
sourcepub fn inner_position(&self) -> Result<PhysicalPosition<i32>, NotSupportedError>
pub fn inner_position(&self) -> Result<PhysicalPosition<i32>, NotSupportedError>
Returns the position of the top-left hand corner of the window’s client area relative to the top-left hand corner of the desktop.
The same conditions that apply to Window::outer_position
apply to this method.
Platform-specific
- iOS: Can only be called on the main thread. Returns the top left coordinates of the window’s safe area in the screen space coordinate system.
- Web: Returns the top-left coordinates relative to the viewport. Note: this returns the
same value as
Window::outer_position
. - Android / Wayland: Always returns
NotSupportedError
.
sourcepub fn outer_position(&self) -> Result<PhysicalPosition<i32>, NotSupportedError>
pub fn outer_position(&self) -> Result<PhysicalPosition<i32>, NotSupportedError>
Returns the position of the top-left hand corner of the window relative to the top-left hand corner of the desktop.
Note that the top-left hand corner of the desktop is not necessarily the same as the screen. If the user uses a desktop with multiple monitors, the top-left hand corner of the desktop is the top-left hand corner of the monitor at the top-left of the desktop.
The coordinates can be negative if the top-left hand corner of the window is outside of the visible screen region.
Platform-specific
- iOS: Can only be called on the main thread. Returns the top left coordinates of the window in the screen space coordinate system.
- Web: Returns the top-left coordinates relative to the viewport.
- Android / Wayland: Always returns
NotSupportedError
.
sourcepub fn set_outer_position<P: Into<Position>>(&self, position: P)
pub fn set_outer_position<P: Into<Position>>(&self, position: P)
Modifies the position of the window.
See Window::outer_position
for more information about the coordinates.
This automatically un-maximizes the window if it’s maximized.
// Specify the position in logical dimensions like this:
window.set_outer_position(LogicalPosition::new(400.0, 200.0));
// Or specify the position in physical dimensions like this:
window.set_outer_position(PhysicalPosition::new(400, 200));
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.
sourcepub fn inner_size(&self) -> PhysicalSize<u32>
pub fn inner_size(&self) -> PhysicalSize<u32>
Returns the physical size of the window’s client area.
The client area is the content of the window, excluding the title bar and borders.
Platform-specific
- iOS: Can only be called on the main thread. Returns the
PhysicalSize
of the window’s safe area in screen space coordinates. - Web: Returns the size of the canvas element.
sourcepub fn set_inner_size<S: Into<Size>>(&self, size: S)
pub fn set_inner_size<S: Into<Size>>(&self, size: S)
Modifies the inner size of the window.
See Window::inner_size
for more information about the values.
This automatically un-maximizes the window if it’s maximized.
// Specify the size in logical dimensions like this:
window.set_inner_size(LogicalSize::new(400.0, 200.0));
// Or specify the size in physical dimensions like this:
window.set_inner_size(PhysicalSize::new(400, 200));
Platform-specific
- iOS / Android: Unsupported.
- Web: Sets the size of the canvas element.
sourcepub fn outer_size(&self) -> PhysicalSize<u32>
pub fn outer_size(&self) -> PhysicalSize<u32>
Returns the physical size of the entire window.
These dimensions include the title bar and borders. If you don’t want that (and you usually don’t),
use Window::inner_size
instead.
Platform-specific
- iOS: Can only be called on the main thread. Returns the
PhysicalSize
of the window in screen space coordinates. - Web: Returns the size of the canvas element. Note: this returns the same value as
Window::inner_size
.
sourcepub fn set_min_inner_size<S: Into<Size>>(&self, min_size: Option<S>)
pub fn set_min_inner_size<S: Into<Size>>(&self, min_size: Option<S>)
Sets a minimum dimension size for the window.
// Specify the size in logical dimensions like this:
window.set_min_inner_size(Some(LogicalSize::new(400.0, 200.0)));
// Or specify the size in physical dimensions like this:
window.set_min_inner_size(Some(PhysicalSize::new(400, 200)));
Platform-specific
- iOS / Android / Web / Orbital: Unsupported.
sourcepub fn set_max_inner_size<S: Into<Size>>(&self, max_size: Option<S>)
pub fn set_max_inner_size<S: Into<Size>>(&self, max_size: Option<S>)
Sets a maximum dimension size for the window.
// Specify the size in logical dimensions like this:
window.set_max_inner_size(Some(LogicalSize::new(400.0, 200.0)));
// Or specify the size in physical dimensions like this:
window.set_max_inner_size(Some(PhysicalSize::new(400, 200)));
Platform-specific
- iOS / Android / Web / Orbital: Unsupported.
sourcepub fn resize_increments(&self) -> Option<PhysicalSize<u32>>
pub fn resize_increments(&self) -> Option<PhysicalSize<u32>>
Returns window resize increments if any were set.
Platform-specific
- iOS / Android / Web / Wayland / Windows / Orbital: Always returns
None
.
sourcepub fn set_resize_increments<S: Into<Size>>(&self, increments: Option<S>)
pub fn set_resize_increments<S: Into<Size>>(&self, increments: Option<S>)
Sets window resize increments.
This is a niche constraint hint usually employed by terminal emulators and other apps that need “blocky” resizes.
Platform-specific
- macOS: Increments are converted to logical size and then macOS rounds them to whole numbers.
- Wayland / Windows: Not implemented.
- iOS / Android / Web / Orbital: Unsupported.
source§impl Window
impl Window
Misc. attribute functions.
sourcepub fn set_transparent(&self, transparent: bool)
pub fn set_transparent(&self, transparent: bool)
Change the window transparency state.
This is just a hint that may not change anything about the window transparency, however doing a missmatch between the content of your window and this hint may result in visual artifacts.
The default value follows the WindowBuilder::with_transparent
.
Platform-specific
- Windows / X11 / Web / iOS / Android / Orbital: Unsupported.
sourcepub fn set_visible(&self, visible: bool)
pub fn set_visible(&self, visible: bool)
Modifies the window’s visibility.
If false
, this will hide the window. If true
, this will show the window.
Platform-specific
- Android / Wayland / Web: Unsupported.
- iOS: Can only be called on the main thread.
sourcepub fn is_visible(&self) -> Option<bool>
pub fn is_visible(&self) -> Option<bool>
Gets the window’s current visibility state.
None
means it couldn’t be determined, so it is not recommended to use this to drive your rendering backend.
Platform-specific
- X11: Not implemented.
- Wayland / iOS / Android / Web: Unsupported.
sourcepub fn set_resizable(&self, resizable: bool)
pub fn set_resizable(&self, resizable: bool)
Sets whether the window is resizable or not.
Note that making the window unresizable doesn’t exempt you from handling WindowEvent::Resized
, as that
event can still be triggered by DPI scaling, entering fullscreen mode, etc. Also, the
window could still be resized by calling Window::set_inner_size
.
Platform-specific
This only has an effect on desktop platforms.
- X11: Due to a bug in XFCE, this has no effect on Xfwm.
- iOS / Android / Web: Unsupported.
sourcepub fn is_resizable(&self) -> bool
pub fn is_resizable(&self) -> bool
Gets the window’s current resizable state.
Platform-specific
- X11: Not implemented.
- iOS / Android / Web: Unsupported.
Sets the enabled window buttons.
Platform-specific
- Wayland / X11 / Orbital: Not implemented.
- Web / iOS / Android: Unsupported.
Gets the enabled window buttons.
Platform-specific
- Wayland / X11 / Orbital: Not implemented. Always returns
WindowButtons::all
. - Web / iOS / Android: Unsupported. Always returns
WindowButtons::all
.
sourcepub fn set_minimized(&self, minimized: bool)
pub fn set_minimized(&self, minimized: bool)
Sets the window to minimized or back
Platform-specific
- iOS / Android / Web / Orbital: Unsupported.
- Wayland: Un-minimize is unsupported.
sourcepub fn is_minimized(&self) -> Option<bool>
pub fn is_minimized(&self) -> Option<bool>
Gets the window’s current minimized state.
None
will be returned, if the minimized state couldn’t be determined.
Note
- You shouldn’t stop rendering for minimized windows, however you could lower the fps.
Platform-specific
- Wayland: always
None
. - iOS / Android / Web / Orbital: Unsupported.
sourcepub fn set_maximized(&self, maximized: bool)
pub fn set_maximized(&self, maximized: bool)
sourcepub fn is_maximized(&self) -> bool
pub fn is_maximized(&self) -> bool
Gets the window’s current maximized state.
Platform-specific
- iOS / Android / Web / Orbital: Unsupported.
sourcepub fn set_fullscreen(&self, fullscreen: Option<Fullscreen>)
pub fn set_fullscreen(&self, fullscreen: Option<Fullscreen>)
Sets the window to fullscreen or back.
Platform-specific
-
macOS:
Fullscreen::Exclusive
provides true exclusive mode with a video mode change. Caveat! macOS doesn’t provide task switching (or spaces!) while in exclusive fullscreen mode. This mode should be used when a video mode change is desired, but for a better user experience, borderless fullscreen might be preferred.Fullscreen::Borderless
provides a borderless fullscreen window on a separate space. This is the idiomatic way for fullscreen games to work on macOS. SeeWindowExtMacOs::set_simple_fullscreen
if separate spaces are not preferred.The dock and the menu bar are disabled in exclusive fullscreen mode.
-
iOS: Can only be called on the main thread.
-
Wayland: Does not support exclusive fullscreen mode and will no-op a request.
-
Windows: Screen saver is disabled in fullscreen mode.
-
Android / Orbital: Unsupported.
sourcepub fn fullscreen(&self) -> Option<Fullscreen>
pub fn fullscreen(&self) -> Option<Fullscreen>
Gets the window’s current fullscreen state.
Platform-specific
- iOS: Can only be called on the main thread.
- Android / Orbital: Will always return
None
. - Wayland: Can return
Borderless(None)
when there are no monitors.
sourcepub fn set_decorations(&self, decorations: bool)
pub fn set_decorations(&self, decorations: bool)
Turn window decorations on or off.
Enable/disable window decorations provided by the server or Winit. By default this is enabled. Note that fullscreen windows and windows on mobile and web platforms naturally do not have decorations.
Platform-specific
- iOS / Android / Web: No effect.
sourcepub fn is_decorated(&self) -> bool
pub fn is_decorated(&self) -> bool
Gets the window’s current decorations state.
Returns true
when windows are decorated (server-side or by Winit).
Also returns true
when no decorations are required (mobile, web).
Platform-specific
- iOS / Android / Web: Always returns
true
.
sourcepub fn set_window_level(&self, level: WindowLevel)
pub fn set_window_level(&self, level: WindowLevel)
Change the window level.
This is just a hint to the OS, and the system could ignore it.
See WindowLevel
for details.
sourcepub fn set_window_icon(&self, window_icon: Option<Icon>)
pub fn set_window_icon(&self, window_icon: Option<Icon>)
Sets the window icon.
On Windows and X11, this is typically the small icon in the top-left corner of the titlebar.
Platform-specific
-
iOS / Android / Web / Wayland / macOS / Orbital: Unsupported.
-
Windows: Sets
ICON_SMALL
. The base size for a window icon is 16x16, but it’s recommended to account for screen scaling and pick a multiple of that, i.e. 32x32. -
X11: Has no universal guidelines for icon sizes, so you’re at the whims of the WM. That said, it’s usually in the same ballpark as on Windows.
sourcepub fn set_ime_position<P: Into<Position>>(&self, position: P)
pub fn set_ime_position<P: Into<Position>>(&self, position: P)
Sets location of IME candidate box in client area coordinates relative to the top left.
This is the window / popup / overlay that allows you to select the desired characters. The look of this box may differ between input devices, even on the same platform.
(Apple’s official term is “candidate window”, see their chinese and japanese guides).
Example
// Specify the position in logical dimensions like this:
window.set_ime_position(LogicalPosition::new(400.0, 200.0));
// Or specify the position in physical dimensions like this:
window.set_ime_position(PhysicalPosition::new(400, 200));
Platform-specific
- iOS / Android / Web / Orbital: Unsupported.
sourcepub fn set_ime_allowed(&self, allowed: bool)
pub fn set_ime_allowed(&self, allowed: bool)
Sets whether the window should get IME events
When IME is allowed, the window will receive Ime
events, and during the
preedit phase the window will NOT get KeyboardInput
or
ReceivedCharacter
events. The window should allow IME while it is
expecting text input.
When IME is not allowed, the window won’t receive Ime
events, and will
receive KeyboardInput
events for every keypress instead. Without
allowing IME, the window will also get ReceivedCharacter
events for
certain keyboard input. Not allowing IME is useful for games for example.
IME is not allowed by default.
Platform-specific
- macOS: IME must be enabled to receive text-input where dead-key sequences are combined.
- iOS / Android / Web / Orbital: Unsupported.
sourcepub fn set_ime_purpose(&self, purpose: ImePurpose)
pub fn set_ime_purpose(&self, purpose: ImePurpose)
Sets the IME purpose for the window using ImePurpose
.
Platform-specific
- iOS / Android / Web / Windows / X11 / macOS / Orbital: Unsupported.
sourcepub fn focus_window(&self)
pub fn focus_window(&self)
Brings the window to the front and sets input focus. Has no effect if the window is already in focus, minimized, or not visible.
This method steals input focus from other applications. Do not use this method unless you are certain that’s what the user wants. Focus stealing can cause an extremely disruptive user experience.
Platform-specific
- iOS / Android / Web / Wayland / Orbital: Unsupported.
sourcepub fn has_focus(&self) -> bool
pub fn has_focus(&self) -> bool
Gets whether the window has keyboard focus.
This queries the same state information as WindowEvent::Focused
.
sourcepub fn request_user_attention(&self, request_type: Option<UserAttentionType>)
pub fn request_user_attention(&self, request_type: Option<UserAttentionType>)
Requests user attention to the window, this has no effect if the application
is already focused. How requesting for user attention manifests is platform dependent,
see UserAttentionType
for details.
Providing None
will unset the request for user attention. Unsetting the request for
user attention might not be done automatically by the WM when the window receives input.
Platform-specific
- iOS / Android / Web / Orbital: Unsupported.
- macOS:
None
has no effect. - X11: Requests for user attention must be manually cleared.
- Wayland: Requires
xdg_activation_v1
protocol,None
has no effect.
sourcepub fn set_theme(&self, theme: Option<Theme>)
pub fn set_theme(&self, theme: Option<Theme>)
Sets the current window theme. Use None
to fallback to system default.
Platform-specific
- macOS: This is an app-wide setting.
- Wayland: You can also use
WINIT_WAYLAND_CSD_THEME
env variable to set the theme. Possible values for env variable are: “dark” and light“. When unspecified, a theme is automatically selected. -x11: Sets_GTK_THEME_VARIANT
hint todark
orlight
and ifNone
is used, it will default toTheme::Dark
. - iOS / Android / Web / x11 / Orbital: Unsupported.
sourcepub fn theme(&self) -> Option<Theme>
pub fn theme(&self) -> Option<Theme>
Returns the current window theme.
Platform-specific
- macOS: This is an app-wide setting.
- iOS / Android / Wayland / x11 / Orbital: Unsupported.
sourcepub fn set_content_protected(&self, _protected: bool)
pub fn set_content_protected(&self, _protected: bool)
Prevents the window contents from being captured by other apps.
Platform-specific
- macOS: if
false
,NSWindowSharingNone
is used but doesn’t completely prevent all apps from reading the window content, for instance, QuickTime. - iOS / Android / x11 / Wayland / Web / Orbital: Unsupported.
sourcepub fn title(&self) -> String
pub fn title(&self) -> String
Gets the current title of the window.
Platform-specific
- iOS / Android / x11 / Wayland / Web: Unsupported. Always returns an empty string.
source§impl Window
impl Window
Cursor functions.
sourcepub fn set_cursor_icon(&self, cursor: CursorIcon)
pub fn set_cursor_icon(&self, cursor: CursorIcon)
sourcepub fn set_cursor_position<P: Into<Position>>(
&self,
position: P
) -> Result<(), ExternalError>
pub fn set_cursor_position<P: Into<Position>>( &self, position: P ) -> Result<(), ExternalError>
Changes the position of the cursor in window coordinates.
// Specify the position in logical dimensions like this:
window.set_cursor_position(LogicalPosition::new(400.0, 200.0));
// Or specify the position in physical dimensions like this:
window.set_cursor_position(PhysicalPosition::new(400, 200));
Platform-specific
- iOS / Android / Web / Wayland / Orbital: Always returns an
ExternalError::NotSupported
.
sourcepub fn set_cursor_grab(&self, mode: CursorGrabMode) -> Result<(), ExternalError>
pub fn set_cursor_grab(&self, mode: CursorGrabMode) -> Result<(), ExternalError>
sourcepub fn set_cursor_visible(&self, visible: bool)
pub fn set_cursor_visible(&self, visible: bool)
Modifies the cursor’s visibility.
If false
, this will hide the cursor. If true
, this will show the cursor.
Platform-specific
- Windows: The cursor is only hidden within the confines of the window.
- X11: The cursor is only hidden within the confines of the window.
- Wayland: The cursor is only hidden within the confines of the window.
- macOS: The cursor is hidden as long as the window has input focus, even if the cursor is outside of the window.
- iOS / Android / Orbital: Unsupported.
sourcepub fn drag_window(&self) -> Result<(), ExternalError>
pub fn drag_window(&self) -> Result<(), ExternalError>
Moves the window with the left mouse button until the button is released.
There’s no guarantee that this will work unless the left mouse button was pressed immediately before this function is called.
Platform-specific
- X11: Un-grabs the cursor.
- Wayland: Requires the cursor to be inside the window to be dragged.
- macOS: May prevent the button release event to be triggered.
- iOS / Android / Web / Orbital: Always returns an
ExternalError::NotSupported
.
sourcepub fn drag_resize_window(
&self,
direction: ResizeDirection
) -> Result<(), ExternalError>
pub fn drag_resize_window( &self, direction: ResizeDirection ) -> Result<(), ExternalError>
Resizes the window with the left mouse button until the button is released.
There’s no guarantee that this will work unless the left mouse button was pressed immediately before this function is called.
Platform-specific
Only X11 is supported at this time.
sourcepub fn set_cursor_hittest(&self, hittest: bool) -> Result<(), ExternalError>
pub fn set_cursor_hittest(&self, hittest: bool) -> Result<(), ExternalError>
Modifies whether the window catches cursor events.
If true
, the window will catch the cursor events. If false
, events are passed through
the window such that any other window behind it receives them. By default hittest is enabled.
Platform-specific
- iOS / Android / Web / X11 / Orbital: Always returns an
ExternalError::NotSupported
.
source§impl Window
impl Window
Monitor info functions.
sourcepub fn current_monitor(&self) -> Option<MonitorHandle>
pub fn current_monitor(&self) -> Option<MonitorHandle>
Returns the monitor on which the window currently resides.
Returns None
if current monitor can’t be detected.
Platform-specific
iOS: Can only be called on the main thread.
sourcepub fn available_monitors(&self) -> impl Iterator<Item = MonitorHandle>
pub fn available_monitors(&self) -> impl Iterator<Item = MonitorHandle>
Returns the list of all the monitors available on the system.
This is the same as EventLoopWindowTarget::available_monitors
, and is provided for convenience.
Platform-specific
iOS: Can only be called on the main thread.
sourcepub fn primary_monitor(&self) -> Option<MonitorHandle>
pub fn primary_monitor(&self) -> Option<MonitorHandle>
Returns the primary monitor of the system.
Returns None
if it can’t identify any monitor as a primary one.
This is the same as EventLoopWindowTarget::primary_monitor
, and is provided for convenience.
Platform-specific
iOS: Can only be called on the main thread.
Wayland: Always returns None
.
Trait Implementations§
source§impl HasRawDisplayHandle for Window
impl HasRawDisplayHandle for Window
source§fn raw_display_handle(&self) -> RawDisplayHandle
fn raw_display_handle(&self) -> RawDisplayHandle
Returns a raw_window_handle::RawDisplayHandle
used by the EventLoop
that
created a window.
source§impl HasRawWindowHandle for Window
impl HasRawWindowHandle for Window
source§fn raw_window_handle(&self) -> RawWindowHandle
fn raw_window_handle(&self) -> RawWindowHandle
Returns a raw_window_handle::RawWindowHandle
for the Window
Platform-specific
Android
Only available after receiving Event::Resumed
and before Event::Suspended
. If you
try to get the handle outside of that period, this function will panic!
Make sure to release or destroy any resources created from this RawWindowHandle
(ie. Vulkan
or OpenGL surfaces) before returning from Event::Suspended
, at which point Android will
release the underlying window/surface: any subsequent interaction is undefined behavior.
source§impl WindowExtWayland for Window
Available on wayland_platform
only.
impl WindowExtWayland for Window
wayland_platform
only.