2017-06-22 05:10:23 +10:00
|
|
|
//! Winit allows you to build a window on as many platforms as possible.
|
2014-08-03 04:49:48 +10:00
|
|
|
//!
|
|
|
|
//! # Building a window
|
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
|
|
|
//!
|
2018-05-21 00:47:22 +10:00
|
|
|
//! The first way is the simplest way and will give you default values for everything.
|
2014-08-03 04:49:48 +10:00
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! 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`].
|
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-02-06 02:30:33 +11:00
|
|
|
//! 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.
|
2017-01-29 01:33:54 +11:00
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! The events generated by a [`Window`] can be retreived from the [`EventLoop`] the [`Window`] was created
|
2017-01-29 01:33:54 +11:00
|
|
|
//! with.
|
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! You do this by calling [`event_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.
|
2017-01-29 01:33:54 +11:00
|
|
|
//!
|
|
|
|
//! ```no_run
|
2019-02-06 02:30:33 +11:00
|
|
|
//! use winit::event_loop::ControlFlow;
|
|
|
|
//! use winit::event::{Event, WindowEvent};
|
|
|
|
//! # 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
|
|
|
//! event_loop.run(move |event, _, control_flow| {
|
2017-01-29 01:33:54 +11:00
|
|
|
//! match event {
|
2018-04-25 06:20:40 +10:00
|
|
|
//! Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
|
|
|
|
//! println!("The close button was pressed; stopping");
|
2019-02-06 02:30:33 +11:00
|
|
|
//! *control_flow = ControlFlow::Exit
|
2017-01-29 01:33:54 +11:00
|
|
|
//! },
|
2019-02-06 02:30:33 +11:00
|
|
|
//! _ => *control_flow = ControlFlow::Wait,
|
2017-01-29 01:33:54 +11:00
|
|
|
//! }
|
|
|
|
//! });
|
|
|
|
//! ```
|
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! 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.
|
2014-10-05 04:17:02 +11:00
|
|
|
//!
|
2016-11-03 19:49:19 +11:00
|
|
|
//! # Drawing on the window
|
|
|
|
//!
|
2019-02-06 02:30:33 +11:00
|
|
|
//! 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
|
2014-08-03 04:49:48 +10:00
|
|
|
|
2019-06-17 14:30:05 +10:00
|
|
|
extern crate instant;
|
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;
|
2014-07-27 18:55:37 +10:00
|
|
|
extern crate libc;
|
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;
|
2014-07-27 18:55:37 +10:00
|
|
|
|
2014-12-02 04:24:15 +11:00
|
|
|
#[cfg(target_os = "windows")]
|
|
|
|
extern crate winapi;
|
2019-02-05 03:52:00 +11:00
|
|
|
#[macro_use]
|
|
|
|
#[cfg(target_os = "windows")]
|
|
|
|
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;
|
|
|
|
#[cfg(target_os = "macos")]
|
2014-10-04 23:49:39 +10:00
|
|
|
extern crate cocoa;
|
|
|
|
#[cfg(target_os = "macos")]
|
2019-05-02 09:03:30 +10:00
|
|
|
extern crate dispatch;
|
|
|
|
#[cfg(target_os = "macos")]
|
2014-10-04 23:49:39 +10:00
|
|
|
extern crate core_foundation;
|
2014-11-05 04:03:38 +11:00
|
|
|
#[cfg(target_os = "macos")]
|
2015-06-04 14:13:18 +10:00
|
|
|
extern crate core_graphics;
|
2018-07-17 00:25:27 +10:00
|
|
|
#[cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "netbsd", target_os = "openbsd"))]
|
2015-05-07 21:20:25 +10:00
|
|
|
extern crate x11_dl;
|
2019-02-06 02:30:33 +11:00
|
|
|
#[cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "netbsd", target_os = "openbsd", target_os = "windows"))]
|
X11: General cleanup (#491)
* X11: General cleanup
This is almost entirely internal changes, and as usual, doesn't actually
fix any problems people have complained about.
- `XSetInputFocus` can't be called before the window is visible. This
was previously handled by looping (with a sleep) and querying for the
window's state until it was visible. Now we use `XIfEvent`, which blocks
until we receive `VisibilityNotify`. Note that this can't be replaced
with an `XSync` (I tried).
- We now call `XSync` at the end of window creation and check for
errors, assuring that broken windows are never returned. When creating
invisible windows, this is the only time the output buffer is flushed
during the entire window creation process (AFAIK). For visible windows,
`XIfEvent` will generally flush, but window creation has overall been
reduced to the minimum number of flushes.
- `check_errors().expect()` has been a common pattern throughout the
backend, but it seems that people (myself included) didn't make a
distinction between using it after synchronous requests and asynchronous
requests. Now we only use it after async requests if we flush first,
though this still isn't correct (since the request likely hasn't been
processed yet). The only real solution (besides forcing a sync *every
time*) is to handle asynchronous errors *asynchronously*. For future
work, I plan on adding logging, though I don't plan on actually
*handling* those errors; that's more of something to hope for in the
hypothetical async/await XCB paradise.
- We now flush whenever it makes sense to. `util::Flusher` was added to
force contributors to be aware of the output buffer.
- `Window::get_position`, `Window::get_inner_position`,
`Window::get_inner_size`, and `Window::get_outer_size` previously all
required *several* round-trips. On my machine, it took an average of
around 80µs. They've now been reduced to one round-trip each, which
reduces my measurement to 16µs. This was accomplished simply by caching
the frame extents, which are expensive to calculate (due to various
queries and heuristics), but change infrequently and predictably. I
still recommend that application developers use these methods sparingly
and generally prefer storing the values from `Resized`/`Moved`, as
that's zero overhead.
- The above change enabled me to change the `Moved` event to supply
window positions, rather than client area positions. Additionally, we no
longer generate `Moved` for real (as in, not synthetic)
`ConfigureNotify` events. Real `ConfigureNotify` events contain
positions relative to the parent window, which are typically constant
and useless. Since that position would be completely different from the
root-relative positions supplied by synthetic `ConfigureNotify` events
(which are the vast majority of them), that meant real `ConfigureNotify`
events would *always* be detected as the position having changed, so the
resultant `Moved` was multiple levels of misleading. In practice, this
meant a garbage `Moved` would be sent every time the window was resized;
now a resize has to actually change the window's position to be
accompanied by `Moved`.
- Every time we processed an `XI_Enter` event, we would leak 4 bytes via
`util::query_pointer` (`XIQueryPointer`). `XIButtonState` contains a
dynamically-allocated mask field which we weren't freeing. As this event
occurs with fairly high frequency, long-running applications could
easily accumulate substantial leaks. `util::PointerState::drop` now
takes care of this.
- The `util` module has been split up into several sub-modules, as it
was getting rather lengthy. This accounts for a significant part of this
diff, unfortunately.
- Atoms are now cached. Xlib caches them too, so `XInternAtom` wouldn't
typically be a round-trip anyway, but the added complexity is
negligible.
- Switched from `std::sync::Mutex` to `parking_lot::Mutex` (within this
backend). There appears to be no downside to this, but if anyone finds
one, this would be easy to revert.
- The WM name and supported hints are now global to the application, and
are updated upon `ReparentNotify`, which should detect when the WM was
replaced (assuming a reparenting WM was involved, that is). Previously,
these values were per-window and would never update, meaning replacing
the WM could potentially lead to (admittedly very minor) problems.
- The result of `Window2::create_empty_cursor` will now only be used if
it actually succeeds.
- `Window2::load_cursor` no longer re-allocates the cursor name.
- `util::lookup_utf8` previously allocated a 16-byte buffer on the heap.
Now it allocates a 1024-byte buffer on the stack, and falls back to
dynamic allocation if the buffer is too small. This base buffer size is
admittedly gratuitous, but less so if you're using IME.
- `with_c_str` was finally removed.
- Added `util::Format` enum to help prevent goofs when dealing with
format arguments.
- `util::get_property`, something I added way back in my first winit PR,
only calculated offsets correctly for `util::Format::Char`. This was
concealed by the accomodating buffer size, as it would be very rare for
the offset to be needed; however, testing with a buffer size of 1,
`util::Format::Long` would read from the same offset multiple times, and
`util::Format::Short` would miss data. This function now works correctly
for all formats, relying on the simple fact that the offset increases by
the buffer size on each iteration. We also account for the extra byte
that `XGetWindowProperty` allocates at the end of the buffer, and copy
data from the buffer instead of moving it and taking ownership of the
pointer.
- Drag and drop now reliably works in release mode. This is presumably
related to the `util::get_property` changes.
- `util::change_property` now exists, which should make it easier to add
features in the future.
- The `EventsLoop` device map is no longer in a mutex.
- `XConnection` now implements `Debug`.
- Valgrind no longer complains about anything related to winit (with
either the system allocator or jemalloc, though "not having valgrind
complain about jemalloc" isn't something to strive for).
* X11: Add better diagnostics when initialization fails
* X11: Handle XIQueryDevice failure
* X11: Use correct types in error handler
2018-05-03 23:15:49 +10:00
|
|
|
extern crate parking_lot;
|
2018-07-17 00:25:27 +10:00
|
|
|
#[cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "netbsd", target_os = "openbsd"))]
|
2017-12-13 22:22:03 +11:00
|
|
|
extern crate percent_encoding;
|
2018-08-02 05:22:14 +10:00
|
|
|
#[cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "netbsd", target_os = "openbsd"))]
|
2018-05-06 03:36:34 +10:00
|
|
|
extern crate smithay_client_toolkit as sctk;
|
2019-02-27 05:36:48 +11:00
|
|
|
#[cfg(feature = "stdweb")]
|
2019-03-03 04:31:16 +11:00
|
|
|
#[macro_use]
|
2019-02-27 05:36:48 +11:00
|
|
|
extern crate stdweb;
|
2019-02-21 20:51:43 +11:00
|
|
|
#[cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "netbsd", target_os = "openbsd"))]
|
|
|
|
extern crate calloop;
|
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-02-06 02:30:33 +11:00
|
|
|
mod platform_impl;
|
|
|
|
pub mod window;
|
|
|
|
pub mod monitor;
|
2015-09-21 17:15:53 +10:00
|
|
|
|
2019-02-06 02:30:33 +11:00
|
|
|
pub mod platform;
|