pub enum Event<T: 'static> {
NewEvents(StartCause),
WindowEvent {
window_id: WindowId,
event: WindowEvent,
},
DeviceEvent {
device_id: DeviceId,
event: DeviceEvent,
},
UserEvent(T),
Suspended,
Resumed,
AboutToWait,
LoopExiting,
MemoryWarning,
}
Expand description
Describes a generic event.
See the module-level docs for more information on the event loop manages each event.
Variants§
NewEvents(StartCause)
Emitted when new events arrive from the OS to be processed.
This event type is useful as a place to put code that should be done before you start
processing events, such as updating frame timing information for benchmarking or checking
the StartCause
to see if a timer set by
ControlFlow::WaitUntil
has elapsed.
WindowEvent
Emitted when the OS sends an event to a winit window.
DeviceEvent
Emitted when the OS sends an event to a device.
UserEvent(T)
Emitted when an event is sent from EventLoopProxy::send_event
Suspended
Emitted when the application has been suspended.
§Portability
Not all platforms support the notion of suspending applications, and there may be no
technical way to guarantee being able to emit a Suspended
event if the OS has
no formal application lifecycle (currently only Android, iOS, and Web do). For this reason,
Winit does not currently try to emit pseudo Suspended
events before the application
quits on platforms without an application lifecycle.
Considering that the implementation of Suspended
and Resumed
events may be internally
driven by multiple platform-specific events, and that there may be subtle differences across
platforms with how these internal events are delivered, it’s recommended that applications
be able to gracefully handle redundant (i.e. back-to-back) Suspended
or Resumed
events.
Also see Resumed
notes.
§Android
On Android, the Suspended
event is only sent when the application’s associated
SurfaceView
is destroyed. This is expected to closely correlate with the onPause
lifecycle event but there may technically be a discrepancy.
Applications that need to run on Android should assume their SurfaceView
has been
destroyed, which indirectly invalidates any existing render surfaces that may have been
created outside of Winit (such as an EGLSurface
, VkSurfaceKHR
or wgpu::Surface
).
After being Suspended
on Android applications must drop all render surfaces before
the event callback completes, which may be re-created when the application is next Resumed
.
§iOS
On iOS, the Suspended
event is currently emitted in response to an
applicationWillResignActive
callback which means that the application is
about to transition from the active to inactive state (according to the
iOS application lifecycle).
§Web
On Web, the Suspended
event is emitted in response to a pagehide
event
with the property persisted
being true, which means that the page is being
put in the bfcache
(back/forward cache) - an in-memory cache that stores a
complete snapshot of a page (including the JavaScript heap) as the user is
navigating away.
Resumed
Emitted when the application has been resumed.
For consistency, all platforms emit a Resumed
event even if they don’t themselves have a
formal suspend/resume lifecycle. For systems without a standard suspend/resume lifecycle
the Resumed
event is always emitted after the NewEvents(StartCause::Init)
event.
§Portability
It’s recommended that applications should only initialize their graphics context and create
a window after they have received their first Resumed
event. Some systems
(specifically Android) won’t allow applications to create a render surface until they are
resumed.
Considering that the implementation of Suspended
and Resumed
events may be internally
driven by multiple platform-specific events, and that there may be subtle differences across
platforms with how these internal events are delivered, it’s recommended that applications
be able to gracefully handle redundant (i.e. back-to-back) Suspended
or Resumed
events.
Also see Suspended
notes.
§Android
On Android, the Resumed
event is sent when a new SurfaceView
has been created. This is
expected to closely correlate with the onResume
lifecycle event but there may technically
be a discrepancy.
Applications that need to run on Android must wait until they have been Resumed
before they will be able to create a render surface (such as an EGLSurface
,
VkSurfaceKHR
or wgpu::Surface
) which depend on having a
SurfaceView
. Applications must also assume that if they are Suspended
, then their
render surfaces are invalid and should be dropped.
Also see Suspended
notes.
§iOS
On iOS, the Resumed
event is emitted in response to an applicationDidBecomeActive
callback which means the application is “active” (according to the
iOS application lifecycle).
§Web
On Web, the Resumed
event is emitted in response to a pageshow
event
with the property persisted
being true, which means that the page is being
restored from the bfcache
(back/forward cache) - an in-memory cache that
stores a complete snapshot of a page (including the JavaScript heap) as the
user is navigating away.
AboutToWait
Emitted when the event loop is about to block and wait for new events.
Most applications shouldn’t need to hook into this event since there is no real relationship between how often the event loop needs to wake up and the dispatching of any specific events.
High frequency event sources, such as input devices could potentially lead to lots of wake
ups and also lots of corresponding AboutToWait
events.
This is not an ideal event to drive application rendering from and instead applications
should render in response to WindowEvent::RedrawRequested
events.
LoopExiting
Emitted when the event loop is being shut down.
This is irreversible - if this event is emitted, it is guaranteed to be the last event that gets emitted. You generally want to treat this as a “do on quit” event.
MemoryWarning
Emitted when the application has received a memory warning.
§Platform-specific
§Android
On Android, the MemoryWarning
event is sent when onLowMemory
was called. The application
must release memory or risk being killed.
§iOS
On iOS, the MemoryWarning
event is emitted in response to an applicationDidReceiveMemoryWarning
callback. The application must free as much memory as possible or risk being terminated, see
how to respond to memory warnings.
§Others
- macOS / Wayland / Windows / Orbital: Unsupported.
Implementations§
Trait Implementations§
source§impl<T: PartialEq + 'static> PartialEq for Event<T>
impl<T: PartialEq + 'static> PartialEq for Event<T>
impl<T: 'static> StructuralPartialEq for Event<T>
Auto Trait Implementations§
impl<T> Freeze for Event<T>where
T: Freeze,
impl<T> RefUnwindSafe for Event<T>where
T: RefUnwindSafe,
impl<T> Send for Event<T>where
T: Send,
impl<T> Sync for Event<T>where
T: Sync,
impl<T> Unpin for Event<T>where
T: Unpin,
impl<T> UnwindSafe for Event<T>where
T: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.