Enum WindowEvent

Source

#[non_exhaustive]pub enum WindowEvent {
Show 31 variants    ActivationTokenDone {
        serial: AsyncRequestSerial,
        token: ActivationToken,
    },
    SurfaceResized(PhysicalSize<u32>),
    Moved(PhysicalPosition<i32>),
    CloseRequested,
    Destroyed,
    DragEntered {
        id: DataTransferId,
        position: Option<PhysicalPosition<f64>>,
    },
    DragPosition {
        id: DataTransferId,
        position: PhysicalPosition<f64>,
        proposed_action: Option<DndAction>,
    },
    DragDropped {
        id: DataTransferId,
        proposed_action: Option<DndAction>,
    },
    DragLeft {
        id: DataTransferId,
    },
    DataTransferReceived {
        id: DataTransferId,
        serial: AsyncRequestSerial,
        value: Arc<dyn TypedData>,
    },
    OutgoingDragDropped {
        id: DataTransferId,
        action: Option<DndAction>,
    },
    OutgoingDragCanceled {
        id: DataTransferId,
    },
    Focused(bool),
    KeyboardInput {
        device_id: Option<DeviceId>,
        event: KeyEvent,
        is_synthetic: bool,
    },
    ModifiersChanged(Modifiers),
    Ime(Ime),
    PointerMoved {
        device_id: Option<DeviceId>,
        position: PhysicalPosition<f64>,
        primary: bool,
        source: PointerSource,
    },
    PointerEntered {
        device_id: Option<DeviceId>,
        position: PhysicalPosition<f64>,
        primary: bool,
        kind: PointerKind,
    },
    PointerLeft {
        device_id: Option<DeviceId>,
        position: Option<PhysicalPosition<f64>>,
        primary: bool,
        kind: PointerKind,
    },
    MouseWheel {
        device_id: Option<DeviceId>,
        delta: MouseScrollDelta,
        phase: TouchPhase,
    },
    PointerButton {
        device_id: Option<DeviceId>,
        state: ElementState,
        position: PhysicalPosition<f64>,
        primary: bool,
        button: ButtonSource,
        is_macos_activation_click: bool,
    },
    HoldGesture {
        device_id: Option<DeviceId>,
        phase: TouchPhase,
    },
    PinchGesture {
        device_id: Option<DeviceId>,
        delta: f64,
        phase: TouchPhase,
    },
    PanGesture {
        device_id: Option<DeviceId>,
        delta: PhysicalPosition<f32>,
        phase: TouchPhase,
    },
    DoubleTapGesture {
        device_id: Option<DeviceId>,
    },
    RotationGesture {
        device_id: Option<DeviceId>,
        delta: f32,
        phase: TouchPhase,
    },
    TouchpadPressure {
        device_id: Option<DeviceId>,
        pressure: f32,
        stage: i64,
    },
    ScaleFactorChanged {
        scale_factor: f64,
        surface_size_writer: SurfaceSizeWriter,
    },
    ThemeChanged(Theme),
    Occluded(bool),
    RedrawRequested,
}

Expand description

Describes an event from a Window.

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

§

ActivationTokenDone

The activation token was delivered back and now could be used.

Fields

§serial: AsyncRequestSerial

§token: ActivationToken

§

SurfaceResized(PhysicalSize<u32>)

The size of the window’s surface has changed.

Contains the new dimensions of the surface (can also be retrieved with Window::surface_size).

This event will not necessarily be emitted upon window creation, query Window::surface_size if you need to determine the surface’s initial size.

§

Moved(PhysicalPosition<i32>)

The position of the window has changed.

Contains the window’s new position in desktop coordinates (can also be retrieved with Window::outer_position).

§Platform-specific

iOS / Android / Web / Wayland: Unsupported.

§

CloseRequested

The window has been requested to close.

§

Destroyed

The window has been destroyed.

§

DragEntered

A drag operation has entered the window.

The user can use the id to read information about the incoming dragged data, and report whether the operation is accepted or rejected back to the operating system (see crate::event_loop::ActiveEventLoop::set_valid_dnd_actions).

