Skip to main content

ViewportEvent

Enum ViewportEvent 

Source
#[non_exhaustive]
pub enum ViewportEvent {
Show 19 variants PointerMoved { position: Vec2, }, MouseButton { button: MouseButton, state: ButtonState, }, Wheel { delta: Vec2, units: ScrollUnits, }, Key { key: KeyCode, state: ButtonState, repeat: bool, logical: Option<char>, }, ModifiersChanged(Modifiers), PointerLeft, FocusLost, Character(char), TrackpadRotate(f32), TrackpadPinch(f32), TrackpadPan(Vec2), Touch { id: TouchId, phase: TouchPhase, position: Vec2, }, RawMotion { delta: Vec2, }, ThemeChanged(Theme), Occluded(bool), FileDropped(PathBuf), FileHovered(PathBuf), FileHoverCancelled, Ime(ImeEvent),
}
Expand description

An event delivered to the viewport input pipeline.

Host applications translate their native windowing events into ViewportEvent values and push them to the OrbitCameraController (or ViewportInput for direct input handling).

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

PointerMoved

The pointer moved to the given viewport-local position.

Fields

§position: Vec2

Viewport-local position in logical pixels, origin at top-left.

§

MouseButton

A mouse button was pressed or released.

Fields

§button: MouseButton

Which button changed state.

§state: ButtonState

New button state.

§

Wheel

The scroll wheel moved.

Fields

§delta: Vec2

Scroll delta. Positive Y = scroll up / zoom in (conventional).

§units: ScrollUnits

Whether the delta is in lines or pixels.

§

Key

A keyboard key changed state.

Fields

§key: KeyCode

Which key changed state, by position: the key in the US-layout A position is KeyCode::A whatever the layout prints on it. Bindings match on this, so WASD stays in place on AZERTY.

§state: ButtonState

New key state.

§repeat: bool

True if the event is a key-repeat (key held down).

§logical: Option<char>

The character the layout gives this key, unshifted and lower case (z for the key labelled Z on any layout), or None for keys that produce no character (arrows, function keys). Match shortcuts such as Ctrl+Z on this to follow the layout.

§

ModifiersChanged(Modifiers)

Modifier key state changed.

§

PointerLeft

The pointer left the viewport area.

This releases every held button. It exists to avoid a button being left stuck down when the pointer goes somewhere the viewport will never hear the release, so it ends any drag in flight.

Send it when the pointer leaves the window, not every time it crosses the viewport’s own edge. A drag whose press landed inside the viewport keeps resolving after the pointer leaves the rect, which is what lets a fast orbit run past the edge; forwarding this event at that boundary throws that away. Setting the pointer ownership in the ViewportContext to Elsewhere is the way to say “the pointer is no longer over us” without ending the drag.

Under a pointer grab it should never be sent at all: a grabbed pointer has no rect to leave, and ending the gesture would end the look session. forward_to_viewport drops it for you under PointerOwnership::Grabbed.

§

FocusLost

The viewport lost keyboard focus.

§

Character(char)

A character was typed (Unicode): the text a key press produced after layout, Shift and dead keys.

winit puts it in KeyEvent::text, and the winit adapter’s translate emits it after the key’s Key event. egui sends it as Event::Text, which the egui adapter’s translate turns into one Character per character. The resolver keeps it only while the viewport owns the keyboard, like a key, and a manipulation session reads its digits, . and - for numeric entry.

§

TrackpadRotate(f32)

Two-finger trackpad rotation gesture.

delta is the change in angle this event, in radians. Positive = counter-clockwise (matches winit’s RotationGesture convention, converted from degrees to radians by the host). egui’s angle convention is the opposite, so its adapter negates; twist therefore turns the same way through either host.

§Platform-specific

Only emitted on macOS (and iOS). Silently unused on Windows and Linux.

§

TrackpadPinch(f32)

Two-finger trackpad pinch (magnify) gesture.

delta is the change in magnification this event, on a log scale: positive = pinch out / zoom in, and 0.0 is no change. This is winit’s PinchGesture convention. A host whose framework reports a multiplicative factor instead (egui’s Event::Zoom, where 1.0 is no change) converts with ln; the adapters do this, so the same physical pinch resolves the same way whichever shell hosts the viewport.

Resolves into NavigationActions::zoom, gated on the pointer being inside the viewport, like the wheel.

§Platform-specific

Only emitted on macOS (and iOS). Silently unused on Windows and Linux.

§

TrackpadPan(Vec2)

