diff --git a/README.md b/README.md index 88e44f80..0caad194 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,14 @@ Winit provides the following features, which can be enabled in your `Cargo.toml` ### 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 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` + +#### 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 diff --git a/src/dpi.rs b/src/dpi.rs index be6d8177..bf234007 100644 --- a/src/dpi.rs +++ b/src/dpi.rs @@ -35,8 +35,9 @@ //! //! ### Position and Size types //! -//! Winit's `Physical(Position|Size)` types correspond with the actual pixels on the device, and the -//! `Logical(Position|Size)` types correspond to the physical pixels divided by the scale factor. +//! Winit's [`PhysicalPosition`] / [`PhysicalSize`] types correspond with the actual pixels on the +//! 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 //! coordinates as input, allowing you to use the most convenient coordinate system for your //! particular application. @@ -46,19 +47,18 @@ //! 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 //! 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 //! int, although rounding lessens the problem. //! //! ### Events //! -//! Winit will dispatch a [`ScaleFactorChanged`](crate::event::WindowEvent::ScaleFactorChanged) -//! event whenever a window's scale factor has changed. This can happen if the user drags their -//! window from a standard-resolution monitor to a high-DPI monitor, or if the user changes their -//! DPI settings. This gives you a chance to rescale your application's UI elements and adjust how -//! the platform changes the window's size to reflect the new scale factor. If a window hasn't -//! received a [`ScaleFactorChanged`](crate::event::WindowEvent::ScaleFactorChanged) event, -//! then its scale factor can be found by calling [window.scale_factor()]. +//! Winit will dispatch a [`ScaleFactorChanged`] event whenever a window's scale factor has changed. +//! This can happen if the user drags their window from a standard-resolution monitor to a high-DPI +//! monitor, or if the user changes their DPI settings. This gives you a chance to rescale your +//! application's UI elements and adjust how the platform changes the window's size to reflect the new +//! scale factor. If a window hasn't received a [`ScaleFactorChanged`] event, then its scale factor +//! can be found by calling [`window.scale_factor()`]. //! //! ## 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 //! both the screen scaling and the browser zoom level and can go below `1.0`. //! +//! //! [points]: https://en.wikipedia.org/wiki/Point_(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 //! [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/ diff --git a/src/event.rs b/src/event.rs index 65e556a2..29e860e6 100644 --- a/src/event.rs +++ b/src/event.rs @@ -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. //! //! 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 //! let mut control_flow = ControlFlow::Poll; @@ -29,10 +29,11 @@ //! 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. //! -//! [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 std::path::PathBuf; @@ -90,7 +91,7 @@ pub enum Event<'a, T: 'static> { /// can render here unconditionally for simplicity. 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: /// - 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 /// something changes, like most non-game GUIs. + /// + /// [`MainEventsCleared`]: Self::MainEventsCleared 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 /// immediately after `MainEventsCleared`. /// /// This event is useful for doing any cleanup or bookkeeping work after all the rendering /// tasks have been completed. + /// + /// [`RedrawRequested`]: Self::RedrawRequested RedrawEventsCleared, /// 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. #[derive(Debug, Clone, Copy, PartialEq, Eq)] 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 /// guaranteed to be equal to or after the requested resume time. + /// + /// [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil ResumeTimeReached { start: 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 - /// `ControlFlow::Poll`. + /// [`ControlFlow::Poll`]. + /// + /// [`ControlFlow::Poll`]: crate::event_loop::ControlFlow::Poll Poll, /// 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); impl DeviceId { - /// Returns a dummy `DeviceId`, useful for unit testing. + /// Returns a dummy id, useful for unit testing. /// /// # Safety /// @@ -579,7 +588,7 @@ pub enum DeviceEvent { /// 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 { /// (x, y) change in position in unspecified units. /// @@ -592,7 +601,7 @@ pub enum DeviceEvent { 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 /// device then this will be reported alongside the MouseMotion event. Motion { @@ -673,7 +682,6 @@ pub struct KeyboardInput { /// // Press space key /// Ime::Commit("啊不") /// ``` -/// #[derive(Debug, Clone, PartialEq, Eq, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub enum Ime { @@ -718,18 +726,18 @@ pub enum TouchPhase { /// Represents a touch event /// -/// Every time the user touches the screen, a new `Start` event with an unique -/// identifier for the finger is generated. When the finger is lifted, an `End` +/// 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 [`TouchPhase::Ended`] /// 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. /// -/// The finger id may be reused by the system after an `End` event. The user -/// should assume that a new `Start` event received with the same id has nothing +/// The finger id may be reused by the system after an `Ended` event. The user +/// 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. /// -/// 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 /// device against their face. #[derive(Debug, Clone, Copy, PartialEq)] @@ -783,8 +791,9 @@ pub enum Force { impl Force { /// Returns the force normalized to the range between 0.0 and 1.0 inclusive. + /// /// 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. pub fn normalized(&self) -> f64 { match self { @@ -845,7 +854,7 @@ pub enum MouseScrollDelta { /// Amount in pixels to scroll in the horizontal and /// 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 /// platform. /// diff --git a/src/event_loop.rs b/src/event_loop.rs index b768b643..92b807fd 100644 --- a/src/event_loop.rs +++ b/src/event_loop.rs @@ -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] -//! to acquire an [`EventLoopProxy`][event_loop_proxy] and call its [`send_event`][send_event] method. +//! If you want to send custom events to the event loop, use +//! [`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 //! 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 std::marker::PhantomData; 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 /// 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 /// 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 -/// 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 -/// `EventLoopProxy` allows you to wake up an `EventLoop` from another thread. +/// 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 +/// [`Window`] created from this _can_ be sent to an other thread, and the +/// [`EventLoopProxy`] allows you to wake up an `EventLoop` from another thread. /// +/// [`Window`]: crate::window::Window pub struct EventLoop { pub(crate) event_loop: platform_impl::EventLoop, 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 -/// your callback. `EventLoop` will coerce into this type (`impl Deref for +/// your callback. [`EventLoop`] will coerce into this type (`impl Deref for /// EventLoop`), so functions that take this as a parameter can also take /// `&EventLoop`. pub struct EventLoopWindowTarget { @@ -77,11 +76,11 @@ impl EventLoopBuilder { /// 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 /// 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 - /// 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. /// /// Calling this function will result in display backend initialisation. @@ -92,6 +91,8 @@ impl EventLoopBuilder { /// `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, /// will fall back on X11. If this variable is set with any other value, winit will panic. + /// + /// [`platform`]: crate::platform #[inline] pub fn build(&mut self) -> EventLoop { // Certain platforms accept a mutable reference in their API. @@ -115,18 +116,21 @@ impl fmt::Debug for EventLoopWindowTarget { } } -/// 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] -/// is emitted. Defaults to `Poll`. +/// Indicates the desired behavior of the event loop after [`Event::RedrawEventsCleared`] is emitted. +/// +/// Defaults to [`Poll`]. /// /// ## 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)] pub enum ControlFlow { /// 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. /// /// 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. + /// + /// [`Poll`]: Self::Poll 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 /// 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 /// [`std::process::exit`]. /// + /// [`LoopDestroyed`]: Event::LoopDestroyed /// [`Exit`]: ControlFlow::Exit ExitWithCode(i32), } @@ -168,41 +175,41 @@ pub enum ControlFlow { impl ControlFlow { /// Alias for [`ExitWithCode`]`(0)`. /// - /// [`ExitWithCode`]: ControlFlow::ExitWithCode + /// [`ExitWithCode`]: Self::ExitWithCode #[allow(non_upper_case_globals)] pub const Exit: Self = Self::ExitWithCode(0); /// Sets this to [`Poll`]. /// - /// [`Poll`]: ControlFlow::Poll + /// [`Poll`]: Self::Poll pub fn set_poll(&mut self) { *self = Self::Poll; } /// Sets this to [`Wait`]. /// - /// [`Wait`]: ControlFlow::Wait + /// [`Wait`]: Self::Wait pub fn set_wait(&mut self) { *self = Self::Wait; } /// Sets this to [`WaitUntil`]`(instant)`. /// - /// [`WaitUntil`]: ControlFlow::WaitUntil + /// [`WaitUntil`]: Self::WaitUntil pub fn set_wait_until(&mut self, instant: Instant) { *self = Self::WaitUntil(instant); } /// Sets this to [`ExitWithCode`]`(code)`. /// - /// [`ExitWithCode`]: ControlFlow::ExitWithCode + /// [`ExitWithCode`]: Self::ExitWithCode pub fn set_exit_with_code(&mut self, code: i32) { *self = Self::ExitWithCode(code); } /// Sets this to [`Exit`]. /// - /// [`Exit`]: ControlFlow::Exit + /// [`Exit`]: Self::Exit pub fn set_exit(&mut self) { *self = Self::Exit; } @@ -210,13 +217,15 @@ impl ControlFlow { impl Default for ControlFlow { #[inline(always)] - fn default() -> ControlFlow { - ControlFlow::Poll + fn default() -> Self { + Self::Poll } } impl EventLoop<()> { - /// Alias for `EventLoopBuilder::new().build()`. + /// Alias for [`EventLoopBuilder::new().build()`]. + /// + /// [`EventLoopBuilder::new().build()`]: EventLoopBuilder::build #[inline] pub fn new() -> EventLoop<()> { EventLoopBuilder::new().build() @@ -258,7 +267,7 @@ impl EventLoop { 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 { EventLoopProxy { event_loop_proxy: self.event_loop.create_proxy(), @@ -318,7 +327,7 @@ impl EventLoopWindowTarget { } } -/// Used to send custom events to `EventLoop`. +/// Used to send custom events to [`EventLoop`]. pub struct EventLoopProxy { event_loop_proxy: platform_impl::EventLoopProxy, } @@ -332,11 +341,13 @@ impl Clone for EventLoopProxy { } impl EventLoopProxy { - /// 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 /// 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> { self.event_loop_proxy.send_event(event) } @@ -348,8 +359,10 @@ impl fmt::Debug for EventLoopProxy { } } -/// 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`. +/// The error that is returned when an [`EventLoopProxy`] attempts to wake up an [`EventLoop`] that +/// no longer exists. +/// +/// Contains the original event given to [`EventLoopProxy::send_event`]. #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] pub struct EventLoopClosed(pub T); diff --git a/src/icon.rs b/src/icon.rs index 418ea03a..982e5f5d 100644 --- a/src/icon.rs +++ b/src/icon.rs @@ -13,7 +13,7 @@ pub(crate) struct Pixel { pub(crate) const PIXEL_SIZE: usize = mem::size_of::(); #[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 { /// Produced when the length of the `rgba` argument isn't divisible by 4, thus `rgba` can't be /// safely interpreted as 32bpp RGBA pixels. @@ -73,10 +73,6 @@ mod constructors { use super::*; 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, width: u32, height: u32) -> Result { if rgba.len() % PIXEL_SIZE != 0 { return Err(BadIcon::ByteCountNotDivisibleBy4 { @@ -123,7 +119,7 @@ impl fmt::Debug for 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 /// `rgba.len() / 4`. Otherwise, this will return a `BadIcon` error. diff --git a/src/monitor.rs b/src/monitor.rs index 5cf680ff..7611f94b 100644 --- a/src/monitor.rs +++ b/src/monitor.rs @@ -1,14 +1,10 @@ //! 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] -//! type. This is retrieved from one of the following methods, which return an iterator of -//! [`MonitorHandle`][monitor_handle]: -//! - [`EventLoopWindowTarget::available_monitors`][loop_get] -//! - [`Window::available_monitors`][window_get]. -//! -//! [monitor_handle]: crate::monitor::MonitorHandle -//! [loop_get]: crate::event_loop::EventLoopWindowTarget::available_monitors -//! [window_get]: crate::window::Window::available_monitors +//! If you want to get basic information about a monitor, you can use the +//! [`MonitorHandle`] type. This is retrieved from one of the following +//! methods, which return an iterator of [`MonitorHandle`]: +//! - [`EventLoopWindowTarget::available_monitors`](crate::event_loop::EventLoopWindowTarget::available_monitors). +//! - [`Window::available_monitors`](crate::window::Window::available_monitors). use crate::{ dpi::{PhysicalPosition, PhysicalSize}, platform_impl, @@ -16,10 +12,7 @@ use crate::{ /// Describes a fullscreen video mode of a monitor. /// -/// Can be acquired with: -/// - [`MonitorHandle::video_modes`][monitor_get]. -/// -/// [monitor_get]: crate::monitor::MonitorHandle::video_modes +/// Can be acquired with [`MonitorHandle::video_modes`]. #[derive(Clone, PartialEq, Eq, Hash)] pub struct VideoMode { pub(crate) video_mode: platform_impl::VideoMode, diff --git a/src/platform/android.rs b/src/platform/android.rs index b4e99176..af15f3ef 100644 --- a/src/platform/android.rs +++ b/src/platform/android.rs @@ -7,15 +7,15 @@ use crate::{ use ndk::configuration::Configuration; 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 {} impl EventLoopExtAndroid for EventLoop {} -/// Additional methods on `EventLoopWindowTarget` that are specific to Android. +/// Additional methods on [`EventLoopWindowTarget`] that are specific to Android. pub trait EventLoopWindowTargetExtAndroid {} -/// Additional methods on `Window` that are specific to Android. +/// Additional methods on [`Window`] that are specific to Android. pub trait WindowExtAndroid { fn content_rect(&self) -> Rect; @@ -34,7 +34,7 @@ impl WindowExtAndroid for Window { impl EventLoopWindowTargetExtAndroid for EventLoopWindowTarget {} -/// Additional methods on `WindowBuilder` that are specific to Android. +/// Additional methods on [`WindowBuilder`] that are specific to Android. pub trait WindowBuilderExtAndroid {} impl WindowBuilderExtAndroid for WindowBuilder {} diff --git a/src/platform/macos.rs b/src/platform/macos.rs index 1ddab448..10997e52 100644 --- a/src/platform/macos.rs +++ b/src/platform/macos.rs @@ -9,16 +9,16 @@ use crate::{ window::{Window, WindowBuilder}, }; -/// Additional methods on `Window` that are specific to MacOS. +/// Additional methods on [`Window`] that are specific to MacOS. pub trait WindowExtMacOS { /// 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; /// 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; /// 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 -/// on the base `WindowBuilder`: -/// -/// - `with_titlebar_transparent` -/// - `with_title_hidden` -/// - `with_titlebar_hidden` -/// - `with_titlebar_buttons_hidden` -/// - `with_fullsize_content_view` +/// **Note:** Properties dealing with the titlebar will be overwritten by the [`WindowBuilder::with_decorations`] method: +/// - `with_titlebar_transparent` +/// - `with_title_hidden` +/// - `with_titlebar_hidden` +/// - `with_titlebar_buttons_hidden` +/// - `with_fullsize_content_view` pub trait WindowBuilderExtMacOS { /// 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) @@ -238,7 +236,7 @@ impl EventLoopBuilderExtMacOS for EventLoopBuilder { } } -/// Additional methods on `MonitorHandle` that are specific to MacOS. +/// Additional methods on [`MonitorHandle`] that are specific to MacOS. pub trait MonitorHandleExtMacOS { /// Returns the identifier of the monitor for Cocoa. 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 { /// Hide the entire application. In most applications this is typically triggered with Command-H. fn hide_application(&self); diff --git a/src/platform/mod.rs b/src/platform/mod.rs index 1ee5fce2..dde4c079 100644 --- a/src/platform/mod.rs +++ b/src/platform/mod.rs @@ -19,7 +19,7 @@ pub mod android; pub mod ios; pub mod macos; pub mod unix; +pub mod web; pub mod windows; pub mod run_return; -pub mod web; diff --git a/src/platform/run_return.rs b/src/platform/run_return.rs index 1c2fa623..5c254615 100644 --- a/src/platform/run_return.rs +++ b/src/platform/run_return.rs @@ -14,17 +14,18 @@ use crate::{ 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 { - /// 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; /// Initializes the `winit` event loop. /// - /// Unlike `run`, this function accepts non-`'static` (i.e. non-`move`) closures and returns - /// control flow to the caller when `control_flow` is set to `ControlFlow::Exit`. + /// Unlike [`EventLoop::run`], this function accepts non-`'static` (i.e. non-`move`) closures + /// and returns control flow to the caller when `control_flow` is set to [`ControlFlow::Exit`]. /// /// # Caveats + /// /// 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 /// window is getting resized, resulting in all application logic outside of the diff --git a/src/platform/unix.rs b/src/platform/unix.rs index 81b06ad0..ae0c9942 100644 --- a/src/platform/unix.rs +++ b/src/platform/unix.rs @@ -35,13 +35,13 @@ pub use crate::platform_impl::{x11::util::WindowType as XWindowType, XNotSupport #[cfg(feature = "wayland")] 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 { - /// True if the `EventLoopWindowTarget` uses Wayland. + /// True if the [`EventLoopWindowTarget`] uses Wayland. #[cfg(feature = "wayland")] fn is_wayland(&self) -> bool; - /// True if the `EventLoopWindowTarget` uses X11. + /// True if the [`EventLoopWindowTarget`] uses X11. #[cfg(feature = "x11")] fn is_x11(&self) -> bool; @@ -50,11 +50,13 @@ pub trait EventLoopWindowTargetExtUnix { fn xlib_xconnection(&self) -> Option>; /// 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")] fn wayland_display(&self) -> Option<*mut raw::c_void>; } @@ -134,9 +136,9 @@ impl EventLoopBuilderExtUnix for EventLoopBuilder { } } -/// Additional methods on `Window` that are specific to Unix. +/// Additional methods on [`Window`] that are specific to Unix. 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). #[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). /// - /// The pointer will become invalid when the glutin `Window` is destroyed. + /// The pointer will become invalid when the [`Window`] is destroyed. #[cfg(feature = "x11")] 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). /// - /// The pointer will become invalid when the glutin `Window` is destroyed. + /// The pointer will become invalid when the [`Window`] is destroyed. #[cfg(feature = "x11")] 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). /// - /// The pointer will become invalid when the glutin `Window` is destroyed. + /// The pointer will become invalid when the [`Window`] is destroyed. #[cfg(feature = "wayland")] 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). /// - /// The pointer will become invalid when the glutin `Window` is destroyed. + /// The pointer will become invalid when the [`Window`] is destroyed. #[cfg(feature = "wayland")] 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 /// wayland backend, and is no longer relevant. /// - /// Always return true. + /// Always return `true`. #[deprecated] 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 { #[cfg(feature = "x11")] fn with_x11_visual(self, visual_infos: *const T) -> Self; diff --git a/src/platform/web.rs b/src/platform/web.rs index 210f87b9..36c2a539 100644 --- a/src/platform/web.rs +++ b/src/platform/web.rs @@ -1,8 +1,8 @@ #![cfg(target_arch = "wasm32")] //! 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 -//! to retrieve the canvas from the Window. Alternatively, use the `WindowBuilderExtWebSys` 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 provide your own canvas. use crate::window::WindowBuilder; diff --git a/src/window.rs b/src/window.rs index 2f8cbbf5..1a1ded6f 100644 --- a/src/window.rs +++ b/src/window.rs @@ -1,4 +1,4 @@ -//! The `Window` struct and associated types. +//! The [`Window`] struct and associated types. use std::fmt; use crate::{ @@ -61,7 +61,7 @@ impl Drop for 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 /// 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); impl WindowId { - /// Returns a dummy `WindowId`, useful for unit testing. + /// Returns a dummy id, useful for unit testing. /// /// # Safety /// /// 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. - /// 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.** pub const unsafe fn dummy() -> Self { @@ -142,7 +142,7 @@ impl Default for WindowAttributes { } impl WindowBuilder { - /// Initializes a new `WindowBuilder` with default values. + /// Initializes a new builder with default values. #[inline] pub fn new() -> Self { Default::default() @@ -153,8 +153,6 @@ impl WindowBuilder { /// If this is not set, some platform-specific dimensions will be used. /// /// See [`Window::set_inner_size`] for details. - /// - /// [`Window::set_inner_size`]: crate::window::Window::set_inner_size #[inline] pub fn with_inner_size>(mut self, size: S) -> Self { self.window.inner_size = Some(size.into()); @@ -167,8 +165,6 @@ impl WindowBuilder { /// from reserved). /// /// See [`Window::set_min_inner_size`] for details. - /// - /// [`Window::set_min_inner_size`]: crate::window::Window::set_min_inner_size #[inline] pub fn with_min_inner_size>(mut self, min_size: S) -> Self { self.window.min_inner_size = Some(min_size.into()); @@ -181,8 +177,6 @@ impl WindowBuilder { /// the primary monitor's dimensions by the platform. /// /// See [`Window::set_max_inner_size`] for details. - /// - /// [`Window::set_max_inner_size`]: crate::window::Window::set_max_inner_size #[inline] pub fn with_max_inner_size>(mut self, max_size: S) -> Self { 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" /// position. /// - **Others**: Ignored. - /// - /// [`Window::set_outer_position`]: crate::window::Window::set_outer_position #[inline] pub fn with_position>(mut self, position: P) -> Self { self.window.position = Some(position.into()); @@ -224,8 +216,6 @@ impl WindowBuilder { /// The default is `true`. /// /// See [`Window::set_resizable`] for details. - /// - /// [`Window::set_resizable`]: crate::window::Window::set_resizable #[inline] pub fn with_resizable(mut self, resizable: bool) -> Self { self.window.resizable = resizable; @@ -237,8 +227,6 @@ impl WindowBuilder { /// The default is `"winit window"`. /// /// See [`Window::set_title`] for details. - /// - /// [`Window::set_title`]: crate::window::Window::set_title #[inline] pub fn with_title>(mut self, title: T) -> Self { self.window.title = title.into(); @@ -250,8 +238,6 @@ impl WindowBuilder { /// The default is `None`. /// /// See [`Window::set_fullscreen`] for details. - /// - /// [`Window::set_fullscreen`]: crate::window::Window::set_fullscreen #[inline] pub fn with_fullscreen(mut self, fullscreen: Option) -> Self { self.window.fullscreen = fullscreen; @@ -263,8 +249,6 @@ impl WindowBuilder { /// The default is `false`. /// /// See [`Window::set_maximized`] for details. - /// - /// [`Window::set_maximized`]: crate::window::Window::set_maximized #[inline] pub fn with_maximized(mut self, maximized: bool) -> Self { self.window.maximized = maximized; @@ -276,8 +260,6 @@ impl WindowBuilder { /// The default is to show the window. /// /// See [`Window::set_visible`] for details. - /// - /// [`Window::set_visible`]: crate::window::Window::set_visible #[inline] pub fn with_visible(mut self, visible: bool) -> Self { self.window.visible = visible; @@ -301,8 +283,6 @@ impl WindowBuilder { /// The default is `true`. /// /// See [`Window::set_decorations`] for details. - /// - /// [`Window::set_decorations`]: crate::window::Window::set_decorations #[inline] pub fn with_decorations(mut self, decorations: bool) -> Self { self.window.decorations = decorations; @@ -314,8 +294,6 @@ impl WindowBuilder { /// The default is `false`. /// /// See [`Window::set_always_on_top`] for details. - /// - /// [`Window::set_always_on_top`]: crate::window::Window::set_always_on_top #[inline] pub fn with_always_on_top(mut self, always_on_top: bool) -> Self { self.window.always_on_top = always_on_top; @@ -327,8 +305,6 @@ impl WindowBuilder { /// The default is `None`. /// /// See [`Window::set_window_icon`] for details. - /// - /// [`Window::set_window_icon`]: crate::window::Window::set_window_icon #[inline] pub fn with_window_icon(mut self, window_icon: Option) -> Self { self.window.window_icon = window_icon; @@ -341,7 +317,7 @@ impl WindowBuilder { /// /// Platform-specific behavior: /// - **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] pub fn build( self, @@ -367,9 +343,9 @@ impl Window { /// /// Platform-specific behavior: /// - **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] pub fn new(event_loop: &EventLoopWindowTarget) -> Result { let builder = WindowBuilder::new(); @@ -387,7 +363,7 @@ impl Window { /// 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 - /// 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. /// /// ## Platform-specific @@ -397,19 +373,20 @@ impl Window { /// - **iOS:** Can only be called on the main thread. Returns the underlying `UIView`'s /// [`contentScaleFactor`]. /// + /// [`WindowEvent::ScaleFactorChanged`]: crate::event::WindowEvent::ScaleFactorChanged /// [`contentScaleFactor`]: https://developer.apple.com/documentation/uikit/uiview/1622657-contentscalefactor?language=objc #[inline] pub fn scale_factor(&self) -> f64 { 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. /// /// 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` + /// 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 during `MainEventsCleared` or any @@ -419,6 +396,9 @@ impl Window { /// /// - **iOS:** Can only be called on the main thread. /// - **Android:** Subsequent calls after `MainEventsCleared` are not handled. + /// + /// [`Event::RedrawRequested`]: crate::event::Event::RedrawRequested + /// [`Event::MainEventsCleared`]: crate::event::Event::MainEventsCleared #[inline] pub fn request_redraw(&self) { 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 /// 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 /// /// - **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 `outer_position`._ + /// same value as [`Window::outer_position`]._ /// - **Android / Wayland:** Always returns [`NotSupportedError`]. /// /// [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 - /// 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 - /// 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 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. + /// of the visible screen region. /// /// ## Platform-specific /// @@ -469,8 +449,8 @@ impl Window { /// Modifies the position of the window. /// - /// See `outer_position` for more information about the coordinates. This automatically un-maximizes the - /// window if it's maximized. + /// See [`Window::outer_position`] for more information about the coordinates. + /// This automatically un-maximizes the window if it's maximized. /// /// ```no_run /// # use winit::dpi::{LogicalPosition, PhysicalPosition}; @@ -514,8 +494,8 @@ impl Window { /// Modifies the inner size of the window. /// - /// See `inner_size` for more information about the values. This automatically un-maximizes the - /// window if it's maximized. + /// See [`Window::inner_size`] for more information about the values. + /// This automatically un-maximizes the window if it's maximized. /// /// ```no_run /// # use winit::dpi::{LogicalSize, PhysicalSize}; @@ -542,14 +522,14 @@ impl 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), - /// use `inner_size` instead. + /// use [`Window::inner_size`] instead. /// /// ## 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. /// - **Web:** Returns the size of the canvas element. _Note: this returns the same value as - /// `inner_size`._ + /// [`Window::inner_size`]._ #[inline] pub fn outer_size(&self) -> PhysicalSize { self.window.outer_size() @@ -617,6 +597,7 @@ impl Window { /// 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. @@ -628,7 +609,7 @@ impl Window { /// 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 /// @@ -641,9 +622,9 @@ impl Window { /// 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 - /// window could still be resized by calling `[Window::set_inner_size]`. + /// window could still be resized by calling [`Window::set_inner_size`]. /// /// ## Platform-specific /// @@ -654,6 +635,8 @@ impl Window { /// ## Platform-specific /// /// - **iOS / Android / Web:** Unsupported. + /// + /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized #[inline] pub fn set_resizable(&self, resizable: bool) { self.window.set_resizable(resizable) @@ -705,18 +688,18 @@ impl Window { /// /// ## 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 /// 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 + /// [`Fullscreen::Borderless`] provides a borderless fullscreen window on a /// separate space. This is the idiomatic way for fullscreen games to work /// on macOS. See `WindowExtMacOs::set_simple_fullscreen` if /// 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. /// - **Wayland:** Does not support exclusive fullscreen mode and will no-op a request. /// - **Windows:** Screen saver is disabled in fullscreen mode. @@ -743,8 +726,6 @@ impl Window { /// ## Platform-specific /// /// - **iOS / Android / Web:** Unsupported. - /// - /// [`setPrefersStatusBarHidden`]: https://developer.apple.com/documentation/uikit/uiviewcontroller/1621440-prefersstatusbarhidden?language=objc #[inline] pub fn set_decorations(&self, decorations: bool) { self.window.set_decorations(decorations) @@ -771,18 +752,20 @@ impl Window { 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. /// /// ## Platform-specific /// /// - **iOS / Android / Web / Wayland / macOS:** Unsupported. /// - /// On Windows, this 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. + /// - **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. + /// - **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. #[inline] pub fn set_window_icon(&self, window_icon: Option) { 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 /// 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 /// 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. /// - /// 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 /// /// **iOS:** Can only be called on the main thread. + /// + /// [`EventLoopWindowTarget::available_monitors`]: crate::event_loop::EventLoopWindowTarget::available_monitors #[inline] pub fn available_monitors(&self) -> impl Iterator { self.window @@ -1011,12 +996,14 @@ impl Window { /// /// 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 /// /// **iOS:** Can only be called on the main thread. /// **Wayland:** Always returns `None`. + /// + /// [`EventLoopWindowTarget::primary_monitor`]: crate::event_loop::EventLoopWindowTarget::primary_monitor #[inline] pub fn primary_monitor(&self) -> Option { self.window.primary_monitor() @@ -1024,7 +1011,7 @@ impl 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 /// @@ -1117,7 +1104,10 @@ pub enum Theme { /// ## 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)] pub enum UserAttentionType { /// ## Platform-specific