#[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
PointerMoved
The pointer moved to the given viewport-local position.
MouseButton
A mouse button was pressed or released.
Wheel
The scroll wheel moved.
Fields
units: ScrollUnitsWhether the delta is in lines or pixels.
Key
A keyboard key changed state.
Fields
key: KeyCodeWhich 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: ButtonStateNew key state.
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
phase: TouchPhaseWhat the contact just did.
position: Vec2Viewport-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.
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
impl ViewportEvent
Sourcepub fn is_contested(&self) -> bool
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.
Sourcepub fn offset_by(&self, origin: Vec2) -> ViewportEvent
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
impl Clone for ViewportEvent
Source§fn clone(&self) -> ViewportEvent
fn clone(&self) -> ViewportEvent
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more