Two-finger trackpad pan gesture.

delta is the pan this event in logical points. Resolves into NavigationActions::pan, gated on the pointer being inside the viewport.

§Platform-specific

Only emitted on macOS (and iOS). Silently unused on Windows and Linux.

§

Touch

A touch contact went down, moved, lifted, or was taken away.

One event per contact per change, so a two-finger gesture arrives as two interleaved streams distinguished by id. The viewport tracks the contacts and recognises the gestures itself, rather than taking a host’s derived pinch or pan, so that the same finger movement feels the same whichever shell hosts the viewport.

A host that also synthesises mouse events from touch (most do) should send one or the other, not both, or every gesture counts twice.

Fields

§id: TouchId

Which contact this is.

§phase: TouchPhase

What the contact just did.

§position: Vec2

Viewport-local position in logical pixels, origin at top-left. The same space as PointerMoved, which is what lets the two share the hit-testing an application already has.

§

RawMotion

Raw, unaccelerated relative pointer motion from the input device, not tied to the window or surface. delta is in raw device units. Use this for first-person / mouselook navigation while the cursor is grabbed; the ordinary cursor position comes from PointerMoved.

Fields

§delta: Vec2

Relative motion since the last event, in raw device units.

§

ThemeChanged(Theme)

The OS colour theme changed. A consumer can follow the system light/dark preference (for overlay UI colours, for example).

§

Occluded(bool)

The window’s occlusion state changed. true when the window became fully hidden (behind others, or minimised); false when it is visible again. A consumer can pause rendering while occluded to save power.

§

FileDropped(PathBuf)

A file was dropped onto the window, at the OS level (not viewport-local).

§

FileHovered(PathBuf)

A file is being dragged over the window but not yet dropped. May arrive more than once as the drag moves; a consumer uses it to show a drop target.

§

FileHoverCancelled

A file drag left the window without dropping, cancelling a prior FileHovered.

§

Ime(ImeEvent)

The platform input method reported composition. For text fields; the viewport itself ignores it.

Implementations§

Source§

impl ViewportEvent

Source

pub fn is_contested(&self) -> bool

Whether this event would be claimed by both the viewport and anything drawn over it, so at most one of them may act on it.

A left press, the pointer motion after it, and a touch contact landing are contested: a press-and-move is exactly what a camera orbit, a gizmo drag and a UI drag would all claim, so it has to belong to one of them. Touch is contested for the same reason: a finger is the only pointer a touch device has, so a control that takes the contact takes all of it. Everything else is ambient: the wheel, the other buttons and the modifiers can be acted on by more than one claimant in the same frame. Releases and contact ends are teardown, not claims, and are never contested: a resolver that saw the press must see its release, and one that did not ignores it. A contact’s later moves are left to the resolver, which follows the contacts it saw land.

That asymmetry is deliberate. Withholding the whole event stream whenever something over the viewport holds the pointer is the obvious implementation and it fails in the most visible place: the moment the cursor crosses a gizmo handle, scrolling stops zooming, which is exactly where someone is most likely to scroll.

The set is fixed and does not consult the active bindings. Right and middle presses stay ambient even though the default scheme binds them to camera navigation, because chrome overwhelmingly uses the primary button. The resolver starts a drag from one only when it arrives while the viewport owns the input, so a right press on chrome over the viewport does not orbit.

Used by forward_to_viewport, which is what most callers want.

Source

pub fn offset_by(&self, origin: Vec2) -> ViewportEvent

This event with any viewport-local position shifted by -origin, and everything else unchanged.

For a viewport embedded in a larger window: the adapters produce positions relative to the window, and the viewport wants them relative to its own rect. Subtract the rect’s top-left corner, in the same logical pixels the positions are already in.

let ev = ViewportEvent::PointerMoved { position: glam::Vec2::new(300.0, 120.0) };
let local = ev.offset_by(glam::Vec2::new(200.0, 100.0));
assert!(matches!(local, ViewportEvent::PointerMoved { position } if position == glam::Vec2::new(100.0, 20.0)));

Worth using rather than matching the position-carrying variants yourself: that list grows (touch contacts joined it), and a host that enumerated it by hand keeps compiling while quietly leaving the new ones in window space. Deltas are not positions and are left alone: the wheel, the trackpad gestures, and raw motion all mean the same thing wherever the rect is.

Trait Implementations§

Source§

impl Clone for ViewportEvent

Source§

fn clone(&self) -> ViewportEvent

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for ViewportEvent

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

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,

Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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.