Struct PointerSequence 

pub struct PointerSequence { /* private fields */ }

Everything the tree knows about one press: who is competing for it, and who won.

Lives in PointerEntry::sequence for as long as the pointer is down. The ordered decision procedure this type is the state of is written out in docs/events-and-gestures.md §4.2 and in this module’s own header.

Implementations

impl PointerSequence

pub fn new( pointer: PointerInfo, path: Vec<WidgetId>, touch_action: TouchAction, dead_zone_boundary: Option<WidgetId>, origin: Point, started_at: EventTime, ) -> Self

Open a sequence for pointer’s press at origin.

path runs target → root and is frozen: a rebuild mid-gesture cannot change who was competing for a press that has already started.

pub fn pointer(&self) -> PointerInfo

Which pointer this sequence follows.

pub fn path(&self) -> &[WidgetId]

The frozen hit path, target → root.

pub fn touch_action(&self) -> TouchAction

The TouchAction frozen at press — the intersection of every declaration from the root down to the pressed target.

pub fn dead_zone_boundary(&self) -> Option<WidgetId>

The innermost gesture_dead_zone node on the frozen path, if any. Nothing at or above it may be enrolled.

pub fn members(&self) -> &[SequenceMember]

Every enrolled member, innermost first.

pub fn winner(&self) -> Option<WidgetId>

The node that owns this press, once one has been decided.

pub fn is_decided(&self) -> bool

Whether arbitration is over.

pub fn capture(&self) -> Option<WidgetId>

The node holding this pointer’s capture, as the sequence recorded it.

pub fn set_capture(&mut self, captor: Option<WidgetId>)

Record who holds the capture.

pub fn pressed_owner(&self) -> Option<WidgetId>

The node whose gesture arena took the press — the tap owner, when the press was not claimed by anything else.

pub fn set_pressed_owner(&mut self, owner: Option<WidgetId>)

Record the node whose gesture arena took the press.

pub fn press_origin(&self) -> Point

Where the press landed.

pub fn last_position(&self) -> Point

Where the pointer was at its most recent sample.

pub fn set_last_position(&mut self, position: Point)

Record the pointer’s current position.

pub fn started_at(&self) -> EventTime

When the press landed, on the tree’s input timeline.

pub fn taps_cancelled(&self) -> bool

Whether the press has already been told it is no longer a tap.

The cancel_taps revocation fires once per press: it resets the node’s TapStreak, and repeating it on every subsequent move would keep clearing state a live drag may still want.

pub fn set_taps_cancelled(&mut self)

Record that the tap family has been revoked for this press.

pub fn is_terminating(&self) -> bool

Whether the sequence is inside its own terminal dispatch — set while the Up that ends it is being delivered, so a teardown triggered from a handler cannot cancel a press that has already completed.

pub fn set_terminating(&mut self, terminating: bool)

Mark the sequence as inside its terminal dispatch.

pub fn travel(&self) -> f32

How far the pointer has travelled from the press point.

pub fn travel_on(&self, axis: Axis) -> f32

How far the pointer has travelled along one axis.

pub fn latch_slop(&self, profile: &GestureProfile) -> f32

The slop a positional member of this sequence latches at.

profile.drag_slop in every configuration except a direct pointer under a frozen TouchAction::NONE, where the subtree has declared that a contact does nothing but manipulate it and the jitter floor is the right threshold. A precise pointer always uses drag_slop: reading slop_precise for it would silently retune every mouse drag latch from 5 dp to 2.

pub fn may_enrol(&self, id: WidgetId) -> bool

Whether id may be enrolled at all: it must be on the frozen path and strictly below the dead-zone boundary.

pub fn has_member(&self, id: WidgetId) -> bool

Whether id is already enrolled.

pub fn enrol(&mut self, id: WidgetId, role: MemberRole) -> bool

Enrol id as a competitor, keeping the member list innermost-first.

Refused — and reported as false — when id is at or above the dead-zone boundary, when it is not on the frozen path, or when it is already enrolled.

pub fn enrol_drag( &mut self, id: WidgetId, role: MemberRole, activation: DragActivation, profile: &GestureProfile, ) -> bool

Enrol a drag member whose DragActivation defers it.

AfterLongPress (and Auto resolving to it) sets eligible_at to the long-press deadline and arms the self-rejection rule: the member is out the moment the press travels past the tap boundary, because that travel is a pan, not a considered grab.

