Enum winit::event::Event

source ·
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

Fields

§window_id: WindowId

Emitted when the OS sends an event to a winit window.

§

DeviceEvent

Fields

§device_id: DeviceId

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§

source§

impl<T> Event<T>

source

pub fn map_nonuser_event<U>(self) -> Result<Event<U>, Event<T>>

Trait Implementations§

source§

impl<T: Clone + 'static> Clone for Event<T>

source§

fn clone(&self) -> Event<T>

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<T: Debug + 'static> Debug for Event<T>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<T: PartialEq + 'static> PartialEq for Event<T>

source§

fn eq(&self, other: &Event<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl<T: 'static> StructuralPartialEq for Event<T>

Auto Trait Implementations§

§

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Downcast for T
where T: Any,

source§

fn into_any(self: Box<T>) -> Box<dyn Any>

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

Convert 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)

Convert &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)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more