Struct PointerTable 

pub struct PointerTable { /* private fields */ }

The live pointers, plus the primary and hover-owner elections.

See the module docs for what those two roles mean and why they are not the same thing as PointerInfo::primary.

Implementations

impl PointerTable

pub const DEFAULT_CAP: usize = 10

How many pointers the table holds at once.

Ten: the maximum simultaneous contacts a Windows digitiser and a Wayland wl_touch seat both report. An eleventh arrival is refused at begin rather than evicting one of the ten, because evicting a contact mid-gesture is how a pinch turns into a fling.

pub fn new() -> Self

An empty table with the default cap.

pub fn with_cap(cap: usize) -> Self

An empty table that holds at most cap pointers. For tests that want to reach the cap without simulating ten fingers.

pub fn cap(&self) -> usize

The cap this table was built with.

pub fn get(&self, id: PointerId) -> Option<&PointerEntry>

The entry for id, if that pointer is live.

pub fn get_mut(&mut self, id: PointerId) -> Option<&mut PointerEntry>

Mutable access to the entry for id, if that pointer is live.

pub fn begin(&mut self, sample: &PointerSample) -> Option<PointerId>

Admit sample’s pointer, creating its entry on first sight and refreshing it afterwards.

Returns None — and traces the refusal — when the sample must not be dispatched at all:

• the backend flagged the contact as a palm (PointerInfo::palm), or
• the table is full (DEFAULT_CAP).

A pointer already in the table is always refreshed, cap or no cap: the cap bounds how many pointers exist, never how many samples an admitted pointer may send.

pub fn would_admit(&self, info: &PointerInfo) -> bool

Whether begin would accept info, without touching the table — and tracing the refusal, since a dropped sample that leaves no evidence is the hardest input bug there is.

The dispatcher asks this before it lowers a sample onto an event, so a refused pointer produces no event at all rather than one that is later discovered to have no entry behind it.

pub fn admit( &mut self, info: PointerInfo, position: Point, is_down: bool, ) -> Option<PointerId>

The primitive behind begin, for the legacy WidgetEvent path, which has no PointerSample to hand.

is_down records position as the entry’s down_position.

pub fn end(&mut self, id: PointerId) -> Option<PointerEntry>

Forget id, returning its entry if it was live.

Called for a contact’s Up or Cancel. A hovering-capable pointer is not ended by an Up — a mouse that releases a button is still there, still hovering, and its entry is what every legacy singular accessor reads.

pub fn primary(&self) -> Option<&PointerEntry>

Teksilo’s single pointer: the one backing the legacy singular accessors. A mouse is preferred; failing that, the oldest live pointer.

Not to be confused with PointerInfo::primary — see the module docs.

pub fn hover_owner(&self) -> Option<&PointerEntry>

The most recent hovering-capable pointer, if any is live.

Hover, enter/leave, the cursor and tooltip dwell all follow this pointer. A touch contact is never it.

pub fn hover_owner_mut(&mut self) -> Option<&mut PointerEntry>

Mutable access to the hover owner’s entry.

pub fn hover_owner_id(&self) -> Option<PointerId>

The hover owner’s id, without borrowing its entry.

pub fn primary_id(&self) -> Option<PointerId>

The primary pointer’s id, without borrowing its entry.

pub fn iter(&self) -> impl Iterator<Item = &PointerEntry> + '_

Every live pointer, oldest first.

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut PointerEntry> + '_

Every live pointer, mutably, oldest first.

pub fn len(&self) -> usize

How many live pointers there are, hovering or not.

pub fn is_empty(&self) -> bool

Whether no pointer is live.

pub fn contact_count(&self) -> usize

How many live pointers are touching the surface — every contact, plus any hovering-capable pointer with a button held. This is the number a multi-touch recognizer counts fingers with; it is 0 for a resting mouse and 2 for a two-finger pinch.

pub fn contains(&self, id: PointerId) -> bool

Whether id names a live pointer.

pub fn retain_active(&mut self, arena: &WidgetArena)

Scrub widget references that no longer name an active node.

A rebuild mints fresh ids, so a hover target, a capture or a hover_within ancestor recorded before it can be dangling afterwards — and a dangling capture swallows every later Move and Up, because dispatch refuses an inactive target. Called from the tree’s post-layout revalidation after it has run the hover-owner’s own signal-firing recovery, so this is the sweep for every other pointer.

pub fn release_captures_of(&mut self, widget: WidgetId)

Release every capture held on widget — it is going away, and a capture that outlives its owner strands the pointer.

pub fn claim_hover_owner(&mut self, id: PointerId) -> Option<PointerId>

Hand the hover-owner role to id, reporting the pointer that lost it.

Called when a hovering-capable pointer produces a sample: the later sample wins, and the caller sends the displaced owner a PointerLeave. A contact is refused outright — it can never own hover — and so is a pointer that is not live.

Trait Implementations

impl Clone for PointerTable

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PointerTable

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

Formats the value using the given formatter.

impl Default for PointerTable

fn default() -> Self

Returns the “default value” for a type.