mirror of
https://github.com/italicsjenga/winit-sonoma-fix.git
synced 2024-12-24 22:31:30 +11:00
Add documentation for the new API
This commit is contained in:
parent
d86fdb48d1
commit
bcb242983b
95
src/lib.rs
95
src/lib.rs
|
@ -2,10 +2,18 @@
|
||||||
//!
|
//!
|
||||||
//! # Building a window
|
//! # Building a window
|
||||||
//!
|
//!
|
||||||
//! There are two ways to create a window:
|
//! Before you can build a window, you first need to build an `EventsLoop`. This is done with the
|
||||||
|
//! `EventsLoop::new()` function. Example:
|
||||||
//!
|
//!
|
||||||
//! - Calling `Window::new()`.
|
//! ```no_run
|
||||||
//! - Calling `let builder = WindowBuilder::new()` then `builder.build()`.
|
//! use winit::EventsLoop;
|
||||||
|
//! let events_loop = EventsLoop::new();
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! 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)`.
|
||||||
//!
|
//!
|
||||||
//! The first way is the simpliest way and will give you default values for everything.
|
//! The first way is the simpliest way and will give you default values for everything.
|
||||||
//!
|
//!
|
||||||
|
@ -14,11 +22,58 @@
|
||||||
//!
|
//!
|
||||||
//! # Events handling
|
//! # Events handling
|
||||||
//!
|
//!
|
||||||
//! Once a window has been created, you can handle the events that it generates. There are two ways
|
//! Once a window has been created, it will *generate events*. For example whenever the user moves
|
||||||
//! to do so: with `poll_events` or with `wait_events`. The former returns an iterator that ends
|
//! the window, resizes the window, moves the mouse, etc. an event is generated.
|
||||||
//! when no event is available, and the latter returns an iterator that blocks and waits for events
|
//!
|
||||||
//! if none is available. Depending on which kind of program you're writing, you usually choose
|
//! The events generated by a window can be retreived from the `EventsLoop` the window was created
|
||||||
//! one or the other.
|
//! with.
|
||||||
|
//!
|
||||||
|
//! There are two ways to do so. The first is to call `events_loop.poll_events(...)`, which will
|
||||||
|
//! retreive all the events pending on the windows and immediately return after no new event is
|
||||||
|
//! available. You usually want to use this method in application that render continuously on the
|
||||||
|
//! screen, such as video games.
|
||||||
|
//!
|
||||||
|
//! ```no_run
|
||||||
|
//! use winit::Event;
|
||||||
|
//! use winit::WindowEvent;
|
||||||
|
//! # use winit::EventsLoop;
|
||||||
|
//! # let events_loop = EventsLoop::new();
|
||||||
|
//!
|
||||||
|
//! loop {
|
||||||
|
//! events_loop.poll_events(|event| {
|
||||||
|
//! match event {
|
||||||
|
//! Event::WindowEvent { event: WindowEvent::Resized(w, h), .. } => {
|
||||||
|
//! println!("The window was resized to {}x{}", w, h);
|
||||||
|
//! },
|
||||||
|
//! _ => ()
|
||||||
|
//! }
|
||||||
|
//! });
|
||||||
|
//! }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! The second way is to call `events_loop.run_forever(...)`. As its name tells, it will run
|
||||||
|
//! forever unless it is stopped by calling `events_loop.interrupt()`.
|
||||||
|
//!
|
||||||
|
//! ```no_run
|
||||||
|
//! use winit::Event;
|
||||||
|
//! use winit::WindowEvent;
|
||||||
|
//! # use winit::EventsLoop;
|
||||||
|
//! # let events_loop = EventsLoop::new();
|
||||||
|
//!
|
||||||
|
//! events_loop.run_forever(|event| {
|
||||||
|
//! match event {
|
||||||
|
//! Event::WindowEvent { event: WindowEvent::Closed, .. } => {
|
||||||
|
//! println!("The window was closed ; stopping");
|
||||||
|
//! events_loop.interrupt();
|
||||||
|
//! },
|
||||||
|
//! _ => ()
|
||||||
|
//! }
|
||||||
|
//! });
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! 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.
|
||||||
//!
|
//!
|
||||||
//! # Drawing on the window
|
//! # Drawing on the window
|
||||||
//!
|
//!
|
||||||
|
@ -86,22 +141,29 @@ pub mod os;
|
||||||
/// # Example
|
/// # Example
|
||||||
///
|
///
|
||||||
/// ```no_run
|
/// ```no_run
|
||||||
|
/// use winit::Event;
|
||||||
|
/// use winit::EventsLoop;
|
||||||
/// use winit::Window;
|
/// use winit::Window;
|
||||||
/// let window = Window::new().unwrap();
|
/// use winit::WindowEvent;
|
||||||
///
|
///
|
||||||
/// loop {
|
/// let events_loop = EventsLoop::new();
|
||||||
/// for event in window.wait_events() {
|
/// let window = Window::new(&events_loop).unwrap();
|
||||||
|
///
|
||||||
|
/// events_loop.run_forever(|event| {
|
||||||
/// match event {
|
/// match event {
|
||||||
/// // process events here
|
/// Event::WindowEvent { event: WindowEvent::Closed, .. } => {
|
||||||
|
/// events_loop.interrupt();
|
||||||
|
/// },
|
||||||
/// _ => ()
|
/// _ => ()
|
||||||
/// }
|
/// }
|
||||||
/// }
|
/// });
|
||||||
/// }
|
|
||||||
/// ```
|
/// ```
|
||||||
pub struct Window {
|
pub struct Window {
|
||||||
window: platform::Window2,
|
window: platform::Window2,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Provides a way to retreive events from the windows that were registered to it.
|
||||||
|
// TODO: document usage in multiple threads
|
||||||
pub struct EventsLoop {
|
pub struct EventsLoop {
|
||||||
events_loop: Arc<platform::EventsLoop>,
|
events_loop: Arc<platform::EventsLoop>,
|
||||||
}
|
}
|
||||||
|
@ -114,6 +176,8 @@ impl EventsLoop {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Fetches all the events that are pending, calls the callback function for each of them,
|
||||||
|
/// and returns.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn poll_events<F>(&self, callback: F)
|
pub fn poll_events<F>(&self, callback: F)
|
||||||
where F: FnMut(Event)
|
where F: FnMut(Event)
|
||||||
|
@ -121,6 +185,7 @@ impl EventsLoop {
|
||||||
self.events_loop.poll_events(callback)
|
self.events_loop.poll_events(callback)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Runs forever until `interrupt()` is called. Whenever an event happens, calls the callback.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn run_forever<F>(&self, callback: F)
|
pub fn run_forever<F>(&self, callback: F)
|
||||||
where F: FnMut(Event)
|
where F: FnMut(Event)
|
||||||
|
@ -128,6 +193,8 @@ impl EventsLoop {
|
||||||
self.events_loop.run_forever(callback)
|
self.events_loop.run_forever(callback)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// If we called `run_forever()`, stops the process of waiting for events.
|
||||||
|
// TODO: what if we're waiting from multiple threads?
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn interrupt(&self) {
|
pub fn interrupt(&self) {
|
||||||
self.events_loop.interrupt()
|
self.events_loop.interrupt()
|
||||||
|
|
|
@ -119,7 +119,7 @@ impl WindowBuilder {
|
||||||
impl Window {
|
impl Window {
|
||||||
/// Creates a new OpenGL context, and a Window for platforms where this is appropriate.
|
/// Creates a new OpenGL context, and a Window for platforms where this is appropriate.
|
||||||
///
|
///
|
||||||
/// This function is equivalent to `WindowBuilder::new().build()`.
|
/// This function is equivalent to `WindowBuilder::new().build(events_loop)`.
|
||||||
///
|
///
|
||||||
/// Error should be very rare and only occur in case of permission denied, incompatible system,
|
/// Error should be very rare and only occur in case of permission denied, incompatible system,
|
||||||
/// out of memory, etc.
|
/// out of memory, etc.
|
||||||
|
|
Loading…
Reference in a new issue