To read the data being dragged, see crate::event_loop::ActiveEventLoop::fetch_data_transfer.

Fields

§id: DataTransferId

ID of the data transfer object, see crate::event_loop::ActiveEventLoop::data_transfer.

§position: Option<PhysicalPosition<f64>>

(x,y) coordinates in pixels relative to the top-left corner of the window.

May be negative on some platforms if something is dragged over a window’s decorations (title bar, frame, etc).

Some platforms will provide this on enter, others do not. If crate::event_loop::ActiveEventLoop::set_valid_dnd_actions is never called, the default state is for the drag operation to be rejected. The position is provided here when available to allow the application to accept a drag operation as soon as possible, preventing the cursor from flickering from rejected to accepted.

§

DragPosition

The position of an ongoing drag operation has changed.

Fields

§id: DataTransferId

ID of the data transfer object, see crate::event_loop::ActiveEventLoop::data_transfer.

§position: PhysicalPosition<f64>

(x,y) coordinates in pixels relative to the top-left corner of the window.

May be negative on some platforms if something is dragged over a window’s decorations (title bar, frame, etc).

§proposed_action: Option<DndAction>

The drag action proposed by the OS, based on the actions supplied in crate::event_loop::ActiveEventLoop::set_valid_dnd_actions, the actions available on the source, and the held modifier keys.

This may be None if the backend has not supplied a valid action. On some platforms (in particular, X11), the application is only informed of the proposed action once the operation completes.

§

DragDropped

A drag operation has dropped file(s) on the window.

Fields

§id: DataTransferId

ID of the data transfer object, see crate::event_loop::ActiveEventLoop::data_transfer.

§proposed_action: Option<DndAction>

The drag action proposed by the OS, based on the actions supplied in crate::event_loop::ActiveEventLoop::set_valid_dnd_actions, the actions available on the source, and the held modifier keys.

This may be None if the backend has not supplied a valid action. This is different from the drag being canceled: the drag completed successfully, we just don’t know what action was selected.

§

DragLeft

A drag operation has been canceled or left the window.

Fields

§id: DataTransferId

ID of the data transfer object, see crate::event_loop::ActiveEventLoop::data_transfer.

§

DataTransferReceived

Data is available for a specific fetch request, see fetch_data_transfer.

While winit makes a best effort to only send this event precisely once, on some platforms it may not be possible to uniquely determine the window that should receive it. In these cases, winit may dispatch the event to all windows that have access to the data transfer. If your application should only process this event once per data transfer, the serial field can be used to deduplicate it.

Fields

§id: DataTransferId

ID of the data transfer object, see crate::event_loop::ActiveEventLoop::data_transfer.

§serial: AsyncRequestSerial

Serial returned from fetch_data_transfer.

§value: Arc<dyn TypedData>

The data for the transfer, with a specific type.

§

OutgoingDragDropped

A drag operation started with start_drag has been dropped.

Fields

§id: DataTransferId

The ID returned from start_drag

§action: Option<DndAction>

The operation selected by the drop destination.

This may be None if the backend has not supplied a valid action. This is different from the drag being canceled: the drag completed successfully, we just don’t know what action was selected.

§

OutgoingDragCanceled

A drag operation started with start_drag has been canceled.

Fields

§id: DataTransferId

The ID returned from start_drag

§

Focused(bool)

The window gained or lost focus.

The parameter is true if the window has gained focus, and false if it has lost focus.

Windows are unfocused upon creation, but will usually be focused by the system soon afterwards.

§

KeyboardInput

An event from the keyboard has been received.

§Platform-specific

Windows: The shift key overrides NumLock. In other words, while shift is held down, numpad keys act as if NumLock wasn’t active. When this is used, the OS sends fake key events which are not marked as is_synthetic.
iOS: Unsupported.

Fields

§device_id: Option<DeviceId>

§event: KeyEvent

§is_synthetic: bool

If true, the event was generated synthetically by winit in one of the following circumstances:

Synthetic key press events are generated for all keys pressed when a window gains focus. Likewise, synthetic key release events are generated for all keys pressed when a window goes out of focus. Currently, this is only functional on X11 and Windows

