From 35379f305a0b1c6caf8fe9a04fc26e1055d41fd3 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 3 Dec 2024 21:24:57 +0100 Subject: [PATCH] Remove feature description in `FEATURES.md` (#3479) It easily becomes out of date. --- .github/PULL_REQUEST_TEMPLATE.md | 1 - FEATURES.md | 198 ------------------------------- src/event.rs | 34 ++++-- src/monitor.rs | 20 ++-- src/window.rs | 7 +- 5 files changed, 40 insertions(+), 220 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b219f393..4f7bbec3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,4 +2,3 @@ - [ ] Added an entry to the `changelog` module if knowledge of this change could be valuable to users - [ ] Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior - [ ] Created or updated an example program if it would help users understand this functionality -- [ ] Updated [feature matrix](https://github.com/rust-windowing/winit/blob/master/FEATURES.md), if new features were added or implemented diff --git a/FEATURES.md b/FEATURES.md index 6f5aff3f..25055f54 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -47,201 +47,3 @@ through the implementation work necessary to function on all platforms. When one gets implemented across all platforms, a PR can be opened to upgrade the feature to a core feature. If that gets accepted, the platform-specific functions get deprecated and become permanently exposed through the core, cross-platform API. - -# Features - -## Extending this section - -If your PR makes notable changes to Winit's features, please update this section as follows: - -- If your PR adds a new feature, add a brief description to the relevant section. If the feature is a core - feature, add a row to the feature matrix and describe what platforms the feature has been implemented on. - -- If your PR begins a new API rework, add a row to the `Pending API Reworks` table. If the PR implements the - API rework on all relevant platforms, please move it to the `Completed API Reworks` table. - -- If your PR implements an already-existing feature on a new platform, either mark the feature as *completed*, - or mark it as *mostly completed* and link to an issue describing the problems with the implementation. - -## Core - -### Windowing -- **Window initialization**: Winit allows the creation of a window -- **Providing pointer to init OpenGL**: Winit provides the necessary pointers to initialize a working opengl context -- **Providing pointer to init Vulkan**: Same as OpenGL but for Vulkan -- **Window decorations**: The windows created by winit are properly decorated, and the decorations can - be deactivated -- **Window decorations toggle**: Decorations can be turned on or off after window creation -- **Window resizing**: The windows created by winit can be resized and generate the appropriate events - when they are. The application can precisely control its window size if desired. -- **Window resize increments**: When the window gets resized, the application can choose to snap the window's - size to specific values. -- **Window transparency**: Winit allows the creation of windows with a transparent background. -- **Window maximization**: The windows created by winit can be maximized upon creation. -- **Window maximization toggle**: The windows created by winit can be maximized and unmaximized after - creation. -- **Window minimization**: The windows created by winit can be minimized after creation. -- **Fullscreen**: The windows created by winit can be put into fullscreen mode. -- **Fullscreen toggle**: The windows created by winit can be switched to and from fullscreen after - creation. -- **Exclusive fullscreen**: Winit allows changing the video mode of the monitor - for fullscreen windows and, if applicable, captures the monitor for exclusive - use by this application. -- **HiDPI support**: Winit assists developers in appropriately scaling HiDPI content. -- **Popup / modal windows**: Windows can be created relative to the client area of other windows, and parent - windows can be disabled in favor of popup windows. This feature also guarantees that popup windows - get drawn above their owner. - - -### System Information -- **Monitor list**: Retrieve the list of monitors and their metadata, including which one is primary. -- **Video mode query**: Monitors can be queried for their supported fullscreen video modes (consisting of resolution, refresh rate, and bit depth). - -### Input Handling -- **Mouse events**: Generating mouse events associated with pointer motion, click, and scrolling events. -- **Mouse set location**: Forcibly changing the location of the pointer. -- **Cursor locking**: Locking the cursor inside the window so it cannot move. -- **Cursor confining**: Confining the cursor to the window bounds so it cannot leave them. -- **Cursor icon**: Changing the cursor icon or hiding the cursor. -- **Cursor image**: Changing the cursor to your own image. -- **Cursor hittest**: Handle or ignore mouse events for a window. -- **Touch events**: Single-touch events. -- **Touch pressure**: Touch events contain information about the amount of force being applied. -- **Multitouch**: Multi-touch events, including cancellation of a gesture. -- **Keyboard events**: Properly processing keyboard events using the user-specified keymap and - translating keypresses into UTF-8 characters, handling dead keys and IMEs. -- **Drag & Drop**: Dragging content into winit, detecting when content enters, drops, or if the drop is cancelled. -- **Raw Device Events**: Capturing input from input devices without any OS filtering. -- **Gamepad/Joystick events**: Capturing input from gamepads and joysticks. -- **Device movement events**: Capturing input from the device gyroscope and accelerometer. - -## Platform -### Windows -* Setting the name of the internal window class -* Setting the taskbar icon -* Setting the parent window -* Setting a menu bar -* `WS_EX_NOREDIRECTIONBITMAP` support -* Theme the title bar according to Windows 10 Dark Mode setting or set a preferred theme -* Changing a system-drawn backdrop -* Setting the window border color -* Setting the title bar background color -* Setting the title color -* Setting the corner rounding preference - -### macOS -* Window activation policy -* Window movable by background -* Transparent titlebar -* Hidden titlebar -* Hidden titlebar buttons -* Full-size content view -* Accepts first mouse -* Set a preferred theme and get current theme. - -### Unix -* Window urgency -* X11 Window Class -* X11 Override Redirect Flag -* GTK Theme Variant -* Base window size -* Setting the X11 parent window - -### iOS -* Get the `UIScreen` object pointer -* Setting the `UIView` hidpi factor -* Valid orientations -* Home indicator visibility -* Status bar visibility and style -* Deferring system gestures -* Getting the preferred video mode - -### Web -* Get if the systems preferred color scheme is "dark" - -## Compatibility Matrix - -Legend: - -- ✔️: Works as intended -- ▢: Mostly works, but some bugs are known -- ❌: Missing feature or large bugs making it unusable -- **N/A**: Not applicable for this platform -- ❓: Unknown status - -### Windowing -|Feature |Windows|MacOS |Linux x11 |Linux Wayland |Android|iOS |Web |Redox OS| -|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | ------ | -|Window initialization |✔️ |✔️ |▢[#5] |✔️ |▢[#33]|▢[#33] |✔️ |✔️ | -|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |**N/A**|✔️ | -|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A** | -|Window decorations |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**|✔️ | -|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**|**N/A** | -|Window resizing |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|✔️ |✔️ | -|Window resize increments |✔️ |✔️ |✔️ |❌ |**N/A**|**N/A**|**N/A**|**N/A** | -|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|N/A |✔️ | -|Window blur |❌ |❌ |❌ |✔️ |**N/A**|**N/A**|N/A |❌ | -|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**|**N/A** | -|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**|**N/A** | -|Window minimization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**|**N/A** | -|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|✔️ |✔️ |**N/A** | -|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|✔️ |✔️ |**N/A** | -|Exclusive fullscreen |✔️ |✔️ |✔️ |**N/A** |❌ |✔️ |**N/A**|**N/A** | -|HiDPI support |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❌ | -|Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |**N/A**|**N/A** | - -### System information -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Web |Redox OS| -|---------------- | ----- | ---- | ------- | ----------- | ----- | ------- | -------- | ------ | -|Monitor list |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |**N/A**|❌ | -|Video mode query |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |**N/A**|❌ | - -### Input handling -|Feature |Windows |MacOS |Linux x11|Linux Wayland|Android|iOS |Web |Redox OS| -|----------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | ------ | -|Mouse events |✔️ |▢[#63] |✔️ |✔️ |**N/A**|**N/A**|✔️ |✔️ | -|Mouse set location |✔️ |✔️ |✔️ |✔️(when locked) |**N/A**|**N/A**|**N/A**|**N/A** | -|Cursor locking |❌ |✔️ |❌ |✔️ |**N/A**|**N/A**|✔️ |❌ | -|Cursor confining |✔️ |❌ |✔️ |✔️ |**N/A**|**N/A**|❌ |❌ | -|Cursor icon |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|✔️ |**N/A** | -|Cursor image |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|✔️ |**N/A** | -|Cursor hittest |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ |❌ | -|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ |**N/A** | -|Touch pressure |✔️ |❌ |❌ |❌ |❌ |✔️ |✔️ |**N/A** | -|Multitouch |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |❌ |**N/A** | -|Keyboard events |✔️ |✔️ |✔️ |✔️ |✔️ |❌ |✔️ |✔️ | -|Drag & Drop |▢[#720] |▢[#720] |▢[#720] |▢[#720] |**N/A**|**N/A**|❓ |**N/A** | -|Raw Device Events |▢[#750] |▢[#750] |▢[#750] |❌ |❌ |❌ |❓ |**N/A** | -|Gamepad/Joystick events |❌[#804] |❌ |❌ |❌ |❌ |❌ |❓ |**N/A** | -|Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❓ |**N/A** | -|Drag window with cursor |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** |**N/A** | -|Resize with cursor |✔️ |❌ |✔️ |✔️ |**N/A**|**N/A**|**N/A** |**N/A** | - -### Pending API Reworks -Changes in the API that have been agreed upon but aren't implemented across all platforms. - -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Web |Redox OS| -|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | ------ | -|New API for HiDPI ([#315] [#319]) |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |❓ | -|Event Loop 2.0 ([#459]) |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |✔️ | -|Keyboard Input 2.0 ([#753]) |✔️ |✔️ |✔️ |✔️ |✔️ |❌ |✔️ |✔️ | - -### Completed API Reworks -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Web |Redox OS| -|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | ------ | - -[#165]: https://github.com/rust-windowing/winit/issues/165 -[#219]: https://github.com/rust-windowing/winit/issues/219 -[#242]: https://github.com/rust-windowing/winit/issues/242 -[#306]: https://github.com/rust-windowing/winit/issues/306 -[#315]: https://github.com/rust-windowing/winit/issues/315 -[#319]: https://github.com/rust-windowing/winit/issues/319 -[#33]: https://github.com/rust-windowing/winit/issues/33 -[#459]: https://github.com/rust-windowing/winit/issues/459 -[#5]: https://github.com/rust-windowing/winit/issues/5 -[#63]: https://github.com/rust-windowing/winit/issues/63 -[#720]: https://github.com/rust-windowing/winit/issues/720 -[#721]: https://github.com/rust-windowing/winit/issues/721 -[#750]: https://github.com/rust-windowing/winit/issues/750 -[#753]: https://github.com/rust-windowing/winit/issues/753 -[#804]: https://github.com/rust-windowing/winit/issues/804 diff --git a/src/event.rs b/src/event.rs index 5a89923e..e7af7d65 100644 --- a/src/event.rs +++ b/src/event.rs @@ -175,18 +175,23 @@ pub enum WindowEvent { /// The window has been destroyed. Destroyed, - /// A file has been dropped into the window. - /// - /// When the user drops multiple files at once, this event will be emitted for each file - /// separately. - DroppedFile(PathBuf), - /// A file is being hovered over the window. /// /// When the user hovers multiple files at once, this event will be emitted for each file /// separately. HoveredFile(PathBuf), + /// A file has been dropped into the window. + /// + /// When the user drops multiple files at once, this event will be emitted for each file + /// separately. + /// + /// The support for this is known to be incomplete, see [#720] for more + /// information. + /// + /// [#720]: https://github.com/rust-windowing/winit/issues/720 + DroppedFile(PathBuf), + /// A file was hovered, but has exited the window. /// /// There will be a single `HoveredFileCancelled` event triggered even if multiple files were @@ -207,6 +212,7 @@ pub enum WindowEvent { /// - **Windows:** The shift key overrides NumLock. In other words, while shift is held down, /// numpad keys act as if NumLock wasn't active. When this is used, the OS sends fake key /// events which are not marked as `is_synthetic`. + /// - **iOS:** Unsupported. KeyboardInput { device_id: Option, event: KeyEvent, @@ -410,10 +416,18 @@ pub enum WindowEvent { /// Touchpad pressure event. /// - /// At the moment, only supported on Apple forcetouch-capable macbooks. - /// The parameters are: pressure level (value between 0 and 1 representing how hard the - /// touchpad is being pressed) and stage (integer representing the click level). - TouchpadPressure { device_id: Option, pressure: f32, stage: i64 }, + /// ## Platform-specific + /// + /// - **macOS**: Only supported on Apple forcetouch-capable macbooks. + /// - **Android / iOS / Wayland / X11 / Windows / Orbital / Web:** Unsupported. + TouchpadPressure { + device_id: Option, + /// Value between 0 and 1 representing how hard the touchpad is being + /// pressed. + pressure: f32, + /// Represents the click level. + stage: i64, + }, /// The window's scale factor has changed. /// diff --git a/src/monitor.rs b/src/monitor.rs index aeb64b4a..7cc7cb8f 100644 --- a/src/monitor.rs +++ b/src/monitor.rs @@ -1,18 +1,12 @@ //! Types useful for interacting with a user's 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`]: -//! - [`ActiveEventLoop::available_monitors`][crate::event_loop::ActiveEventLoop::available_monitors]. -//! - [`Window::available_monitors`][crate::window::Window::available_monitors]. use std::num::{NonZeroU16, NonZeroU32}; use crate::dpi::{PhysicalPosition, PhysicalSize}; use crate::platform_impl; -/// Describes a fullscreen video mode of a monitor. +/// A handle to a fullscreen video mode of a specific monitor. /// -/// Can be acquired with [`MonitorHandle::video_modes`]. +/// This can be acquired with [`MonitorHandle::video_modes`]. #[derive(Clone, PartialEq, Eq, Hash)] pub struct VideoModeHandle { pub(crate) video_mode: platform_impl::VideoModeHandle, @@ -92,7 +86,15 @@ impl std::fmt::Display for VideoModeHandle { /// Handle to a monitor. /// -/// Allows you to retrieve information about a given monitor and can be used in [`Window`] creation. +/// Allows you to retrieve basic information and metadata about a monitor. +/// +/// Can be used in [`Window`] creation to place the window on a specific +/// monitor. +/// +/// This can be retrieved from one of the following methods, which return an +/// iterator of [`MonitorHandle`]s: +/// - [`ActiveEventLoop::available_monitors`](crate::event_loop::ActiveEventLoop::available_monitors). +/// - [`Window::available_monitors`](crate::window::Window::available_monitors). /// /// ## Platform-specific /// diff --git a/src/window.rs b/src/window.rs index cd16d387..ff698af2 100644 --- a/src/window.rs +++ b/src/window.rs @@ -909,7 +909,7 @@ pub trait Window: AsAny + Send + Sync { /// - **Web / iOS / Android:** Unsupported. Always returns [`WindowButtons::all`]. fn enabled_buttons(&self) -> WindowButtons; - /// Sets the window to minimized or back + /// Minimize the window, or put it back from the minimized state. /// /// ## Platform-specific /// @@ -945,7 +945,7 @@ pub trait Window: AsAny + Send + Sync { /// - **iOS / Android / Web:** Unsupported. fn is_maximized(&self) -> bool; - /// Sets the window to fullscreen or back. + /// Set the window's fullscreen state. /// /// ## Platform-specific /// @@ -1433,6 +1433,9 @@ impl From for CursorIcon { /// Fullscreen modes. #[derive(Clone, Debug, PartialEq, Eq, Hash)] pub enum Fullscreen { + /// This changes the video mode of the monitor for fullscreen windows and, + /// if applicable, captures the monitor for exclusive use by this + /// application. Exclusive(VideoModeHandle), /// Providing `None` to `Borderless` will fullscreen on the current monitor.