2020-01-06 03:02:41 +11:00
|
|
|
//! Winit is a cross-platform window creation and event loop management library.
|
2014-08-03 04:49:48 +10:00
|
|
|
//!
|
2020-01-06 03:02:41 +11:00
|
|
|
//! # Building windows
|
2014-09-04 19:38:33 +10:00
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! Before you can build a [`Window`], you first need to build an [`EventLoop`]. This is done with the
|
|
|
|
//! [`EventLoop::new()`] function.
|
2014-09-04 19:38:33 +10:00
|
|
|
//!
|
2017-01-29 01:33:54 +11:00
|
|
|
//! ```no_run
|
2019-02-06 02:30:33 +11:00
|
|
|
//! use winit::event_loop::EventLoop;
|
|
|
|
//! let event_loop = EventLoop::new();
|
2017-01-29 01:33:54 +11:00
|
|
|
//! ```
|
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! Once this is done there are two ways to create a [`Window`]:
|
2017-01-29 01:33:54 +11:00
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! - Calling [`Window::new(&event_loop)`][window_new].
|
|
|
|
//! - Calling [`let builder = WindowBuilder::new()`][window_builder_new] then [`builder.build(&event_loop)`][window_builder_build].
|
2014-08-03 04:49:48 +10:00
|
|
|
//!
|
2020-01-06 03:02:41 +11:00
|
|
|
//! The first method is the simplest, and will give you default values for everything. The second
|
|
|
|
//! method 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`].
|
2014-10-05 04:17:02 +11:00
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! # Event handling
|
2014-10-05 04:17:02 +11:00
|
|
|
//!
|
2019-06-25 07:30:06 +10:00
|
|
|
//! Once a [`Window`] has been created, it will generate different *events*. A [`Window`] object can
|
2020-01-06 03:02:41 +11:00
|
|
|
//! generate [`WindowEvent`]s when certain input events occur, such as a cursor moving over the
|
|
|
|
//! window or a key getting pressed while the window is focused. Devices can generate
|
|
|
|
//! [`DeviceEvent`]s, which contain unfiltered event data that isn't specific to a certain window.
|
|
|
|
//! Some user activity, like mouse movement, can generate both a [`WindowEvent`] *and* a
|
|
|
|
//! [`DeviceEvent`]. You can also create and handle your own custom [`UserEvent`]s, if desired.
|
|
|
|
//!
|
|
|
|
//! You can retreive events by calling [`EventLoop::run`][event_loop_run]. This function will
|
|
|
|
//! dispatch events for every [`Window`] that was created with that particular [`EventLoop`], and
|
|
|
|
//! will run until the `control_flow` argument given to the closure is set to
|
|
|
|
//! [`ControlFlow`]`::`[`Exit`], at which point [`Event`]`::`[`LoopDestroyed`] is emitted and the
|
|
|
|
//! entire program terminates.
|
2017-01-29 01:33:54 +11:00
|
|
|
//!
|
2020-01-06 03:02:41 +11:00
|
|
|
//! Winit no longer uses a `EventLoop::poll_events() -> impl Iterator<Event>`-based event loop
|
|
|
|
//! model, since that can't be implemented properly on web and mobile platforms and works poorly on
|
|
|
|
//! most desktop platforms. However, this model can be re-implemented to an extent on desktops with
|
|
|
|
//! [`EventLoopExtDesktop::run_return`]. See that method's documentation for more reasons about why
|
|
|
|
//! it's discouraged, beyond mobile/web compatibility reasons.
|
2017-01-29 01:33:54 +11:00
|
|
|
//!
|
|
|
|
//!
|
|
|
|
//! ```no_run
|
2019-06-22 01:33:15 +10:00
|
|
|
//! use winit::{
|
|
|
|
//! event::{Event, WindowEvent},
|
2019-06-23 03:26:06 +10:00
|
|
|
//! event_loop::{ControlFlow, EventLoop},
|
|
|
|
//! window::WindowBuilder,
|
2019-06-22 01:33:15 +10:00
|
|
|
//! };
|
2019-06-23 03:26:06 +10:00
|
|
|
//!
|
|
|
|
//! let event_loop = EventLoop::new();
|
|
|
|
//! let window = WindowBuilder::new().build(&event_loop).unwrap();
|
2017-01-29 01:33:54 +11:00
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! event_loop.run(move |event, _, control_flow| {
|
2020-01-06 03:02:41 +11:00
|
|
|
//! // ControlFlow::Poll continuously runs the event loop, even if the OS hasn't
|
|
|
|
//! // dispatched any events. This is ideal for games and similar applications.
|
|
|
|
//! *control_flow = ControlFlow::Poll;
|
|
|
|
//!
|
|
|
|
//! // ControlFlow::Wait pauses the event loop if no events are available to process.
|
|
|
|
//! // This is ideal for non-game applications that only update in response to user
|
|
|
|
//! // input, and uses significantly less power/CPU time than ControlFlow::Poll.
|
|
|
|
//! *control_flow = ControlFlow::Wait;
|
|
|
|
//!
|
2017-01-29 01:33:54 +11:00
|
|
|
//! match event {
|
2020-01-06 03:02:41 +11:00
|
|
|
//! Event::WindowEvent {
|
|
|
|
//! event: WindowEvent::CloseRequested,
|
|
|
|
//! ..
|
|
|
|
//! } => {
|
|
|
|
//! println!("The close button was pressed; stopping");
|
|
|
|
//! *control_flow = ControlFlow::Exit
|
|
|
|
//! },
|
2019-07-31 16:31:12 +10:00
|
|
|
//! Event::MainEventsCleared => {
|
2019-06-23 03:26:06 +10:00
|
|
|
//! // Application update code.
|
2019-07-10 14:43:15 +10:00
|
|
|
//!
|
2019-06-23 03:26:06 +10:00
|
|
|
//! // Queue a RedrawRequested event.
|
2020-04-20 07:09:08 +10:00
|
|
|
//! //
|
|
|
|
//! // You only need to call this if you've determined that you need to redraw, in
|
|
|
|
//! // applications which do not always need to. Applications that redraw continuously
|
|
|
|
//! // can just render here instead.
|
2019-06-23 03:26:06 +10:00
|
|
|
//! window.request_redraw();
|
|
|
|
//! },
|
2019-07-31 16:31:12 +10:00
|
|
|
//! Event::RedrawRequested(_) => {
|
2019-06-23 03:26:06 +10:00
|
|
|
//! // Redraw the application.
|
|
|
|
//! //
|
2020-04-20 07:09:08 +10:00
|
|
|
//! // It's preferable for applications that do not render continuously to render in
|
|
|
|
//! // this event rather than in MainEventsCleared, since rendering in here allows
|
|
|
|
//! // the program to gracefully handle redraws requested by the OS.
|
2019-06-23 03:26:06 +10:00
|
|
|
//! },
|
2020-01-06 03:02:41 +11:00
|
|
|
//! _ => ()
|
2017-01-29 01:33:54 +11:00
|
|
|
//! }
|
|
|
|
//! });
|
|
|
|
//! ```
|
|
|
|
//!
|
2020-01-06 03:02:41 +11:00
|
|
|
//! [`Event`]`::`[`WindowEvent`] has a [`WindowId`] member. In multi-window environments, it should be
|
|
|
|
//! compared to the value returned by [`Window::id()`][window_id_fn] to determine which [`Window`]
|
|
|
|
//! dispatched the event.
|
2014-10-05 04:17:02 +11:00
|
|
|
//!
|
2016-11-03 19:49:19 +11:00
|
|
|
//! # Drawing on the window
|
|
|
|
//!
|
2020-01-06 03:02:41 +11:00
|
|
|
//! Winit doesn't directly provide any methods for drawing on a [`Window`]. However it allows you to
|
2020-04-20 04:58:58 +10:00
|
|
|
//! retrieve the raw handle of the window (see the [`platform`] module and/or the
|
|
|
|
//! [`raw_window_handle`] method), which in turn allows you to create an
|
|
|
|
//! OpenGL/Vulkan/DirectX/Metal/etc. context that can be used to render graphics.
|
2019-02-06 02:30:33 +11:00
|
|
|
//!
|
2019-11-12 10:05:59 +11:00
|
|
|
//! [`EventLoop`]: event_loop::EventLoop
|
2020-01-06 03:02:41 +11:00
|
|
|
//! [`EventLoopExtDesktop::run_return`]: ./platform/desktop/trait.EventLoopExtDesktop.html#tymethod.run_return
|
2019-11-12 10:05:59 +11:00
|
|
|
//! [`EventLoop::new()`]: event_loop::EventLoop::new
|
|
|
|
//! [event_loop_run]: event_loop::EventLoop::run
|
|
|
|
//! [`ControlFlow`]: event_loop::ControlFlow
|
|
|
|
//! [`Exit`]: event_loop::ControlFlow::Exit
|
|
|
|
//! [`Window`]: window::Window
|
2020-01-06 03:02:41 +11:00
|
|
|
//! [`WindowId`]: window::WindowId
|
2019-11-12 10:05:59 +11:00
|
|
|
//! [`WindowBuilder`]: window::WindowBuilder
|
|
|
|
//! [window_new]: window::Window::new
|
|
|
|
//! [window_builder_new]: window::WindowBuilder::new
|
|
|
|
//! [window_builder_build]: window::WindowBuilder::build
|
|
|
|
//! [window_id_fn]: window::Window::id
|
|
|
|
//! [`Event`]: event::Event
|
|
|
|
//! [`WindowEvent`]: event::WindowEvent
|
|
|
|
//! [`DeviceEvent`]: event::DeviceEvent
|
|
|
|
//! [`UserEvent`]: event::Event::UserEvent
|
|
|
|
//! [`LoopDestroyed`]: event::Event::LoopDestroyed
|
|
|
|
//! [`platform`]: platform
|
2020-04-20 04:58:58 +10:00
|
|
|
//! [`raw_window_handle`]: ./window/struct.Window.html#method.raw_window_handle
|
2014-08-03 04:49:48 +10:00
|
|
|
|
2019-06-18 04:27:00 +10:00
|
|
|
#![deny(rust_2018_idioms)]
|
2019-11-12 10:05:59 +11:00
|
|
|
#![deny(intra_doc_link_resolution_failure)]
|
2019-06-18 04:27:00 +10:00
|
|
|
|
2018-06-15 09:42:18 +10:00
|
|
|
#[allow(unused_imports)]
|
2015-04-03 17:33:51 +11:00
|
|
|
#[macro_use]
|
|
|
|
extern crate lazy_static;
|
2020-01-10 16:29:31 +11:00
|
|
|
#[allow(unused_imports)]
|
2018-07-02 01:01:46 +10:00
|
|
|
#[macro_use]
|
|
|
|
extern crate log;
|
2018-11-01 19:24:56 +11:00
|
|
|
#[cfg(feature = "serde")]
|
|
|
|
#[macro_use]
|
|
|
|
extern crate serde;
|
2019-06-13 04:07:25 +10:00
|
|
|
#[macro_use]
|
2019-02-05 03:52:00 +11:00
|
|
|
extern crate bitflags;
|
2015-06-05 23:38:21 +10:00
|
|
|
#[cfg(any(target_os = "macos", target_os = "ios"))]
|
2015-03-22 16:31:32 +11:00
|
|
|
#[macro_use]
|
|
|
|
extern crate objc;
|
2019-11-27 16:38:18 +11:00
|
|
|
#[cfg(all(target_arch = "wasm32", feature = "std_web"))]
|
2019-07-02 04:43:54 +10:00
|
|
|
extern crate std_web as stdweb;
|
2014-10-04 23:49:39 +10:00
|
|
|
|
2018-06-15 09:42:18 +10:00
|
|
|
pub mod dpi;
|
2019-05-30 11:29:54 +10:00
|
|
|
#[macro_use]
|
|
|
|
pub mod error;
|
2019-02-06 02:30:33 +11:00
|
|
|
pub mod event;
|
|
|
|
pub mod event_loop;
|
2018-05-08 07:36:21 +10:00
|
|
|
mod icon;
|
2019-06-25 11:15:34 +10:00
|
|
|
pub mod monitor;
|
2019-02-06 02:30:33 +11:00
|
|
|
mod platform_impl;
|
|
|
|
pub mod window;
|
2015-09-21 17:15:53 +10:00
|
|
|
|
2019-02-06 02:30:33 +11:00
|
|
|
pub mod platform;
|