Otherwise, this value is always false.

§

ModifiersChanged(Modifiers)

The keyboard modifiers have changed.

§

Ime(Ime)

An event from an input method.

Note: You have to explicitly enable this event using Window::set_ime_allowed.

§Platform-specific

iOS / Android / Web / Orbital: Unsupported.

§

PointerMoved

The pointer has moved on the window.

Should be emitted regardless of window focus.

Fields

§device_id: Option<DeviceId>

§position: PhysicalPosition<f64>

(x,y) coordinates in pixels relative to the top-left corner of the window. Because the range of this data is limited by the display area and it may have been transformed by the OS to implement effects such as pointer acceleration, it should not be used to implement non-pointer-like interactions such as 3D camera control. For that, consider DeviceEvent::PointerMotion.

§Platform-specific

Web: Doesn’t take into account CSS border, padding, or transform.

§primary: bool

Indicates whether the event is created by a primary pointer.

A pointer is considered primary when it’s a mouse, the first finger in a multi-touch interaction, or an unknown pointer source.

§source: PointerSource

§

PointerEntered

The pointer has entered the window.

Should be emitted regardless of window focus.

Fields

§device_id: Option<DeviceId>

§position: PhysicalPosition<f64>

The position of the pointer when it entered the window.

§Platform-specific

**Orbital: Always emits (0., 0.).
Web: Doesn’t take into account CSS border, padding, or transform.

§primary: bool

Indicates whether the event is created by a primary pointer.

A pointer is considered primary when it’s a mouse, the first finger in a multi-touch interaction, or an unknown pointer source.

§kind: PointerKind

§

PointerLeft

The pointer has left the window.

Should be emitted regardless of window focus.

Fields

§device_id: Option<DeviceId>

§position: Option<PhysicalPosition<f64>>

The position of the pointer when it left the window. The position reported can be outside the bounds of the window.

§Platform-specific

Orbital/Windows: Always emits None.
Web: Doesn’t take into account CSS border, padding, or transform.

§primary: bool

Indicates whether the event is created by a primary pointer.

A pointer is considered primary when it’s a mouse, the first finger in a multi-touch interaction, or an unknown pointer source.

§kind: PointerKind

§

MouseWheel

A mouse wheel movement or touchpad scroll occurred.

Fields

§device_id: Option<DeviceId>

§delta: MouseScrollDelta

§phase: TouchPhase

§

PointerButton

An mouse button press has been received.

Fields

§device_id: Option<DeviceId>

§state: ElementState

§position: PhysicalPosition<f64>

The position of the pointer when the button was pressed.

§Platform-specific

**Orbital: Always emits (0., 0.).
Web: Doesn’t take into account CSS border, padding, or transform.

§primary: bool

Indicates whether the event is created by a primary pointer.

A pointer is considered primary when it’s a mouse, the first finger in a multi-touch interaction, or an unknown pointer source.

§button: ButtonSource

§is_macos_activation_click: bool

Whether this event is part of the click that activated an otherwise inactive window.

On macOS, AppKit normally consumes the click that brings a window forward without delivering it as a regular mouse event (controlled by acceptsFirstMouse:). Winit always delivers it, but tags both the activating press and its matching release with this flag so applications can short-circuit the whole gesture with a single check — e.g. ignore activation clicks for destructive or button-like targets while accepting them for low-risk actions (selection, scrolling).

§Platform-specific

Only available on macOS. Always false on every other platform.
Only ever true for the left mouse button. Intervening drag motion (delivered as WindowEvent::PointerMoved) is not tagged; applications that care about drags during the activation gesture must track that state themselves.

§

HoldGesture

Multi-finger hold gesture on the touchpad or touchscreen without movement.

The phase field indicates the lifecycle of the hold gesture:

Started: One or more fingers are in contact with the touchpad/touchscreen.
Ended: All fingers have been lifted from the touchpad/touchscreen.
Cancelled: The hold gesture was interrupted, for example when another finger touches the touchpad (causing a new Started event with more fingers), or when movement begins and transitions to other gestures like pinch, pan, or rotation.

§Platform-specific