pub fn resolve_activation(&self, activation: DragActivation) -> DragActivation

What DragActivation::Auto means for this sequence.

Immediate for a precise pointer or a subtree that has declared TouchAction::NONE (nothing else can want the press); AfterLongPress for a coarse pointer with an eligible pan competitor, because the axis is already spoken for.

pub fn has_deferred_grab(&self) -> bool

Whether any live member’s activation was deferred to the long-press deadline — i.e. the hold is what arms that member’s grab.

Only enrol_drag sets a member’s eligible_at, and only when resolve_activation answered DragActivation::AfterLongPress, so this is exactly “a grab on this sequence is waiting out the hold”. A mouse never has one: the resolution needs an eligible pan competitor and a mouse enrols none.

Read by the framework to keep one hold from meaning two things — see WidgetTree::long_press_is_a_grab.

pub fn has_eligible_pan(&self) -> bool

Whether any live member is a pan claimant. A mouse never has one: GestureProfile::pan_slop is None for it and PanClaim::devices admits only direct pointers.

pub fn pan_is_eligible( &self, claim: &PanClaim, profile: &GestureProfile, ) -> bool

Whether claim is eligible for this sequence’s pointer at all: the claim must admit the device, the pointer’s profile must have a pan slop, and the frozen TouchAction must permit at least one claimed axis.

pub fn pan_axis_past_slop( &self, claim: &PanClaim, profile: &GestureProfile, ) -> Option<Axis>

The axis a pan member of this sequence would win on, if its travel has passed pan_slop on one the claim and the frozen action both permit.

A diagonal tie resolves by dominant axis — the one that has moved further — so a pan that is mostly vertical scrolls vertically even when both axes are claimed.

pub fn decide(&mut self, id: WidgetId) -> Vec<WidgetId>

Declare id the winner and reject every other live member.

Returns the members that were knocked out, so the caller can cancel each exactly once.

pub fn reject(&mut self, id: WidgetId)

Withdraw id from the running.

pub fn hold(&mut self, id: WidgetId, now: EventTime)

Defer id’s decision until it releases or profile.max_hold elapses.

pub fn release_hold(&mut self, id: WidgetId)

End id’s hold, putting it back in the running.

pub fn expire_holds(&mut self, now: EventTime, profile: &GestureProfile)

Release every hold older than profile.max_hold.

A hold exists so an application recognizer can await an asynchronous decision; leaving one standing would strand the press, so the framework times it out rather than trusting the holder.

pub fn is_held(&self) -> bool

Whether any member is holding.

pub fn next_hold_deadline(&self, profile: &GestureProfile) -> Option<EventTime>

When expire_holds next has work: the earliest instant at which a standing hold reaches profile.max_hold.

A deferred member’s eligible_at is deliberately not a term here. It looks like a sibling deadline and is not one. Nothing happens at that instant: eligibility is never stored, it is re-derived by SequenceMember::is_eligible_at against whatever instant its caller names, and no reader transitions anything on reaching it. Two call sites read it — the arbitration walk, and the arena gate the ordinary bubble and the timer tick share, the one naming the sample being dispatched and the other the tick’s own instant — and each of them only answers a question its caller already had. A press that has sat still past its long_press is already eligible the moment it moves, with no intervening tick, so waking the event loop at eligible_at would buy an idle frame with nothing to do in it. The expiry of a hold is the opposite: it is a stored state transition, and if nobody performs it the hold stands past the duration the framework promises to trust it for.

pub fn revalidate(&mut self, arena: &WidgetArena) -> Vec<WidgetId>

Drop every member whose node is no longer active, reporting them so the caller can cancel each individually.

Run every sample: a rebuild mints fresh ids, and a member left pointing at a destroyed node would either be fed events forever or silently win. The sequence dies only when the winner or the captor dies — see lost_owner.

pub fn lost_owner(&self, arena: &WidgetArena) -> bool

Whether the node that owns this sequence — its winner, or failing that its captor — has gone away. The sequence itself must then be cancelled.

pub fn member_report(&self) -> Vec<(WidgetId, MemberRole, MemberState)>

The role and state of every member, for WidgetTree::sequence_members.

Trait Implementations

impl Clone for PointerSequence

fn clone(&self) -> PointerSequence

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PointerSequence

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

Formats the value using the given formatter.

impl PartialEq for PointerSequence

fn eq(&self, other: &PointerSequence) -> bool

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for PointerSequence