migrations/winit
1
0
Fork 0
mirror of https://github.com/rust-windowing/winit.git synced 2026-06-26 22:53:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation

Browse Source
This commit is contained in:
Osspial
2018-08-23 19:09:19 -04:00
parent 4377680a44
commit 42e8a0d2cf
9 changed files with 103 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
examples/window_icon.rs
View File

@@ -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

8
src/dpi.rs
View File

@@ -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.

12
src/event.rs
View File

@@ -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<T> {
/// 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<T> {
/// 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<T> Event<T> {
}
}
/// 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

26
src/event_loop.rs
View File

@@ -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<T> std::fmt::Debug for EventLoop<T> {
}
}
/// 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<T> EventLoop<T> {
/// 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<T> EventLoop<T> {
}
}
/// Used to wake up the `EventLoop` from another thread.
/// Used to send custom events to `EventLoop`.
#[derive(Clone)]
pub struct EventLoopProxy<T> {
events_loop_proxy: platform_impl::EventLoopProxy<T>,

54
src/lib.rs
View File

@@ -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]

21
src/monitor.rs
View File

@@ -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)]

6
src/platform/desktop.rs
View File

@@ -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<F>(&mut self, event_handler: F)
where F: FnMut(Event<Self::UserEvent>, &EventLoop<Self::UserEvent>, &mut ControlFlow);
}

8
src/platform/mod.rs
View File

@@ -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;

2
src/window.rs
View File

@@ -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())