diff --git a/examples/window_icon.rs b/examples/window_icon.rs index 9db3e0f050..545b44c9f6 100644 --- a/examples/window_icon.rs +++ b/examples/window_icon.rs @@ -8,14 +8,10 @@ extern crate image; #[cfg(feature = "icon_loading")] fn main() { -<<<<<<< HEAD - use winit::Icon; -======= use winit::window::{WindowBuilder, Icon}; use winit::event::Event; use winit::event_loop::{EventLoop, ControlFlow}; ->>>>>>> Re-organize into module structure // You'll have to choose an icon size at your own discretion. On X11, the desired size varies // by WM, and on Windows, you still have to account for screen scaling. Here we use 32px, // since it seems to work well enough in most cases. Be careful about going too high, or diff --git a/src/dpi.rs b/src/dpi.rs index 0d1514273f..909c9835dc 100644 --- a/src/dpi.rs +++ b/src/dpi.rs @@ -33,9 +33,9 @@ //! windows. This event is sent any time the DPI factor changes, either because the window moved to another monitor, //! or because the user changed the configuration of their screen. //! - You can also retrieve the DPI factor of a monitor by calling -//! [`MonitorId::get_hidpi_factor`](../struct.MonitorId.html#method.get_hidpi_factor), or the +//! [`MonitorId::get_hidpi_factor`](../monitor/struct.MonitorId.html#method.get_hidpi_factor), or the //! current DPI factor applied to a window by calling -//! [`Window::get_hidpi_factor`](../struct.Window.html#method.get_hidpi_factor), which is roughly equivalent +//! [`Window::get_hidpi_factor`](../window/struct.Window.html#method.get_hidpi_factor), which is roughly equivalent //! to `window.get_current_monitor().get_hidpi_factor()`. //! //! Depending on the platform, the window's actual DPI factor may only be known after @@ -59,9 +59,9 @@ //! //! The window's logical size is conserved across DPI changes, resulting in the physical size changing instead. This //! may be surprising on X11, but is quite standard elsewhere. Physical size changes always produce a -//! [`Resized`](../enum.WindowEvent.html#variant.Resized) event, even on platforms where no resize actually occurs, +//! [`Resized`](../event/enum.WindowEvent.html#variant.Resized) event, even on platforms where no resize actually occurs, //! such as macOS and Wayland. As a result, it's not necessary to separately handle -//! [`HiDpiFactorChanged`](../enum.WindowEvent.html#variant.HiDpiFactorChanged) if you're only listening for size. +//! [`HiDpiFactorChanged`](../event/enum.WindowEvent.html#variant.HiDpiFactorChanged) if you're only listening for size. //! //! Your GPU has no awareness of the concept of logical pixels, and unless you like wasting pixel density, your //! framebuffer's size should be in physical pixels. diff --git a/src/event.rs b/src/event.rs index ad73473d6a..e20230248a 100644 --- a/src/event.rs +++ b/src/event.rs @@ -1,3 +1,9 @@ +//! The `Event` enum and assorted supporting types. +//! +//! These are sent to the closure given to [`EventLoop::run(...)`][event_loop_run], where they get +//! processed and used to modify the program state. For more details, see the root-level documentation. +//! +//! [event_loop_run]: ../event_loop/struct.EventLoop.html#method.run use std::time::Instant; use std::path::PathBuf; @@ -8,14 +14,17 @@ use platform_impl; /// Describes a generic event. #[derive(Clone, Debug, PartialEq)] pub enum Event { + /// Emitted when the OS sends an event to a winit window. WindowEvent { window_id: WindowId, event: WindowEvent, }, + /// Emitted when the OS sends an event to a device. DeviceEvent { device_id: DeviceId, event: DeviceEvent, }, + /// Emitted when an event is sent from [`EventLoopProxy::send_event`](../event_loop/struct.EventLoopProxy.html#method.send_event) UserEvent(T), /// Emitted when new events arrive from the OS to be processed. NewEvents(StartCause), @@ -27,7 +36,7 @@ pub enum Event { /// emitted, it is guaranteed to be the last event emitted. LoopDestroyed, - /// The application has been suspended or resumed. + /// Emitted when the application has been suspended or resumed. /// /// The parameter is true if app was suspended, and false if it has been resumed. Suspended(bool), @@ -48,6 +57,7 @@ impl Event { } } +/// Describes the reason the event loop is resuming. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum StartCause { /// Sent if the time specified by `ControlFlow::WaitUntil` has been reached. Contains the diff --git a/src/event_loop.rs b/src/event_loop.rs index 3870c70a88..447738547d 100644 --- a/src/event_loop.rs +++ b/src/event_loop.rs @@ -1,3 +1,14 @@ +//! 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. +//! +//! See the root-level documentation for information on how to create and use an event loop to +//! handle events. +//! +//! [create_proxy]: ./struct.EventLoop.html#method.create_proxy +//! [event_loop_proxy]: ./struct.EventLoopProxy.html +//! [send_event]: ./struct.EventLoopProxy.html#method.send_event use std::{fmt, error}; use std::time::Instant; @@ -29,9 +40,12 @@ impl std::fmt::Debug for EventLoop { } } -/// Returned by the user callback given to the `EventLoop::run_forever` method. +/// Set by the user callback given to the `EventLoop::run` method. /// -/// Indicates whether the `run_forever` method should continue or complete. +/// Indicates the desired behavior of the event loop after [`Event::EventsCleared`][events_cleared] +/// is emitted. +/// +/// [events_cleared]: ../event/enum.Event.html#variant.EventsCleared #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub enum ControlFlow { @@ -43,7 +57,8 @@ pub enum ControlFlow { /// When the current loop iteration finishes, immediately begin a new iteration regardless of /// whether or not new events are available to process. Poll, - /// Send a `LoopDestroyed` event and stop the event loop. + /// Send a `LoopDestroyed` event and stop the event loop. Once set, `control_flow` cannot be + /// changed from `Exit`. Exit } @@ -55,13 +70,14 @@ impl Default for ControlFlow { } impl EventLoop<()> { + /// Builds a new event loop with a `()` as the user event type. pub fn new() -> EventLoop<()> { EventLoop::<()>::new_user_event() } } impl EventLoop { - /// Builds a new events loop. + /// Builds a new event loop. /// /// Usage will result in display backend initialisation, this can be controlled on linux /// using an environment variable `WINIT_UNIX_BACKEND`. Legal values are `x11` and `wayland`. @@ -109,7 +125,7 @@ impl EventLoop { } } -/// Used to wake up the `EventLoop` from another thread. +/// Used to send custom events to `EventLoop`. #[derive(Clone)] pub struct EventLoopProxy { events_loop_proxy: platform_impl::EventLoopProxy, diff --git a/src/lib.rs b/src/lib.rs index d814170b4f..69a1db0e66 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,34 +2,35 @@ //! //! # Building a window //! -//! Before you can build a window, you first need to build an `EventLoop`. This is done with the -//! `EventLoop::new()` function. Example: +//! Before you can build a [`Window`], you first need to build an [`EventLoop`]. This is done with the +//! [`EventLoop::new()`] function. //! //! ```no_run //! use winit::event_loop::EventLoop; //! let events_loop = EventLoop::new(); //! ``` //! -//! Once this is done there are two ways to create a window: +//! Once this is done there are two ways to create a [`Window`]: //! -//! - Calling `Window::new(&events_loop)`. -//! - Calling `let builder = WindowBuilder::new()` then `builder.build(&events_loop)`. +//! - Calling [`Window::new(&events_loop)`][window_new]. +//! - Calling [`let builder = WindowBuilder::new()`][window_builder_new] then [`builder.build(&events_loop)`][window_builder_build]. //! //! The first way is the simplest way and will give you default values for everything. //! -//! The second way allows you to customize the way your window will look and behave by modifying -//! the fields of the `WindowBuilder` object before you create the window. +//! The second way allows you to customize the way your [`Window`] will look and behave by modifying +//! the fields of the [`WindowBuilder`] object before you create the [`Window`]. //! -//! # Events handling +//! # Event handling //! -//! Once a window has been created, it will *generate events*. For example whenever the user moves -//! the window, resizes the window, moves the mouse, etc. an event is generated. +//! Once a [`Window`] has been created, it will *generate events*. For example whenever the user moves +//! the [`Window`], resizes the [`Window`], moves the mouse, etc. an event is generated. //! -//! The events generated by a window can be retreived from the `EventLoop` the window was created +//! The events generated by a [`Window`] can be retreived from the [`EventLoop`] the [`Window`] was created //! with. //! -//! You do this by calling `events_loop.run(...)`. This function will run forever unless it is -//! stopped by returning `ControlFlow::Exit`, at which point the entire program will terminate. +//! You do this by calling [`events_loop.run(...)`][event_loop_run]. This function will run forever +//! unless `control_flow` is set to [`ControlFlow`]`::`[`Exit`], at which point [`Event`]`::`[`LoopDestroyed`] +//! is emitted and the entire program terminates. //! //! ```no_run //! use winit::event_loop::ControlFlow; @@ -48,16 +49,31 @@ //! }); //! ``` //! -//! If you use multiple windows, the `WindowEvent` event has a member named `window_id`. You can -//! compare it with the value returned by the `id()` method of `Window` in order to know which -//! window has received the event. +//! If you use multiple [`Window`]s, [`Event`]`::`[`WindowEvent`] has a member named `window_id`. You can +//! compare it with the value returned by the [`id()`][window_id_fn] method of [`Window`] in order to know which +//! [`Window`] has received the event. //! //! # Drawing on the window //! -//! Winit doesn't provide any function that allows drawing on a window. However it allows you to -//! retrieve the raw handle of the window (see the `platform` module for that), which in turn allows you -//! to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the window. -//! +//! Winit doesn't provide any function that allows drawing on a [`Window`]. However it allows you to +//! retrieve the raw handle of the window (see the [`platform`] module), which in turn allows you +//! to create an OpenGL/Vulkan/DirectX/Metal/etc. context that will draw on the [`Window`]. +//! +//! [`EventLoop`]: ./event_loop/struct.EventLoop.html +//! [`EventLoop::new()`]: ./event_loop/struct.EventLoop.html#method.new +//! [event_loop_run]: ./event_loop/struct.EventLoop.html#method.run +//! [`ControlFlow`]: ./event_loop/enum.ControlFlow.html +//! [`Exit`]: ./event_loop/enum.ControlFlow.html#variant.Exit +//! [`Window`]: ./window/struct.Window.html +//! [`WindowBuilder`]: ./window/struct.WindowBuilder.html +//! [window_new]: ./window/struct.Window.html#method.new +//! [window_builder_new]: ./window/struct.WindowBuilder.html#method.new +//! [window_builder_build]: ./window/struct.WindowBuilder.html#method.build +//! [window_id_fn]: ./window/struct.Window.html#method.id +//! [`Event`]: ./event/enum.Event.html +//! [`WindowEvent`]: ./event/enum.Event.html#variant.WindowEvent +//! [`LoopDestroyed`]: ./event/enum.Event.html#variant.LoopDestroyed +//! [`platform`]: ./platform/index.html #[allow(unused_imports)] #[macro_use] diff --git a/src/monitor.rs b/src/monitor.rs index 4697b1f844..76aaed9e7c 100644 --- a/src/monitor.rs +++ b/src/monitor.rs @@ -1,9 +1,28 @@ +//! Types useful for interacting with a user's monitors. +//! +//! If you want to get basic information about a monitor, you can use the [`MonitorId`][monitor_id] +//! type. This is retreived from an [`AvailableMonitorsIter`][monitor_iter], which can be acquired +//! with: +//! - [`EventLoop::get_available_monitors`][loop_get] +//! - [`Window::get_available_monitors`][window_get]. +//! +//! [monitor_id]: ./struct.MonitorId.html +//! [monitor_iter]: ./struct.AvailableMonitorsIter.html +//! [loop_get]: ../event_loop/struct.EventLoop.html#method.get_available_monitors +//! [window_get]: ../window/struct.Window.html#method.get_available_monitors use std::collections::vec_deque::IntoIter as VecDequeIter; use platform_impl; use dpi::{PhysicalPosition, PhysicalSize}; -/// An iterator for the list of available monitors. +/// An iterator over all available monitors. +/// +/// Can be acquired with: +/// - [`EventLoop::get_available_monitors`][loop_get] +/// - [`Window::get_available_monitors`][window_get]. +/// +/// [loop_get]: ../event_loop/struct.EventLoop.html#method.get_available_monitors +/// [window_get]: ../window/struct.Window.html#method.get_available_monitors // Implementation note: we retrieve the list once, then serve each element by one by one. // This may change in the future. #[derive(Debug)] diff --git a/src/platform/desktop.rs b/src/platform/desktop.rs index 51da320107..2aaa9cf219 100644 --- a/src/platform/desktop.rs +++ b/src/platform/desktop.rs @@ -9,11 +9,13 @@ use event_loop::{EventLoop, ControlFlow}; /// Additional methods on `EventLoop` that are specific to desktop platforms. pub trait EventLoopExtDesktop { + /// A type provided by the user that can be passed through `Event::UserEvent`. type UserEvent; + /// Initializes the `winit` event loop. /// - /// Unlikes `run`, this function *does* return control flow to the caller when `control_flow` - /// is set to `ControlFlow::Exit`. + /// Unlikes `run`, this function accepts non-`'static` closures and returns control flow to the + /// caller when `control_flow` is set to `ControlFlow::Exit`. fn run_return(&mut self, event_handler: F) where F: FnMut(Event, &EventLoop, &mut ControlFlow); } diff --git a/src/platform/mod.rs b/src/platform/mod.rs index 27ce048d99..ba494ac6d3 100644 --- a/src/platform/mod.rs +++ b/src/platform/mod.rs @@ -1,6 +1,6 @@ //! Contains traits with platform-specific methods in them. //! -//! Contains the follow modules: +//! Contains the follow OS-specific modules: //! //! - `android` //! - `ios` @@ -8,8 +8,12 @@ //! - `unix` //! - `windows` //! -//! However only the module corresponding to the platform you're compiling to will be available. +//! And the following platform-specific module: +//! +//! - `desktop` (available on `windows`, `unix`, and `macos`) //! +//! However only the module corresponding to the platform you're compiling to will be available. + pub mod android; pub mod ios; pub mod macos; diff --git a/src/window.rs b/src/window.rs index 36652072ec..5085c21d6f 100644 --- a/src/window.rs +++ b/src/window.rs @@ -1,3 +1,4 @@ +//! The `Window` struct and associated types. use std::{fmt, error}; use platform_impl; @@ -578,6 +579,7 @@ impl Window { MonitorId { inner: self.window.get_primary_monitor() } } + /// Returns an identifier unique to the window. #[inline] pub fn id(&self) -> WindowId { WindowId(self.window.id())