alex/winit-sonoma-fix
1
0
Fork 0
mirror of https://github.com/italicsjenga/winit-sonoma-fix.git synced 2024-12-23 22:01:31 +11:00
Code Issues Packages Projects Releases Wiki Activity

Documentation cleanup (#2328)

Browse source 
* Remove redundant documentation links

* Add note to README about windows not showing up on Wayland

* Fix documentation links

* Small documentation fixes

* Add note about doing stuff after StartCause::Init on macOS
This commit is contained in:
Mads Marquart 2022-06-11 18:57:19 +02:00 committed by GitHub
parent 6474891f1e
commit 3e0a544eb8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 223 additions and 198 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
README.md
View file

@ -69,6 +69,14 @@ Winit provides the following features, which can be enabled in your `Cargo.toml`
### Platform-specific usage ### Platform-specific usage
#### Wayland
Note that windows don't appear on Wayland until you draw/present to them.
`winit` doesn't do drawing, try the examples in [`glutin`] instead.
[`glutin`]: https://github.com/rust-windowing/glutin
#### WebAssembly #### WebAssembly
To run the web example: `cargo run-wasm --example web` To run the web example: `cargo run-wasm --example web`
@ -121,3 +129,16 @@ fn main() {
``` ```
And run the application with `cargo apk run --example request_redraw_threaded` And run the application with `cargo apk run --example request_redraw_threaded`
#### MacOS
A lot of functionality expects the application to be ready before you start
doing anything; this includes creating windows, fetching monitors, drawing,
and so on, see issues [#2238], [#2051] and [#2087].
If you encounter problems, you should try doing your initialization inside
`Event::NewEvents(StartCause::Init)`.
[#2238]: https://github.com/rust-windowing/winit/issues/2238
[#2051]: https://github.com/rust-windowing/winit/issues/2051
[#2087]: https://github.com/rust-windowing/winit/issues/2087

24
src/dpi.rs
View file

@ -35,8 +35,9 @@
//! //!
//! ### Position and Size types //! ### Position and Size types
//! //!
//! Winit's `Physical(Position|Size)` types correspond with the actual pixels on the device, and the //! Winit's [`PhysicalPosition`] / [`PhysicalSize`] types correspond with the actual pixels on the
//! `Logical(Position|Size)` types correspond to the physical pixels divided by the scale factor. //! device, and the [`LogicalPosition`] / [`LogicalSize`] types correspond to the physical pixels
//! divided by the scale factor.
//! All of Winit's functions return physical types, but can take either logical or physical //! All of Winit's functions return physical types, but can take either logical or physical
//! coordinates as input, allowing you to use the most convenient coordinate system for your //! coordinates as input, allowing you to use the most convenient coordinate system for your
//! particular application. //! particular application.
@ -46,19 +47,18 @@
//! floating precision when necessary (e.g. logical sizes for fractional scale factors and touch //! floating precision when necessary (e.g. logical sizes for fractional scale factors and touch
//! input). If `P` is a floating-point type, please do not cast the values with `as {int}`. Doing so //! input). If `P` is a floating-point type, please do not cast the values with `as {int}`. Doing so
//! will truncate the fractional part of the float, rather than properly round to the nearest //! will truncate the fractional part of the float, rather than properly round to the nearest
//! integer. Use the provided `cast` function or `From`/`Into` conversions, which handle the //! integer. Use the provided `cast` function or [`From`]/[`Into`] conversions, which handle the
//! rounding properly. Note that precision loss will still occur when rounding from a float to an //! rounding properly. Note that precision loss will still occur when rounding from a float to an
//! int, although rounding lessens the problem. //! int, although rounding lessens the problem.
//! //!
//! ### Events //! ### Events
//! //!
//! Winit will dispatch a [`ScaleFactorChanged`](crate::event::WindowEvent::ScaleFactorChanged) //! Winit will dispatch a [`ScaleFactorChanged`] event whenever a window's scale factor has changed.
//! event whenever a window's scale factor has changed. This can happen if the user drags their //! This can happen if the user drags their window from a standard-resolution monitor to a high-DPI
//! window from a standard-resolution monitor to a high-DPI monitor, or if the user changes their //! monitor, or if the user changes their DPI settings. This gives you a chance to rescale your
//! DPI settings. This gives you a chance to rescale your application's UI elements and adjust how //! application's UI elements and adjust how the platform changes the window's size to reflect the new
//! the platform changes the window's size to reflect the new scale factor. If a window hasn't //! scale factor. If a window hasn't received a [`ScaleFactorChanged`] event, then its scale factor
//! received a [`ScaleFactorChanged`](crate::event::WindowEvent::ScaleFactorChanged) event, //! can be found by calling [`window.scale_factor()`].
//! then its scale factor can be found by calling [window.scale_factor()].
//! //!
//! ## How is the scale factor calculated? //! ## How is the scale factor calculated?
//! //!
@ -93,9 +93,11 @@
//! In other words, it is the value of [`window.devicePixelRatio`][web_1]. It is affected by //! In other words, it is the value of [`window.devicePixelRatio`][web_1]. It is affected by
//! both the screen scaling and the browser zoom level and can go below `1.0`. //! both the screen scaling and the browser zoom level and can go below `1.0`.
//! //!
//!
//! [points]: https://en.wikipedia.org/wiki/Point_(typography) //! [points]: https://en.wikipedia.org/wiki/Point_(typography)
//! [picas]: https://en.wikipedia.org/wiki/Pica_(typography) //! [picas]: https://en.wikipedia.org/wiki/Pica_(typography)
//! [window.scale_factor()]: crate::window::Window::scale_factor //! [`ScaleFactorChanged`]: crate::event::WindowEvent::ScaleFactorChanged
//! [`window.scale_factor()`]: crate::window::Window::scale_factor
//! [windows_1]: https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows //! [windows_1]: https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows
//! [apple_1]: https://developer.apple.com/library/archive/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/Displays/Displays.html //! [apple_1]: https://developer.apple.com/library/archive/documentation/DeviceInformation/Reference/iOSDeviceCompatibility/Displays/Displays.html
//! [apple_2]: https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/image-size-and-resolution/ //! [apple_2]: https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/image-size-and-resolution/

51
src/event.rs
View file

@ -1,10 +1,10 @@
//! The `Event` enum and assorted supporting types. //! The [`Event`] enum and assorted supporting types.
//! //!
//! These are sent to the closure given to [`EventLoop::run(...)`][event_loop_run], where they get //! These are sent to the closure given to [`EventLoop::run(...)`], where they get
//! processed and used to modify the program state. For more details, see the root-level documentation. //! processed and used to modify the program state. For more details, see the root-level documentation.
//! //!
//! Some of these events represent different "parts" of a traditional event-handling loop. You could //! Some of these events represent different "parts" of a traditional event-handling loop. You could
//! approximate the basic ordering loop of [`EventLoop::run(...)`][event_loop_run] like this: //! approximate the basic ordering loop of [`EventLoop::run(...)`] like this:
//! //!
//! ```rust,ignore //! ```rust,ignore
//! let mut control_flow = ControlFlow::Poll; //! let mut control_flow = ControlFlow::Poll;
@ -29,10 +29,11 @@
//! event_handler(LoopDestroyed, ..., &mut control_flow); //! event_handler(LoopDestroyed, ..., &mut control_flow);
//! ``` //! ```
//! //!
//! This leaves out timing details like `ControlFlow::WaitUntil` but hopefully //! This leaves out timing details like [`ControlFlow::WaitUntil`] but hopefully
//! describes what happens in what order. //! describes what happens in what order.
//! //!
//! [event_loop_run]: crate::event_loop::EventLoop::run //! [`EventLoop::run(...)`]: crate::event_loop::EventLoop::run
//! [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
use instant::Instant; use instant::Instant;
use std::path::PathBuf; use std::path::PathBuf;
@ -90,7 +91,7 @@ pub enum Event<'a, T: 'static> {
/// can render here unconditionally for simplicity. /// can render here unconditionally for simplicity.
MainEventsCleared, MainEventsCleared,
/// Emitted after `MainEventsCleared` when a window should be redrawn. /// Emitted after [`MainEventsCleared`] when a window should be redrawn.
/// ///
/// This gets triggered in two scenarios: /// This gets triggered in two scenarios:
/// - The OS has performed an operation that's invalidated the window's contents (such as /// - The OS has performed an operation that's invalidated the window's contents (such as
@ -102,14 +103,18 @@ pub enum Event<'a, T: 'static> {
/// ///
/// Mainly of interest to applications with mostly-static graphics that avoid redrawing unless /// Mainly of interest to applications with mostly-static graphics that avoid redrawing unless
/// something changes, like most non-game GUIs. /// something changes, like most non-game GUIs.
///
/// [`MainEventsCleared`]: Self::MainEventsCleared
RedrawRequested(WindowId), RedrawRequested(WindowId),
/// Emitted after all `RedrawRequested` events have been processed and control flow is about to /// Emitted after all [`RedrawRequested`] events have been processed and control flow is about to
/// be taken away from the program. If there are no `RedrawRequested` events, it is emitted /// be taken away from the program. If there are no `RedrawRequested` events, it is emitted
/// immediately after `MainEventsCleared`. /// immediately after `MainEventsCleared`.
/// ///
/// This event is useful for doing any cleanup or bookkeeping work after all the rendering /// This event is useful for doing any cleanup or bookkeeping work after all the rendering
/// tasks have been completed. /// tasks have been completed.
///
/// [`RedrawRequested`]: Self::RedrawRequested
RedrawEventsCleared, RedrawEventsCleared,
/// Emitted when the event loop is being shut down. /// Emitted when the event loop is being shut down.
@ -184,9 +189,11 @@ impl<'a, T> Event<'a, T> {
/// Describes the reason the event loop is resuming. /// Describes the reason the event loop is resuming.
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StartCause { pub enum StartCause {
/// Sent if the time specified by `ControlFlow::WaitUntil` has been reached. Contains the /// Sent if the time specified by [`ControlFlow::WaitUntil`] has been reached. Contains the
/// moment the timeout was requested and the requested resume time. The actual resume time is /// moment the timeout was requested and the requested resume time. The actual resume time is
/// guaranteed to be equal to or after the requested resume time. /// guaranteed to be equal to or after the requested resume time.
///
/// [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
ResumeTimeReached { ResumeTimeReached {
start: Instant, start: Instant,
requested_resume: Instant, requested_resume: Instant,
@ -200,7 +207,9 @@ pub enum StartCause {
}, },
/// Sent if the event loop is being resumed after the loop's control flow was set to /// Sent if the event loop is being resumed after the loop's control flow was set to
/// `ControlFlow::Poll`. /// [`ControlFlow::Poll`].
///
/// [`ControlFlow::Poll`]: crate::event_loop::ControlFlow::Poll
Poll, Poll,
/// Sent once, immediately after `run` is called. Indicates that the loop was just initialized. /// Sent once, immediately after `run` is called. Indicates that the loop was just initialized.
@ -550,7 +559,7 @@ impl<'a> WindowEvent<'a> {
pub struct DeviceId(pub(crate) platform_impl::DeviceId); pub struct DeviceId(pub(crate) platform_impl::DeviceId);
impl DeviceId { impl DeviceId {
/// Returns a dummy `DeviceId`, useful for unit testing. /// Returns a dummy id, useful for unit testing.
/// ///
/// # Safety /// # Safety
/// ///
@ -579,7 +588,7 @@ pub enum DeviceEvent {
/// Change in physical position of a pointing device. /// Change in physical position of a pointing device.
/// ///
/// This represents raw, unfiltered physical motion. Not to be confused with `WindowEvent::CursorMoved`. /// This represents raw, unfiltered physical motion. Not to be confused with [`WindowEvent::CursorMoved`].
MouseMotion { MouseMotion {
/// (x, y) change in position in unspecified units. /// (x, y) change in position in unspecified units.
/// ///
@ -592,7 +601,7 @@ pub enum DeviceEvent {
delta: MouseScrollDelta, delta: MouseScrollDelta,
}, },
/// Motion on some analog axis. This event will be reported for all arbitrary input devices /// Motion on some analog axis. This event will be reported for all arbitrary input devices
/// that winit supports on this platform, including mouse devices. If the device is a mouse /// that winit supports on this platform, including mouse devices. If the device is a mouse
/// device then this will be reported alongside the MouseMotion event. /// device then this will be reported alongside the MouseMotion event.
Motion { Motion {
@ -673,7 +682,6 @@ pub struct KeyboardInput {
/// // Press space key /// // Press space key
/// Ime::Commit("啊不") /// Ime::Commit("啊不")
/// ``` /// ```
///
#[derive(Debug, Clone, PartialEq, Eq, Hash)] #[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum Ime { pub enum Ime {
@ -718,18 +726,18 @@ pub enum TouchPhase {
/// Represents a touch event /// Represents a touch event
/// ///
/// Every time the user touches the screen, a new `Start` event with an unique /// Every time the user touches the screen, a new [`TouchPhase::Started`] event with an unique
/// identifier for the finger is generated. When the finger is lifted, an `End` /// identifier for the finger is generated. When the finger is lifted, an [`TouchPhase::Ended`]
/// event is generated with the same finger id. /// event is generated with the same finger id.
/// ///
/// After a `Start` event has been emitted, there may be zero or more `Move` /// After a `Started` event has been emitted, there may be zero or more `Move`
/// events when the finger is moved or the touch pressure changes. /// events when the finger is moved or the touch pressure changes.
/// ///
/// The finger id may be reused by the system after an `End` event. The user /// The finger id may be reused by the system after an `Ended` event. The user
/// should assume that a new `Start` event received with the same id has nothing /// should assume that a new `Started` event received with the same id has nothing
/// to do with the old finger and is a new finger. /// to do with the old finger and is a new finger.
/// ///
/// A `Cancelled` event is emitted when the system has canceled tracking this /// A [`TouchPhase::Cancelled`] event is emitted when the system has canceled tracking this
/// touch, such as when the window loses focus, or on iOS if the user moves the /// touch, such as when the window loses focus, or on iOS if the user moves the
/// device against their face. /// device against their face.
#[derive(Debug, Clone, Copy, PartialEq)] #[derive(Debug, Clone, Copy, PartialEq)]
@ -783,8 +791,9 @@ pub enum Force {
impl Force { impl Force {
/// Returns the force normalized to the range between 0.0 and 1.0 inclusive. /// Returns the force normalized to the range between 0.0 and 1.0 inclusive.
///
/// Instead of normalizing the force, you should prefer to handle /// Instead of normalizing the force, you should prefer to handle
/// `Force::Calibrated` so that the amount of force the user has to apply is /// [`Force::Calibrated`] so that the amount of force the user has to apply is
/// consistent across devices. /// consistent across devices.
pub fn normalized(&self) -> f64 { pub fn normalized(&self) -> f64 {
match self { match self {
@ -845,7 +854,7 @@ pub enum MouseScrollDelta {
/// Amount in pixels to scroll in the horizontal and /// Amount in pixels to scroll in the horizontal and
/// vertical direction. /// vertical direction.
/// ///
/// Scroll events are expressed as a PixelDelta if /// Scroll events are expressed as a `PixelDelta` if
/// supported by the device (eg. a touchpad) and /// supported by the device (eg. a touchpad) and
/// platform. /// platform.
/// ///

97
src/event_loop.rs
View file

@ -1,14 +1,12 @@
//! The `EventLoop` struct and assorted supporting types, including `ControlFlow`. //! The [`EventLoop`] struct and assorted supporting types, including
//! [`ControlFlow`].
//! //!
//! If you want to send custom events to the event loop, use [`EventLoop::create_proxy()`][create_proxy] //! If you want to send custom events to the event loop, use
//! to acquire an [`EventLoopProxy`][event_loop_proxy] and call its [`send_event`][send_event] method. //! [`EventLoop::create_proxy`] to acquire an [`EventLoopProxy`] and call its
//! [`send_event`](`EventLoopProxy::send_event`) method.
//! //!
//! See the root-level documentation for information on how to create and use an event loop to //! See the root-level documentation for information on how to create and use an event loop to
//! handle events. //! handle events.
//!
//! [create_proxy]: crate::event_loop::EventLoop::create_proxy
//! [event_loop_proxy]: crate::event_loop::EventLoopProxy
//! [send_event]: crate::event_loop::EventLoopProxy::send_event
use instant::Instant; use instant::Instant;
use std::marker::PhantomData; use std::marker::PhantomData;
use std::ops::Deref; use std::ops::Deref;
@ -19,26 +17,27 @@ use crate::{event::Event, monitor::MonitorHandle, platform_impl};
/// Provides a way to retrieve events from the system and from the windows that were registered to /// Provides a way to retrieve events from the system and from the windows that were registered to
/// the events loop. /// the events loop.
/// ///
/// An `EventLoop` can be seen more or less as a "context". Calling `EventLoop::new()` /// An `EventLoop` can be seen more or less as a "context". Calling [`EventLoop::new`]
/// initializes everything that will be required to create windows. For example on Linux creating /// initializes everything that will be required to create windows. For example on Linux creating
/// an event loop opens a connection to the X or Wayland server. /// an event loop opens a connection to the X or Wayland server.
/// ///
/// To wake up an `EventLoop` from a another thread, see the `EventLoopProxy` docs. /// To wake up an `EventLoop` from a another thread, see the [`EventLoopProxy`] docs.
/// ///
/// Note that the `EventLoop` cannot be shared across threads (due to platform-dependant logic /// Note that this cannot be shared across threads (due to platform-dependant logic
/// forbidding it), as such it is neither `Send` nor `Sync`. If you need cross-thread access, the /// forbidding it), as such it is neither [`Send`] nor [`Sync`]. If you need cross-thread access, the
/// `Window` created from this `EventLoop` _can_ be sent to an other thread, and the /// [`Window`] created from this _can_ be sent to an other thread, and the
/// `EventLoopProxy` allows you to wake up an `EventLoop` from another thread. /// [`EventLoopProxy`] allows you to wake up an `EventLoop` from another thread.
/// ///
/// [`Window`]: crate::window::Window
pub struct EventLoop<T: 'static> { pub struct EventLoop<T: 'static> {
pub(crate) event_loop: platform_impl::EventLoop<T>, pub(crate) event_loop: platform_impl::EventLoop<T>,
pub(crate) _marker: PhantomData<*mut ()>, // Not Send nor Sync pub(crate) _marker: PhantomData<*mut ()>, // Not Send nor Sync
} }
/// Target that associates windows with an `EventLoop`. /// Target that associates windows with an [`EventLoop`].
/// ///
/// This type exists to allow you to create new windows while Winit executes /// This type exists to allow you to create new windows while Winit executes
/// your callback. `EventLoop` will coerce into this type (`impl<T> Deref for /// your callback. [`EventLoop`] will coerce into this type (`impl<T> Deref for
/// EventLoop<T>`), so functions that take this as a parameter can also take /// EventLoop<T>`), so functions that take this as a parameter can also take
/// `&EventLoop`. /// `&EventLoop`.
pub struct EventLoopWindowTarget<T: 'static> { pub struct EventLoopWindowTarget<T: 'static> {
@ -77,11 +76,11 @@ impl<T> EventLoopBuilder<T> {
/// Builds a new event loop. /// Builds a new event loop.
/// ///
/// ***For cross-platform compatibility, the `EventLoop` must be created on the main thread.*** /// ***For cross-platform compatibility, the [`EventLoop`] must be created on the main thread.***
/// Attempting to create the event loop on a different thread will panic. This restriction isn't /// Attempting to create the event loop on a different thread will panic. This restriction isn't
/// strictly necessary on all platforms, but is imposed to eliminate any nasty surprises when /// strictly necessary on all platforms, but is imposed to eliminate any nasty surprises when
/// porting to platforms that require it. `EventLoopBuilderExt::any_thread` functions are exposed /// porting to platforms that require it. `EventLoopBuilderExt::any_thread` functions are exposed
/// in the relevant `platform` module if the target platform supports creating an event loop on /// in the relevant [`platform`] module if the target platform supports creating an event loop on
/// any thread. /// any thread.
/// ///
/// Calling this function will result in display backend initialisation. /// Calling this function will result in display backend initialisation.
@ -92,6 +91,8 @@ impl<T> EventLoopBuilder<T> {
/// `WINIT_UNIX_BACKEND`. Legal values are `x11` and `wayland`. /// `WINIT_UNIX_BACKEND`. Legal values are `x11` and `wayland`.
/// If it is not set, winit will try to connect to a Wayland connection, and if that fails, /// If it is not set, winit will try to connect to a Wayland connection, and if that fails,
/// will fall back on X11. If this variable is set with any other value, winit will panic. /// will fall back on X11. If this variable is set with any other value, winit will panic.
///
/// [`platform`]: crate::platform
#[inline] #[inline]
pub fn build(&mut self) -> EventLoop<T> { pub fn build(&mut self) -> EventLoop<T> {
// Certain platforms accept a mutable reference in their API. // Certain platforms accept a mutable reference in their API.
@ -115,18 +116,21 @@ impl<T> fmt::Debug for EventLoopWindowTarget<T> {
} }
} }
/// Set by the user callback given to the `EventLoop::run` method. /// Set by the user callback given to the [`EventLoop::run`] method.
/// ///
/// Indicates the desired behavior of the event loop after [`Event::RedrawEventsCleared`][events_cleared] /// Indicates the desired behavior of the event loop after [`Event::RedrawEventsCleared`] is emitted.
/// is emitted. Defaults to `Poll`. ///
/// Defaults to [`Poll`].
/// ///
/// ## Persistency /// ## Persistency
/// Almost every change is persistent between multiple calls to the event loop closure within a
/// given run loop. The only exception to this is `ExitWithCode` which, once set, cannot be unset.
/// Changes are **not** persistent between multiple calls to `run_return` - issuing a new call will
/// reset the control flow to `Poll`.
/// ///
/// [events_cleared]: crate::event::Event::RedrawEventsCleared /// Almost every change is persistent between multiple calls to the event loop closure within a
/// given run loop. The only exception to this is [`ExitWithCode`] which, once set, cannot be unset.
/// Changes are **not** persistent between multiple calls to `run_return` - issuing a new call will
/// reset the control flow to [`Poll`].
///
/// [`ExitWithCode`]: Self::ExitWithCode
/// [`Poll`]: Self::Poll
#[derive(Copy, Clone, Debug, PartialEq, Eq)] #[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum ControlFlow { pub enum ControlFlow {
/// When the current loop iteration finishes, immediately begin a new iteration regardless of /// When the current loop iteration finishes, immediately begin a new iteration regardless of
@ -144,10 +148,12 @@ pub enum ControlFlow {
/// arrives or the given time is reached. /// arrives or the given time is reached.
/// ///
/// Useful for implementing efficient timers. Applications which want to render at the display's /// Useful for implementing efficient timers. Applications which want to render at the display's
/// native refresh rate should instead use `Poll` and the VSync functionality of a graphics API /// native refresh rate should instead use [`Poll`] and the VSync functionality of a graphics API
/// to reduce odds of missed frames. /// to reduce odds of missed frames.
///
/// [`Poll`]: Self::Poll
WaitUntil(Instant), WaitUntil(Instant),
/// Send a `LoopDestroyed` event and stop the event loop. This variant is *sticky* - once set, /// Send a [`LoopDestroyed`] event and stop the event loop. This variant is *sticky* - once set,
/// `control_flow` cannot be changed from `ExitWithCode`, and any future attempts to do so will /// `control_flow` cannot be changed from `ExitWithCode`, and any future attempts to do so will
/// result in the `control_flow` parameter being reset to `ExitWithCode`. /// result in the `control_flow` parameter being reset to `ExitWithCode`.
/// ///
@ -161,6 +167,7 @@ pub enum ControlFlow {
/// which can cause surprises with negative exit values (`-42` would end up as `214`). See /// which can cause surprises with negative exit values (`-42` would end up as `214`). See
/// [`std::process::exit`]. /// [`std::process::exit`].
/// ///
/// [`LoopDestroyed`]: Event::LoopDestroyed
/// [`Exit`]: ControlFlow::Exit /// [`Exit`]: ControlFlow::Exit
ExitWithCode(i32), ExitWithCode(i32),
} }
@ -168,41 +175,41 @@ pub enum ControlFlow {
impl ControlFlow { impl ControlFlow {
/// Alias for [`ExitWithCode`]`(0)`. /// Alias for [`ExitWithCode`]`(0)`.
/// ///
/// [`ExitWithCode`]: ControlFlow::ExitWithCode /// [`ExitWithCode`]: Self::ExitWithCode
#[allow(non_upper_case_globals)] #[allow(non_upper_case_globals)]
pub const Exit: Self = Self::ExitWithCode(0); pub const Exit: Self = Self::ExitWithCode(0);
/// Sets this to [`Poll`]. /// Sets this to [`Poll`].
/// ///
/// [`Poll`]: ControlFlow::Poll /// [`Poll`]: Self::Poll
pub fn set_poll(&mut self) { pub fn set_poll(&mut self) {
*self = Self::Poll; *self = Self::Poll;
} }
/// Sets this to [`Wait`]. /// Sets this to [`Wait`].
/// ///
/// [`Wait`]: ControlFlow::Wait /// [`Wait`]: Self::Wait
pub fn set_wait(&mut self) { pub fn set_wait(&mut self) {
*self = Self::Wait; *self = Self::Wait;
} }
/// Sets this to [`WaitUntil`]`(instant)`. /// Sets this to [`WaitUntil`]`(instant)`.
/// ///
/// [`WaitUntil`]: ControlFlow::WaitUntil /// [`WaitUntil`]: Self::WaitUntil
pub fn set_wait_until(&mut self, instant: Instant) { pub fn set_wait_until(&mut self, instant: Instant) {
*self = Self::WaitUntil(instant); *self = Self::WaitUntil(instant);
} }
/// Sets this to [`ExitWithCode`]`(code)`. /// Sets this to [`ExitWithCode`]`(code)`.
/// ///
/// [`ExitWithCode`]: ControlFlow::ExitWithCode /// [`ExitWithCode`]: Self::ExitWithCode
pub fn set_exit_with_code(&mut self, code: i32) { pub fn set_exit_with_code(&mut self, code: i32) {
*self = Self::ExitWithCode(code); *self = Self::ExitWithCode(code);
} }
/// Sets this to [`Exit`]. /// Sets this to [`Exit`].
/// ///
/// [`Exit`]: ControlFlow::Exit /// [`Exit`]: Self::Exit
pub fn set_exit(&mut self) { pub fn set_exit(&mut self) {
*self = Self::Exit; *self = Self::Exit;
} }
@ -210,13 +217,15 @@ impl ControlFlow {
impl Default for ControlFlow { impl Default for ControlFlow {
#[inline(always)] #[inline(always)]
fn default() -> ControlFlow { fn default() -> Self {
ControlFlow::Poll Self::Poll
} }
} }
impl EventLoop<()> { impl EventLoop<()> {
/// Alias for `EventLoopBuilder::new().build()`. /// Alias for [`EventLoopBuilder::new().build()`].
///
/// [`EventLoopBuilder::new().build()`]: EventLoopBuilder::build
#[inline] #[inline]
pub fn new() -> EventLoop<()> { pub fn new() -> EventLoop<()> {
EventLoopBuilder::new().build() EventLoopBuilder::new().build()
@ -258,7 +267,7 @@ impl<T> EventLoop<T> {
self.event_loop.run(event_handler) self.event_loop.run(event_handler)
} }
/// Creates an `EventLoopProxy` that can be used to dispatch user events to the main event loop. /// Creates an [`EventLoopProxy`] that can be used to dispatch user events to the main event loop.
pub fn create_proxy(&self) -> EventLoopProxy<T> { pub fn create_proxy(&self) -> EventLoopProxy<T> {
EventLoopProxy { EventLoopProxy {
event_loop_proxy: self.event_loop.create_proxy(), event_loop_proxy: self.event_loop.create_proxy(),
@ -318,7 +327,7 @@ impl<T> EventLoopWindowTarget<T> {
} }
} }
/// Used to send custom events to `EventLoop`. /// Used to send custom events to [`EventLoop`].
pub struct EventLoopProxy<T: 'static> { pub struct EventLoopProxy<T: 'static> {
event_loop_proxy: platform_impl::EventLoopProxy<T>, event_loop_proxy: platform_impl::EventLoopProxy<T>,
} }
@ -332,11 +341,13 @@ impl<T: 'static> Clone for EventLoopProxy<T> {
} }
impl<T: 'static> EventLoopProxy<T> { impl<T: 'static> EventLoopProxy<T> {
/// Send an event to the `EventLoop` from which this proxy was created. This emits a /// Send an event to the [`EventLoop`] from which this proxy was created. This emits a
/// `UserEvent(event)` event in the event loop, where `event` is the value passed to this /// `UserEvent(event)` event in the event loop, where `event` is the value passed to this
/// function. /// function.
/// ///
/// Returns an `Err` if the associated `EventLoop` no longer exists. /// Returns an `Err` if the associated [`EventLoop`] no longer exists.
///
/// [`UserEvent(event)`]: Event::UserEvent
pub fn send_event(&self, event: T) -> Result<(), EventLoopClosed<T>> { pub fn send_event(&self, event: T) -> Result<(), EventLoopClosed<T>> {
self.event_loop_proxy.send_event(event) self.event_loop_proxy.send_event(event)
} }
@ -348,8 +359,10 @@ impl<T: 'static> fmt::Debug for EventLoopProxy<T> {
} }
} }
/// The error that is returned when an `EventLoopProxy` attempts to wake up an `EventLoop` that /// The error that is returned when an [`EventLoopProxy`] attempts to wake up an [`EventLoop`] that
/// no longer exists. Contains the original event given to `send_event`. /// no longer exists.
///
/// Contains the original event given to [`EventLoopProxy::send_event`].
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct EventLoopClosed<T>(pub T); pub struct EventLoopClosed<T>(pub T);

8
src/icon.rs
View file

@ -13,7 +13,7 @@ pub(crate) struct Pixel {
pub(crate) const PIXEL_SIZE: usize = mem::size_of::<Pixel>(); pub(crate) const PIXEL_SIZE: usize = mem::size_of::<Pixel>();
#[derive(Debug)] #[derive(Debug)]
/// An error produced when using `Icon::from_rgba` with invalid arguments. /// An error produced when using [`Icon::from_rgba`] with invalid arguments.
pub enum BadIcon { pub enum BadIcon {
/// Produced when the length of the `rgba` argument isn't divisible by 4, thus `rgba` can't be /// Produced when the length of the `rgba` argument isn't divisible by 4, thus `rgba` can't be
/// safely interpreted as 32bpp RGBA pixels. /// safely interpreted as 32bpp RGBA pixels.
@ -73,10 +73,6 @@ mod constructors {
use super::*; use super::*;
impl RgbaIcon { impl RgbaIcon {
/// Creates an `Icon` from 32bpp RGBA data.
///
/// The length of `rgba` must be divisible by 4, and `width * height` must equal
/// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error.
pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, BadIcon> { pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, BadIcon> {
if rgba.len() % PIXEL_SIZE != 0 { if rgba.len() % PIXEL_SIZE != 0 {
return Err(BadIcon::ByteCountNotDivisibleBy4 { return Err(BadIcon::ByteCountNotDivisibleBy4 {
@ -123,7 +119,7 @@ impl fmt::Debug for Icon {
} }
impl Icon { impl Icon {
/// Creates an `Icon` from 32bpp RGBA data. /// Creates an icon from 32bpp RGBA data.
/// ///
/// The length of `rgba` must be divisible by 4, and `width * height` must equal /// The length of `rgba` must be divisible by 4, and `width * height` must equal
/// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error. /// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error.

19
src/monitor.rs
View file

@ -1,14 +1,10 @@
//! Types useful for interacting with a user's monitors. //! Types useful for interacting with a user's monitors.
//! //!
//! If you want to get basic information about a monitor, you can use the [`MonitorHandle`][monitor_handle] //! If you want to get basic information about a monitor, you can use the
//! type. This is retrieved from one of the following methods, which return an iterator of //! [`MonitorHandle`] type. This is retrieved from one of the following
//! [`MonitorHandle`][monitor_handle]: //! methods, which return an iterator of [`MonitorHandle`]:
//! - [`EventLoopWindowTarget::available_monitors`][loop_get] //! - [`EventLoopWindowTarget::available_monitors`](crate::event_loop::EventLoopWindowTarget::available_monitors).
//! - [`Window::available_monitors`][window_get]. //! - [`Window::available_monitors`](crate::window::Window::available_monitors).
//!
//! [monitor_handle]: crate::monitor::MonitorHandle
//! [loop_get]: crate::event_loop::EventLoopWindowTarget::available_monitors
//! [window_get]: crate::window::Window::available_monitors
use crate::{ use crate::{
dpi::{PhysicalPosition, PhysicalSize}, dpi::{PhysicalPosition, PhysicalSize},
platform_impl, platform_impl,
@ -16,10 +12,7 @@ use crate::{
/// Describes a fullscreen video mode of a monitor. /// Describes a fullscreen video mode of a monitor.
/// ///
/// Can be acquired with: /// Can be acquired with [`MonitorHandle::video_modes`].
/// - [`MonitorHandle::video_modes`][monitor_get].
///
/// [monitor_get]: crate::monitor::MonitorHandle::video_modes
#[derive(Clone, PartialEq, Eq, Hash)] #[derive(Clone, PartialEq, Eq, Hash)]
pub struct VideoMode { pub struct VideoMode {
pub(crate) video_mode: platform_impl::VideoMode, pub(crate) video_mode: platform_impl::VideoMode,

8
src/platform/android.rs
View file

@ -7,15 +7,15 @@ use crate::{
use ndk::configuration::Configuration; use ndk::configuration::Configuration;
use ndk_glue::Rect; use ndk_glue::Rect;
/// Additional methods on `EventLoop` that are specific to Android. /// Additional methods on [`EventLoop`] that are specific to Android.
pub trait EventLoopExtAndroid {} pub trait EventLoopExtAndroid {}
impl<T> EventLoopExtAndroid for EventLoop<T> {} impl<T> EventLoopExtAndroid for EventLoop<T> {}
/// Additional methods on `EventLoopWindowTarget` that are specific to Android. /// Additional methods on [`EventLoopWindowTarget`] that are specific to Android.
pub trait EventLoopWindowTargetExtAndroid {} pub trait EventLoopWindowTargetExtAndroid {}
/// Additional methods on `Window` that are specific to Android. /// Additional methods on [`Window`] that are specific to Android.
pub trait WindowExtAndroid { pub trait WindowExtAndroid {
fn content_rect(&self) -> Rect; fn content_rect(&self) -> Rect;
@ -34,7 +34,7 @@ impl WindowExtAndroid for Window {
impl<T> EventLoopWindowTargetExtAndroid for EventLoopWindowTarget<T> {} impl<T> EventLoopWindowTargetExtAndroid for EventLoopWindowTarget<T> {}
/// Additional methods on `WindowBuilder` that are specific to Android. /// Additional methods on [`WindowBuilder`] that are specific to Android.
pub trait WindowBuilderExtAndroid {} pub trait WindowBuilderExtAndroid {}
impl WindowBuilderExtAndroid for WindowBuilder {} impl WindowBuilderExtAndroid for WindowBuilder {}

26
src/platform/macos.rs
View file

@ -9,16 +9,16 @@ use crate::{
window::{Window, WindowBuilder}, window::{Window, WindowBuilder},
}; };
/// Additional methods on `Window` that are specific to MacOS. /// Additional methods on [`Window`] that are specific to MacOS.
pub trait WindowExtMacOS { pub trait WindowExtMacOS {
/// Returns a pointer to the cocoa `NSWindow` that is used by this window. /// Returns a pointer to the cocoa `NSWindow` that is used by this window.
/// ///
/// The pointer will become invalid when the `Window` is destroyed. /// The pointer will become invalid when the [`Window`] is destroyed.
fn ns_window(&self) -> *mut c_void; fn ns_window(&self) -> *mut c_void;
/// Returns a pointer to the cocoa `NSView` that is used by this window. /// Returns a pointer to the cocoa `NSView` that is used by this window.
/// ///
/// The pointer will become invalid when the `Window` is destroyed. /// The pointer will become invalid when the [`Window`] is destroyed.
fn ns_view(&self) -> *mut c_void; fn ns_view(&self) -> *mut c_void;
/// Returns whether or not the window is in simple fullscreen mode. /// Returns whether or not the window is in simple fullscreen mode.
@ -89,16 +89,14 @@ impl Default for ActivationPolicy {
} }
} }
/// Additional methods on `WindowBuilder` that are specific to MacOS. /// Additional methods on [`WindowBuilder`] that are specific to MacOS.
/// ///
/// **Note:** Properties dealing with the titlebar will be overwritten by the `with_decorations` method /// **Note:** Properties dealing with the titlebar will be overwritten by the [`WindowBuilder::with_decorations`] method:
/// on the base `WindowBuilder`: /// - `with_titlebar_transparent`
/// /// - `with_title_hidden`
/// - `with_titlebar_transparent` /// - `with_titlebar_hidden`
/// - `with_title_hidden` /// - `with_titlebar_buttons_hidden`
/// - `with_titlebar_hidden` /// - `with_fullsize_content_view`
/// - `with_titlebar_buttons_hidden`
/// - `with_fullsize_content_view`
pub trait WindowBuilderExtMacOS { pub trait WindowBuilderExtMacOS {
/// Enables click-and-drag behavior for the entire window, not just the titlebar. /// Enables click-and-drag behavior for the entire window, not just the titlebar.
fn with_movable_by_window_background(self, movable_by_window_background: bool) fn with_movable_by_window_background(self, movable_by_window_background: bool)
@ -238,7 +236,7 @@ impl<T> EventLoopBuilderExtMacOS for EventLoopBuilder<T> {
} }
} }
/// Additional methods on `MonitorHandle` that are specific to MacOS. /// Additional methods on [`MonitorHandle`] that are specific to MacOS.
pub trait MonitorHandleExtMacOS { pub trait MonitorHandleExtMacOS {
/// Returns the identifier of the monitor for Cocoa. /// Returns the identifier of the monitor for Cocoa.
fn native_id(&self) -> u32; fn native_id(&self) -> u32;
@ -257,7 +255,7 @@ impl MonitorHandleExtMacOS for MonitorHandle {
} }
} }
/// Additional methods on `EventLoopWindowTarget` that are specific to macOS. /// Additional methods on [`EventLoopWindowTarget`] that are specific to macOS.
pub trait EventLoopWindowTargetExtMacOS { pub trait EventLoopWindowTargetExtMacOS {
/// Hide the entire application. In most applications this is typically triggered with Command-H. /// Hide the entire application. In most applications this is typically triggered with Command-H.
fn hide_application(&self); fn hide_application(&self);

2
src/platform/mod.rs
View file

@ -19,7 +19,7 @@ pub mod android;
pub mod ios; pub mod ios;
pub mod macos; pub mod macos;
pub mod unix; pub mod unix;
pub mod web;
pub mod windows; pub mod windows;
pub mod run_return; pub mod run_return;
pub mod web;

9
src/platform/run_return.rs
View file

@ -14,17 +14,18 @@ use crate::{
event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget}, event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget},
}; };
/// Additional methods on `EventLoop` to return control flow to the caller. /// Additional methods on [`EventLoop`] to return control flow to the caller.
pub trait EventLoopExtRunReturn { pub trait EventLoopExtRunReturn {
/// A type provided by the user that can be passed through `Event::UserEvent`. /// A type provided by the user that can be passed through [`Event::UserEvent`].
type UserEvent; type UserEvent;
/// Initializes the `winit` event loop. /// Initializes the `winit` event loop.
/// ///
/// Unlike `run`, this function accepts non-`'static` (i.e. non-`move`) closures and returns /// Unlike [`EventLoop::run`], this function accepts non-`'static` (i.e. non-`move`) closures
/// control flow to the caller when `control_flow` is set to `ControlFlow::Exit`. /// and returns control flow to the caller when `control_flow` is set to [`ControlFlow::Exit`].
/// ///
/// # Caveats /// # Caveats
///
/// Despite its appearance at first glance, this is *not* a perfect replacement for /// Despite its appearance at first glance, this is *not* a perfect replacement for
/// `poll_events`. For example, this function will not return on Windows or macOS while a /// `poll_events`. For example, this function will not return on Windows or macOS while a
/// window is getting resized, resulting in all application logic outside of the /// window is getting resized, resulting in all application logic outside of the

30
src/platform/unix.rs
View file

@ -35,13 +35,13 @@ pub use crate::platform_impl::{x11::util::WindowType as XWindowType, XNotSupport
#[cfg(feature = "wayland")] #[cfg(feature = "wayland")]
pub use crate::window::Theme; pub use crate::window::Theme;
/// Additional methods on `EventLoopWindowTarget` that are specific to Unix. /// Additional methods on [`EventLoopWindowTarget`] that are specific to Unix.
pub trait EventLoopWindowTargetExtUnix { pub trait EventLoopWindowTargetExtUnix {
/// True if the `EventLoopWindowTarget` uses Wayland. /// True if the [`EventLoopWindowTarget`] uses Wayland.
#[cfg(feature = "wayland")] #[cfg(feature = "wayland")]
fn is_wayland(&self) -> bool; fn is_wayland(&self) -> bool;
/// True if the `EventLoopWindowTarget` uses X11. /// True if the [`EventLoopWindowTarget`] uses X11.
#[cfg(feature = "x11")] #[cfg(feature = "x11")]
fn is_x11(&self) -> bool; fn is_x11(&self) -> bool;
@ -50,11 +50,13 @@ pub trait EventLoopWindowTargetExtUnix {
fn xlib_xconnection(&self) -> Option<Arc<XConnection>>; fn xlib_xconnection(&self) -> Option<Arc<XConnection>>;
/// Returns a pointer to the `wl_display` object of wayland that is used by this /// Returns a pointer to the `wl_display` object of wayland that is used by this
/// `EventLoopWindowTarget`. /// [`EventLoopWindowTarget`].
/// ///
/// Returns `None` if the `EventLoop` doesn't use wayland (if it uses xlib for example). /// Returns `None` if the [`EventLoop`] doesn't use wayland (if it uses xlib for example).
/// ///
/// The pointer will become invalid when the winit `EventLoop` is destroyed. /// The pointer will become invalid when the winit [`EventLoop`] is destroyed.
///
/// [`EventLoop`]: crate::event_loop::EventLoop
#[cfg(feature = "wayland")] #[cfg(feature = "wayland")]
fn wayland_display(&self) -> Option<*mut raw::c_void>; fn wayland_display(&self) -> Option<*mut raw::c_void>;
} }
@ -134,9 +136,9 @@ impl<T> EventLoopBuilderExtUnix for EventLoopBuilder<T> {
} }
} }
/// Additional methods on `Window` that are specific to Unix. /// Additional methods on [`Window`] that are specific to Unix.
pub trait WindowExtUnix { pub trait WindowExtUnix {
/// Returns the ID of the `Window` xlib object that is used by this window. /// Returns the ID of the [`Window`] xlib object that is used by this window.
/// ///
/// Returns `None` if the window doesn't use xlib (if it uses wayland for example). /// Returns `None` if the window doesn't use xlib (if it uses wayland for example).
#[cfg(feature = "x11")] #[cfg(feature = "x11")]
@ -146,7 +148,7 @@ pub trait WindowExtUnix {
/// ///
/// Returns `None` if the window doesn't use xlib (if it uses wayland for example). /// Returns `None` if the window doesn't use xlib (if it uses wayland for example).
/// ///
/// The pointer will become invalid when the glutin `Window` is destroyed. /// The pointer will become invalid when the [`Window`] is destroyed.
#[cfg(feature = "x11")] #[cfg(feature = "x11")]
fn xlib_display(&self) -> Option<*mut raw::c_void>; fn xlib_display(&self) -> Option<*mut raw::c_void>;
@ -161,7 +163,7 @@ pub trait WindowExtUnix {
/// ///
/// Returns `None` if the window doesn't use xlib (if it uses wayland for example). /// Returns `None` if the window doesn't use xlib (if it uses wayland for example).
/// ///
/// The pointer will become invalid when the glutin `Window` is destroyed. /// The pointer will become invalid when the [`Window`] is destroyed.
#[cfg(feature = "x11")] #[cfg(feature = "x11")]
fn xcb_connection(&self) -> Option<*mut raw::c_void>; fn xcb_connection(&self) -> Option<*mut raw::c_void>;
@ -169,7 +171,7 @@ pub trait WindowExtUnix {
/// ///
/// Returns `None` if the window doesn't use wayland (if it uses xlib for example). /// Returns `None` if the window doesn't use wayland (if it uses xlib for example).
/// ///
/// The pointer will become invalid when the glutin `Window` is destroyed. /// The pointer will become invalid when the [`Window`] is destroyed.
#[cfg(feature = "wayland")] #[cfg(feature = "wayland")]
fn wayland_surface(&self) -> Option<*mut raw::c_void>; fn wayland_surface(&self) -> Option<*mut raw::c_void>;
@ -177,7 +179,7 @@ pub trait WindowExtUnix {
/// ///
/// Returns `None` if the window doesn't use wayland (if it uses xlib for example). /// Returns `None` if the window doesn't use wayland (if it uses xlib for example).
/// ///
/// The pointer will become invalid when the glutin `Window` is destroyed. /// The pointer will become invalid when the [`Window`] is destroyed.
#[cfg(feature = "wayland")] #[cfg(feature = "wayland")]
fn wayland_display(&self) -> Option<*mut raw::c_void>; fn wayland_display(&self) -> Option<*mut raw::c_void>;
@ -193,7 +195,7 @@ pub trait WindowExtUnix {
/// It is a remnant of a previous implementation detail for the /// It is a remnant of a previous implementation detail for the
/// wayland backend, and is no longer relevant. /// wayland backend, and is no longer relevant.
/// ///
/// Always return true. /// Always return `true`.
#[deprecated] #[deprecated]
fn is_ready(&self) -> bool; fn is_ready(&self) -> bool;
} }
@ -285,7 +287,7 @@ impl WindowExtUnix for Window {
} }
} }
/// Additional methods on `WindowBuilder` that are specific to Unix. /// Additional methods on [`WindowBuilder`] that are specific to Unix.
pub trait WindowBuilderExtUnix { pub trait WindowBuilderExtUnix {
#[cfg(feature = "x11")] #[cfg(feature = "x11")]
fn with_x11_visual<T>(self, visual_infos: *const T) -> Self; fn with_x11_visual<T>(self, visual_infos: *const T) -> Self;

4
src/platform/web.rs
View file

@ -1,8 +1,8 @@
#![cfg(target_arch = "wasm32")] #![cfg(target_arch = "wasm32")]
//! The web target does not automatically insert the canvas element object into the web page, to //! The web target does not automatically insert the canvas element object into the web page, to
//! allow end users to determine how the page should be laid out. Use the `WindowExtWebSys` trait //! allow end users to determine how the page should be laid out. Use the [`WindowExtWebSys`] trait
//! to retrieve the canvas from the Window. Alternatively, use the `WindowBuilderExtWebSys` trait //! to retrieve the canvas from the Window. Alternatively, use the [`WindowBuilderExtWebSys`] trait
//! to provide your own canvas. //! to provide your own canvas.
use crate::window::WindowBuilder; use crate::window::WindowBuilder;

122
src/window.rs
View file

@ -1,4 +1,4 @@
//! The `Window` struct and associated types. //! The [`Window`] struct and associated types.
use std::fmt; use std::fmt;
use crate::{ use crate::{
@ -61,7 +61,7 @@ impl Drop for Window {
/// Identifier of a window. Unique for each window. /// Identifier of a window. Unique for each window.
/// ///
/// Can be obtained with `window.id()`. /// Can be obtained with [`window.id()`](`Window::id`).
/// ///
/// Whenever you receive an event specific to a window, this event contains a `WindowId` which you /// Whenever you receive an event specific to a window, this event contains a `WindowId` which you
/// can then compare to the ids of your windows. /// can then compare to the ids of your windows.
@ -69,13 +69,13 @@ impl Drop for Window {
pub struct WindowId(pub(crate) platform_impl::WindowId); pub struct WindowId(pub(crate) platform_impl::WindowId);
impl WindowId { impl WindowId {
/// Returns a dummy `WindowId`, useful for unit testing. /// Returns a dummy id, useful for unit testing.
/// ///
/// # Safety /// # Safety
/// ///
/// The only guarantee made about the return value of this function is that /// The only guarantee made about the return value of this function is that
/// it will always be equal to itself and to future values returned by this function. /// it will always be equal to itself and to future values returned by this function.
/// No other guarantees are made. This may be equal to a real `WindowId`. /// No other guarantees are made. This may be equal to a real [`WindowId`].
/// ///
/// **Passing this into a winit function will result in undefined behavior.** /// **Passing this into a winit function will result in undefined behavior.**
pub const unsafe fn dummy() -> Self { pub const unsafe fn dummy() -> Self {
@ -142,7 +142,7 @@ impl Default for WindowAttributes {
} }
impl WindowBuilder { impl WindowBuilder {
/// Initializes a new `WindowBuilder` with default values. /// Initializes a new builder with default values.
#[inline] #[inline]
pub fn new() -> Self { pub fn new() -> Self {
Default::default() Default::default()
@ -153,8 +153,6 @@ impl WindowBuilder {
/// If this is not set, some platform-specific dimensions will be used. /// If this is not set, some platform-specific dimensions will be used.
/// ///
/// See [`Window::set_inner_size`] for details. /// See [`Window::set_inner_size`] for details.
///
/// [`Window::set_inner_size`]: crate::window::Window::set_inner_size
#[inline] #[inline]
pub fn with_inner_size<S: Into<Size>>(mut self, size: S) -> Self { pub fn with_inner_size<S: Into<Size>>(mut self, size: S) -> Self {
self.window.inner_size = Some(size.into()); self.window.inner_size = Some(size.into());
@ -167,8 +165,6 @@ impl WindowBuilder {
/// from reserved). /// from reserved).
/// ///
/// See [`Window::set_min_inner_size`] for details. /// See [`Window::set_min_inner_size`] for details.
///
/// [`Window::set_min_inner_size`]: crate::window::Window::set_min_inner_size
#[inline] #[inline]
pub fn with_min_inner_size<S: Into<Size>>(mut self, min_size: S) -> Self { pub fn with_min_inner_size<S: Into<Size>>(mut self, min_size: S) -> Self {
self.window.min_inner_size = Some(min_size.into()); self.window.min_inner_size = Some(min_size.into());
@ -181,8 +177,6 @@ impl WindowBuilder {
/// the primary monitor's dimensions by the platform. /// the primary monitor's dimensions by the platform.
/// ///
/// See [`Window::set_max_inner_size`] for details. /// See [`Window::set_max_inner_size`] for details.
///
/// [`Window::set_max_inner_size`]: crate::window::Window::set_max_inner_size
#[inline] #[inline]
pub fn with_max_inner_size<S: Into<Size>>(mut self, max_size: S) -> Self { pub fn with_max_inner_size<S: Into<Size>>(mut self, max_size: S) -> Self {
self.window.max_inner_size = Some(max_size.into()); self.window.max_inner_size = Some(max_size.into());
@ -211,8 +205,6 @@ impl WindowBuilder {
/// - **X11**: The top left corner of the window, the window's "outer" /// - **X11**: The top left corner of the window, the window's "outer"
/// position. /// position.
/// - **Others**: Ignored. /// - **Others**: Ignored.
///
/// [`Window::set_outer_position`]: crate::window::Window::set_outer_position
#[inline] #[inline]
pub fn with_position<P: Into<Position>>(mut self, position: P) -> Self { pub fn with_position<P: Into<Position>>(mut self, position: P) -> Self {
self.window.position = Some(position.into()); self.window.position = Some(position.into());
@ -224,8 +216,6 @@ impl WindowBuilder {
/// The default is `true`. /// The default is `true`.
/// ///
/// See [`Window::set_resizable`] for details. /// See [`Window::set_resizable`] for details.
///
/// [`Window::set_resizable`]: crate::window::Window::set_resizable
#[inline] #[inline]
pub fn with_resizable(mut self, resizable: bool) -> Self { pub fn with_resizable(mut self, resizable: bool) -> Self {
self.window.resizable = resizable; self.window.resizable = resizable;
@ -237,8 +227,6 @@ impl WindowBuilder {
/// The default is `"winit window"`. /// The default is `"winit window"`.
/// ///
/// See [`Window::set_title`] for details. /// See [`Window::set_title`] for details.
///
/// [`Window::set_title`]: crate::window::Window::set_title
#[inline] #[inline]
pub fn with_title<T: Into<String>>(mut self, title: T) -> Self { pub fn with_title<T: Into<String>>(mut self, title: T) -> Self {
self.window.title = title.into(); self.window.title = title.into();
@ -250,8 +238,6 @@ impl WindowBuilder {
/// The default is `None`. /// The default is `None`.
/// ///
/// See [`Window::set_fullscreen`] for details. /// See [`Window::set_fullscreen`] for details.
///
/// [`Window::set_fullscreen`]: crate::window::Window::set_fullscreen
#[inline] #[inline]
pub fn with_fullscreen(mut self, fullscreen: Option<Fullscreen>) -> Self { pub fn with_fullscreen(mut self, fullscreen: Option<Fullscreen>) -> Self {
self.window.fullscreen = fullscreen; self.window.fullscreen = fullscreen;
@ -263,8 +249,6 @@ impl WindowBuilder {
/// The default is `false`. /// The default is `false`.
/// ///
/// See [`Window::set_maximized`] for details. /// See [`Window::set_maximized`] for details.
///
/// [`Window::set_maximized`]: crate::window::Window::set_maximized
#[inline] #[inline]
pub fn with_maximized(mut self, maximized: bool) -> Self { pub fn with_maximized(mut self, maximized: bool) -> Self {
self.window.maximized = maximized; self.window.maximized = maximized;
@ -276,8 +260,6 @@ impl WindowBuilder {
/// The default is to show the window. /// The default is to show the window.
/// ///
/// See [`Window::set_visible`] for details. /// See [`Window::set_visible`] for details.
///
/// [`Window::set_visible`]: crate::window::Window::set_visible
#[inline] #[inline]
pub fn with_visible(mut self, visible: bool) -> Self { pub fn with_visible(mut self, visible: bool) -> Self {
self.window.visible = visible; self.window.visible = visible;
@ -301,8 +283,6 @@ impl WindowBuilder {
/// The default is `true`. /// The default is `true`.
/// ///
/// See [`Window::set_decorations`] for details. /// See [`Window::set_decorations`] for details.
///
/// [`Window::set_decorations`]: crate::window::Window::set_decorations
#[inline] #[inline]
pub fn with_decorations(mut self, decorations: bool) -> Self { pub fn with_decorations(mut self, decorations: bool) -> Self {
self.window.decorations = decorations; self.window.decorations = decorations;
@ -314,8 +294,6 @@ impl WindowBuilder {
/// The default is `false`. /// The default is `false`.
/// ///
/// See [`Window::set_always_on_top`] for details. /// See [`Window::set_always_on_top`] for details.
///
/// [`Window::set_always_on_top`]: crate::window::Window::set_always_on_top
#[inline] #[inline]
pub fn with_always_on_top(mut self, always_on_top: bool) -> Self { pub fn with_always_on_top(mut self, always_on_top: bool) -> Self {
self.window.always_on_top = always_on_top; self.window.always_on_top = always_on_top;
@ -327,8 +305,6 @@ impl WindowBuilder {
/// The default is `None`. /// The default is `None`.
/// ///
/// See [`Window::set_window_icon`] for details. /// See [`Window::set_window_icon`] for details.
///
/// [`Window::set_window_icon`]: crate::window::Window::set_window_icon
#[inline] #[inline]
pub fn with_window_icon(mut self, window_icon: Option<Icon>) -> Self { pub fn with_window_icon(mut self, window_icon: Option<Icon>) -> Self {
self.window.window_icon = window_icon; self.window.window_icon = window_icon;
@ -341,7 +317,7 @@ impl WindowBuilder {
/// ///
/// Platform-specific behavior: /// Platform-specific behavior:
/// - **Web**: The window is created but not inserted into the web page automatically. Please /// - **Web**: The window is created but not inserted into the web page automatically. Please
/// see the web platform module for more information. /// see the web platform module for more information.
#[inline] #[inline]
pub fn build<T: 'static>( pub fn build<T: 'static>(
self, self,
@ -367,9 +343,9 @@ impl Window {
/// ///
/// Platform-specific behavior: /// Platform-specific behavior:
/// - **Web**: The window is created but not inserted into the web page automatically. Please /// - **Web**: The window is created but not inserted into the web page automatically. Please
/// see the web platform module for more information. /// see the web platform module for more information.
/// ///
/// [`WindowBuilder::new().build(event_loop)`]: crate::window::WindowBuilder::build /// [`WindowBuilder::new().build(event_loop)`]: WindowBuilder::build
#[inline] #[inline]
pub fn new<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> { pub fn new<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> {
let builder = WindowBuilder::new(); let builder = WindowBuilder::new();
@ -387,7 +363,7 @@ impl Window {
/// See the [`dpi`](crate::dpi) module for more information. /// See the [`dpi`](crate::dpi) module for more information.
/// ///
/// Note that this value can change depending on user action (for example if the window is /// 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 /// 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. /// the most robust way to track the DPI you need to use to draw.
/// ///
/// ## Platform-specific /// ## Platform-specific
@ -397,19 +373,20 @@ impl Window {
/// - **iOS:** Can only be called on the main thread. Returns the underlying `UIView`'s /// - **iOS:** Can only be called on the main thread. Returns the underlying `UIView`'s
/// [`contentScaleFactor`]. /// [`contentScaleFactor`].
/// ///
/// [`WindowEvent::ScaleFactorChanged`]: crate::event::WindowEvent::ScaleFactorChanged
/// [`contentScaleFactor`]: https://developer.apple.com/documentation/uikit/uiview/1622657-contentscalefactor?language=objc /// [`contentScaleFactor`]: https://developer.apple.com/documentation/uikit/uiview/1622657-contentscalefactor?language=objc
#[inline] #[inline]
pub fn scale_factor(&self) -> f64 { pub fn scale_factor(&self) -> f64 {
self.window.scale_factor() self.window.scale_factor()
} }
/// Emits a `WindowEvent::RedrawRequested` event in the associated event loop after all OS /// Emits a [`Event::RedrawRequested`] event in the associated event loop after all OS
/// events have been processed by the event loop. /// events have been processed by the event loop.
/// ///
/// This is the **strongly encouraged** method of redrawing windows, as it can integrate with /// This is the **strongly encouraged** method of redrawing windows, as it can integrate with
/// OS-requested redraws (e.g. when a window gets resized). /// OS-requested redraws (e.g. when a window gets resized).
/// ///
/// This function can cause `RedrawRequested` events to be emitted after `Event::MainEventsCleared` /// This function can cause `RedrawRequested` events to be emitted after [`Event::MainEventsCleared`]
/// but before `Event::NewEvents` if called in the following circumstances: /// but before `Event::NewEvents` if called in the following circumstances:
/// * While processing `MainEventsCleared`. /// * While processing `MainEventsCleared`.
/// * While processing a `RedrawRequested` event that was sent during `MainEventsCleared` or any /// * While processing a `RedrawRequested` event that was sent during `MainEventsCleared` or any
@ -419,6 +396,9 @@ impl Window {
/// ///
/// - **iOS:** Can only be called on the main thread. /// - **iOS:** Can only be called on the main thread.
/// - **Android:** Subsequent calls after `MainEventsCleared` are not handled. /// - **Android:** Subsequent calls after `MainEventsCleared` are not handled.
///
/// [`Event::RedrawRequested`]: crate::event::Event::RedrawRequested
/// [`Event::MainEventsCleared`]: crate::event::Event::MainEventsCleared
#[inline] #[inline]
pub fn request_redraw(&self) { pub fn request_redraw(&self) {
self.window.request_redraw() self.window.request_redraw()
@ -430,14 +410,14 @@ impl Window {
/// Returns the position of the top-left hand corner of the window's client area relative to the /// 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. /// top-left hand corner of the desktop.
/// ///
/// The same conditions that apply to `outer_position` apply to this method. /// The same conditions that apply to [`Window::outer_position`] apply to this method.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **iOS:** Can only be called on the main thread. Returns the top left coordinates of the /// - **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. /// window's [safe area] in the screen space coordinate system.
/// - **Web:** Returns the top-left coordinates relative to the viewport. _Note: this returns the /// - **Web:** Returns the top-left coordinates relative to the viewport. _Note: this returns the
/// same value as `outer_position`._ /// same value as [`Window::outer_position`]._
/// - **Android / Wayland:** Always returns [`NotSupportedError`]. /// - **Android / Wayland:** Always returns [`NotSupportedError`].
/// ///
/// [safe area]: https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc /// [safe area]: https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc
@ -447,14 +427,14 @@ impl Window {
} }
/// Returns the position of the top-left hand corner of the window relative to the /// Returns the position of the top-left hand corner of the window relative to the
/// top-left hand corner of the desktop. /// top-left hand corner of the desktop.
/// ///
/// Note that the top-left hand corner of the desktop is not necessarily the same as /// 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 /// 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. /// 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 /// The coordinates can be negative if the top-left hand corner of the window is outside
/// of the visible screen region. /// of the visible screen region.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
@ -469,8 +449,8 @@ impl Window {
/// Modifies the position of the window. /// Modifies the position of the window.
/// ///
/// See `outer_position` for more information about the coordinates. This automatically un-maximizes the /// See [`Window::outer_position`] for more information about the coordinates.
/// window if it's maximized. /// This automatically un-maximizes the window if it's maximized.
/// ///
/// ```no_run /// ```no_run
/// # use winit::dpi::{LogicalPosition, PhysicalPosition}; /// # use winit::dpi::{LogicalPosition, PhysicalPosition};
@ -514,8 +494,8 @@ impl Window {
/// Modifies the inner size of the window. /// Modifies the inner size of the window.
/// ///
/// See `inner_size` for more information about the values. This automatically un-maximizes the /// See [`Window::inner_size`] for more information about the values.
/// window if it's maximized. /// This automatically un-maximizes the window if it's maximized.
/// ///
/// ```no_run /// ```no_run
/// # use winit::dpi::{LogicalSize, PhysicalSize}; /// # use winit::dpi::{LogicalSize, PhysicalSize};
@ -542,14 +522,14 @@ impl Window {
/// Returns the physical size of the entire window. /// 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), /// These dimensions include the title bar and borders. If you don't want that (and you usually don't),
/// use `inner_size` instead. /// use [`Window::inner_size`] instead.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **iOS:** Can only be called on the main thread. Returns the `PhysicalSize` of the window in /// - **iOS:** Can only be called on the main thread. Returns the [`PhysicalSize`] of the window in
/// screen space coordinates. /// screen space coordinates.
/// - **Web:** Returns the size of the canvas element. _Note: this returns the same value as /// - **Web:** Returns the size of the canvas element. _Note: this returns the same value as
/// `inner_size`._ /// [`Window::inner_size`]._
#[inline] #[inline]
pub fn outer_size(&self) -> PhysicalSize<u32> { pub fn outer_size(&self) -> PhysicalSize<u32> {
self.window.outer_size() self.window.outer_size()
@ -617,6 +597,7 @@ impl Window {
/// Modifies the window's visibility. /// Modifies the window's visibility.
/// ///
/// If `false`, this will hide the window. If `true`, this will show the window. /// If `false`, this will hide the window. If `true`, this will show the window.
///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **Android / Wayland / Web:** Unsupported. /// - **Android / Wayland / Web:** Unsupported.
@ -628,7 +609,7 @@ impl Window {
/// Gets the window's current vibility state. /// Gets the window's current vibility state.
/// ///
/// If `None` means it couldn't be determined so it is not recommended to use this to drive your rendering backend. /// `None` means it couldn't be determined, so it is not recommended to use this to drive your rendering backend.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
@ -641,9 +622,9 @@ impl Window {
/// Sets whether the window is resizable or not. /// Sets whether the window is resizable or not.
/// ///
/// Note that making the window unresizable doesn't exempt you from handling `Resized`, as that /// 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 /// 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]`. /// window could still be resized by calling [`Window::set_inner_size`].
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
@ -654,6 +635,8 @@ impl Window {
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **iOS / Android / Web:** Unsupported. /// - **iOS / Android / Web:** Unsupported.
///
/// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
#[inline] #[inline]
pub fn set_resizable(&self, resizable: bool) { pub fn set_resizable(&self, resizable: bool) {
self.window.set_resizable(resizable) self.window.set_resizable(resizable)
@ -705,18 +688,18 @@ impl Window {
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **macOS:** `Fullscreen::Exclusive` provides true exclusive mode with a /// - **macOS:** [`Fullscreen::Exclusive`] provides true exclusive mode with a
/// video mode change. *Caveat!* macOS doesn't provide task switching (or /// video mode change. *Caveat!* macOS doesn't provide task switching (or
/// spaces!) while in exclusive fullscreen mode. This mode should be used /// spaces!) while in exclusive fullscreen mode. This mode should be used
/// when a video mode change is desired, but for a better user experience, /// when a video mode change is desired, but for a better user experience,
/// borderless fullscreen might be preferred. /// borderless fullscreen might be preferred.
/// ///
/// `Fullscreen::Borderless` provides a borderless fullscreen window on a /// [`Fullscreen::Borderless`] provides a borderless fullscreen window on a
/// separate space. This is the idiomatic way for fullscreen games to work /// separate space. This is the idiomatic way for fullscreen games to work
/// on macOS. See `WindowExtMacOs::set_simple_fullscreen` if /// on macOS. See `WindowExtMacOs::set_simple_fullscreen` if
/// separate spaces are not preferred. /// separate spaces are not preferred.
/// ///
/// The dock and the menu bar are always disabled in fullscreen mode. /// The dock and the menu bar are disabled in exclusive fullscreen mode.
/// - **iOS:** Can only be called on the main thread. /// - **iOS:** Can only be called on the main thread.
/// - **Wayland:** Does not support exclusive fullscreen mode and will no-op a request. /// - **Wayland:** Does not support exclusive fullscreen mode and will no-op a request.
/// - **Windows:** Screen saver is disabled in fullscreen mode. /// - **Windows:** Screen saver is disabled in fullscreen mode.
@ -743,8 +726,6 @@ impl Window {
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **iOS / Android / Web:** Unsupported. /// - **iOS / Android / Web:** Unsupported.
///
/// [`setPrefersStatusBarHidden`]: https://developer.apple.com/documentation/uikit/uiviewcontroller/1621440-prefersstatusbarhidden?language=objc
#[inline] #[inline]
pub fn set_decorations(&self, decorations: bool) { pub fn set_decorations(&self, decorations: bool) {
self.window.set_decorations(decorations) self.window.set_decorations(decorations)
@ -771,18 +752,20 @@ impl Window {
self.window.set_always_on_top(always_on_top) self.window.set_always_on_top(always_on_top)
} }
/// Sets the window icon. On Windows and X11, this is typically the small icon in the top-left /// Sets the window icon.
///
/// On Windows and X11, this is typically the small icon in the top-left
/// corner of the titlebar. /// corner of the titlebar.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **iOS / Android / Web / Wayland / macOS:** Unsupported. /// - **iOS / Android / Web / Wayland / macOS:** Unsupported.
/// ///
/// On Windows, this sets `ICON_SMALL`. The base size for a window icon is 16x16, but it's /// - **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. /// 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 /// - **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. /// said, it's usually in the same ballpark as on Windows.
#[inline] #[inline]
pub fn set_window_icon(&self, window_icon: Option<Icon>) { pub fn set_window_icon(&self, window_icon: Option<Icon>) {
self.window.set_window_icon(window_icon) self.window.set_window_icon(window_icon)
@ -865,7 +848,7 @@ impl Window {
/// Requests user attention to the window, this has no effect if the application /// 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, /// is already focused. How requesting for user attention manifests is platform dependent,
/// see `UserAttentionType` for details. /// see [`UserAttentionType`] for details.
/// ///
/// Providing `None` will unset the request for user attention. Unsetting the request for /// 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. /// user attention might not be done automatically by the WM when the window receives input.
@ -994,11 +977,13 @@ impl Window {
/// Returns the list of all the monitors available on the system. /// Returns the list of all the monitors available on the system.
/// ///
/// This is the same as `EventLoopWindowTarget::available_monitors`, and is provided for convenience. /// This is the same as [`EventLoopWindowTarget::available_monitors`], and is provided for convenience.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// **iOS:** Can only be called on the main thread. /// **iOS:** Can only be called on the main thread.
///
/// [`EventLoopWindowTarget::available_monitors`]: crate::event_loop::EventLoopWindowTarget::available_monitors
#[inline] #[inline]
pub fn available_monitors(&self) -> impl Iterator<Item = MonitorHandle> { pub fn available_monitors(&self) -> impl Iterator<Item = MonitorHandle> {
self.window self.window
@ -1011,12 +996,14 @@ impl Window {
/// ///
/// Returns `None` if it can't identify any monitor as a primary one. /// 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. /// This is the same as [`EventLoopWindowTarget::primary_monitor`], and is provided for convenience.
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
/// **iOS:** Can only be called on the main thread. /// **iOS:** Can only be called on the main thread.
/// **Wayland:** Always returns `None`. /// **Wayland:** Always returns `None`.
///
/// [`EventLoopWindowTarget::primary_monitor`]: crate::event_loop::EventLoopWindowTarget::primary_monitor
#[inline] #[inline]
pub fn primary_monitor(&self) -> Option<MonitorHandle> { pub fn primary_monitor(&self) -> Option<MonitorHandle> {
self.window.primary_monitor() self.window.primary_monitor()
@ -1024,7 +1011,7 @@ impl Window {
} }
unsafe impl raw_window_handle::HasRawWindowHandle for Window { unsafe impl raw_window_handle::HasRawWindowHandle for Window {
/// Returns a `raw_window_handle::RawWindowHandle` for the Window /// Returns a [`raw_window_handle::RawWindowHandle`] for the Window
/// ///
/// ## Platform-specific /// ## Platform-specific
/// ///
@ -1117,7 +1104,10 @@ pub enum Theme {
/// ## Platform-specific /// ## Platform-specific
/// ///
/// - **X11:** Sets the WM's `XUrgencyHint`. No distinction between `Critical` and `Informational`. /// - **X11:** Sets the WM's `XUrgencyHint`. No distinction between [`Critical`] and [`Informational`].
///
/// [`Critical`]: Self::Critical
/// [`Informational`]: Self::Informational
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UserAttentionType { pub enum UserAttentionType {
/// ## Platform-specific /// ## Platform-specific