Only available on Wayland.

Fields

§device_id: Option<DeviceId>

§phase: TouchPhase

§

PinchGesture

Two-finger pinch gesture, often used for magnification.

§Platform-specific

Only available on macOS, iOS, and Wayland.
On iOS, not recognized by default. It must be enabled when needed.

Fields

§device_id: Option<DeviceId>

§delta: f64

Positive values indicate magnification (zooming in) and negative values indicate shrinking (zooming out).

This value may be NaN.

§phase: TouchPhase

§

PanGesture

N-finger pan gesture

§Platform-specific

Only available on iOS and Wayland.
On iOS, not recognized by default. It must be enabled when needed.

Fields

§device_id: Option<DeviceId>

§delta: PhysicalPosition<f32>

Change in pixels of pan gesture from last update.

§phase: TouchPhase

§

DoubleTapGesture

Double tap gesture.

On a Mac, smart magnification is triggered by a double tap with two fingers on the trackpad and is commonly used to zoom on a certain object (e.g. a paragraph of a PDF) or (sort of like a toggle) to reset any zoom. The gesture is also supported in Safari, Pages, etc.

The event is general enough that its generating gesture is allowed to vary across platforms. It could also be generated by another device.

Unfortunately, neither Windows nor Wayland support this gesture or any other gesture with the same effect.

§Platform-specific

Only available on macOS 10.8 and later, and iOS.
On iOS, not recognized by default. It must be enabled when needed.

Fields

§device_id: Option<DeviceId>

§

RotationGesture

Two-finger rotation gesture.

Positive delta values indicate rotation counterclockwise and negative delta values indicate rotation clockwise.

§Platform-specific

Only available on macOS, iOS, and Wayland.
On iOS, not recognized by default. It must be enabled when needed.

Fields

§device_id: Option<DeviceId>

§delta: f32

change in rotation in degrees

§phase: TouchPhase

§

TouchpadPressure

Touchpad pressure event.

§Platform-specific

macOS: Only supported on Apple forcetouch-capable macbooks.
Android / iOS / Wayland / X11 / Windows / Orbital / Web: Unsupported.

Fields

§device_id: Option<DeviceId>

§pressure: f32

Value between 0 and 1 representing how hard the touchpad is being pressed.

§stage: i64

Represents the click level.

§

ScaleFactorChanged

The window’s scale factor has changed.

The following user actions can cause DPI changes:

Changing the display’s resolution.
Changing the display’s scale factor (e.g. in Control Panel on Windows).
Moving the window to a display with a different scale factor.

To update the window size, use the provided SurfaceSizeWriter handle. By default, the window is resized to the value suggested by the OS, but it can be changed to any value.

This event will not necessarily be emitted upon window creation, query Window::scale_factor if you need to determine the window’s initial scale factor.

For more information about DPI in general, see the dpi crate.

Fields

§scale_factor: f64

§surface_size_writer: SurfaceSizeWriter

Handle to update surface size during scale changes.

See SurfaceSizeWriter docs for more details.

§

ThemeChanged(Theme)

The system window theme has changed.

Applications might wish to react to this to change the theme of the content of the window when the system changes the window theme.

This only reports a change if the window theme was not overridden by Window::set_theme.

§Platform-specific

iOS / Android / X11 / Wayland / Orbital: Unsupported.

§

Occluded(bool)

The window has been occluded (completely hidden from view).

This is different to window visibility as it depends on whether the window is closed, minimised, set invisible, or fully occluded by another window.

§Platform-specific

§iOS

On iOS, the Occluded(false) event is emitted in response to an applicationWillEnterForeground callback which means the application should start preparing its data. The Occluded(true) event is emitted in response to an applicationDidEnterBackground callback which means the application should free resources (according to the iOS application lifecycle).

§Others

Web: Doesn’t take into account CSS border, padding, or transform.
Android / Wayland / Windows / Orbital: Unsupported.

§

RedrawRequested

Emitted when a window should be redrawn.

This gets triggered in a few scenarios:

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

Winit will aggregate duplicate redraw requests into a single event, to help avoid duplicating rendering work.