leyoda/winit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
Download patch file Download diff file Expand all files Collapse all files

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 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<S: Into<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<S: Into<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<S: Into<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<P: Into<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<T: Into<String>>(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<Fullscreen>) -> 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<Icon>) -> 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<T: 'static>(
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<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> {
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<u32> {
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<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
/// 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<Item = MonitorHandle> {
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<MonitorHandle> {
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