Enum winit::event::Event

pub enum Event<'a, T: 'static> {
    NewEvents(StartCause),
    WindowEvent {
        window_id: WindowId,
        event: WindowEvent<'a>,
    },
    DeviceEvent {
        device_id: DeviceId,
        event: DeviceEvent,
    },
    UserEvent(T),
    Suspended,
    Resumed,
    MainEventsCleared,
    RedrawRequested(WindowId),
    RedrawEventsCleared,
    LoopDestroyed,
}

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

event: WindowEvent<'a>

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

DeviceEvent

Fields

device_id: DeviceId

event: 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 and iOS 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).

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

MainEventsCleared

Emitted when all of the event loop’s input events have been processed and redraw processing is about to begin.

This event is useful as a place to put your code that should be run after all state-changing events have been handled and you want to do stuff (updating state, performing calculations, etc) that happens as the “main body” of your event loop. If your program only draws graphics when something changes, it’s usually better to do it in response to Event::RedrawRequested, which gets emitted immediately after this event. Programs that draw graphics continuously, like most games, can render here unconditionally for simplicity.

RedrawRequested(WindowId)

Emitted after MainEventsCleared when a window should be redrawn.

This gets triggered in two scenarios:

• The OS has performed an operation that’s invalidated the window’s contents (such as resizing the window).
• The application has explicitly requested a redraw via Window::request_redraw.

During each iteration of the event loop, Winit will aggregate duplicate redraw requests into a single event, to help avoid duplicating rendering work.

Mainly of interest to applications with mostly-static graphics that avoid redrawing unless something changes, like most non-game GUIs.

Platform-specific

• macOS / iOS: Due to implementation difficulties, this will often, but not always, be emitted directly inside drawRect:, with neither a preceding MainEventsCleared nor subsequent RedrawEventsCleared. See #2640 for work on this.

RedrawEventsCleared

Emitted after all RedrawRequested events have been processed and control flow is about to be taken away from the program. If there are no RedrawRequested events, it is emitted immediately after MainEventsCleared.

This event is useful for doing any cleanup or bookkeeping work after all the rendering tasks have been completed.

LoopDestroyed

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 an “do on quit” event.

Implementations

impl<'a, T> Event<'a, T>

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

pub fn to_static(self) -> Option<Event<'static, T>>

If the event doesn’t contain a reference, turn it into an event with a 'static lifetime. Otherwise, return None.

Trait Implementations

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

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

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

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

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.

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