Struct PointerSample

#[non_exhaustive]
pub struct PointerSample { /* private fields */ }

Optional high-fidelity data associated with a pointer event.

Mouse events normally provide only id, source, and position. Touch and pen adapters can additionally supply normalized pressure, tilt, twist, and contact size without leaking provider-specific event types into the runtime. is_primary identifies the primary pointer for its source. Providers that can expose multiple simultaneous pointers should use PointerSample::new_with_primary or PointerSample::with_primary instead of relying on the compatibility default of PointerSample::new.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::MOUSE, PointerSource::Mouse, Point::new(1.0, 2.0))?;
assert!(sample.is_primary());

Implementations

impl PointerSample

pub fn new( id: PointerId, source: PointerSource, position: Point, ) -> Result<Self, PointerSampleError>

Creates a sample for the compatibility single-pointer path.

This constructor keeps the original three-argument API and treats the sample as primary. Multi-pointer providers should use Self::new_with_primary so secondary pointers are represented explicitly.

Errors

Returns PointerSampleError::NonFinitePosition unless both logical position coordinates are finite.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::MOUSE, PointerSource::Mouse, Point::new(1.0, 2.0))?;
assert_eq!(sample.position(), Point::new(1.0, 2.0));

pub fn new_with_primary( id: PointerId, source: PointerSource, position: Point, is_primary: bool, ) -> Result<Self, PointerSampleError>

Creates a sample with an explicit primary-pointer classification.

Optional pressure, tilt, twist, and contact size start as None, and activation starts as ActivationKind::Normal.

Errors

Returns PointerSampleError::NonFinitePosition unless both logical position coordinates are finite.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new_with_primary(PointerId::new(2), PointerSource::Touch, Point::new(1.0, 2.0), false)?;
assert!(!sample.is_primary());

pub const fn id(&self) -> PointerId

Returns the provider-neutral pointer identifier.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(2), PointerSource::Touch, Point::default())?;
assert_eq!(sample.id(), PointerId::new(2));

pub const fn source(&self) -> PointerSource

Returns the physical source classification.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(2), PointerSource::Pen, Point::default())?;
assert_eq!(sample.source(), PointerSource::Pen);

pub const fn position(&self) -> Point

Returns the logical window position.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::MOUSE, PointerSource::Mouse, Point::new(3.0, 4.0))?;
assert_eq!(sample.position(), Point::new(3.0, 4.0));

pub const fn is_primary(&self) -> bool

Returns whether this is the primary pointer for its source.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
assert!(PointerSample::new(PointerId::MOUSE, PointerSource::Mouse, Point::default())?.is_primary());

pub const fn pressure(&self) -> Option<f32>

Returns normalized pressure, or None when the provider omitted it.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Pen, Point::default())?.with_pressure(0.5)?;
assert_eq!(sample.pressure(), Some(0.5));

pub const fn tilt(&self) -> Option<(f32, f32)>

Returns (x, y) pen tilt in degrees, or None when unavailable.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Pen, Point::default())?.with_tilt(10.0, -5.0)?;
assert_eq!(sample.tilt(), Some((10.0, -5.0)));

pub const fn twist(&self) -> Option<f32>

Returns clockwise pen twist in 0.0..360.0 degrees, when available.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Pen, Point::default())?.with_twist(45.0)?;
assert_eq!(sample.twist(), Some(45.0));

pub const fn contact_size(&self) -> Option<Size>

Returns logical contact width/height, or None when unavailable.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point, Size};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Touch, Point::default())?.with_contact_size(Size::new(4.0, 5.0))?;
assert_eq!(sample.contact_size(), Some(Size::new(4.0, 5.0)));

pub const fn activation(&self) -> ActivationKind

Returns whether this gesture may activate controls.

Examples

use ailloli_ui_core::{event::{ActivationKind, PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::MOUSE, PointerSource::Mouse, Point::default())?.with_activation(ActivationKind::FocusOnly);
assert_eq!(sample.activation(), ActivationKind::FocusOnly);

pub fn with_pressure(self, pressure: f32) -> Result<Self, PointerSampleError>

Sets normalized pressure in the inclusive range 0.0..=1.0.

Errors

Returns PointerSampleError::InvalidPressure for non-finite or out-of-range input.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Pen, Point::default())?.with_pressure(0.75)?;
assert_eq!(sample.pressure(), Some(0.75));

pub fn with_tilt(self, x: f32, y: f32) -> Result<Self, PointerSampleError>

Sets pen tilt components in inclusive degrees -90.0..=90.0.

Errors

Returns PointerSampleError::InvalidTilt if either component is non-finite or outside the supported range.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Pen, Point::default())?.with_tilt(20.0, -20.0)?;
assert_eq!(sample.tilt(), Some((20.0, -20.0)));

pub fn with_twist(self, twist: f32) -> Result<Self, PointerSampleError>

Sets clockwise pen twist in the half-open range 0.0..360.0 degrees.

Errors

Returns PointerSampleError::InvalidTwist for non-finite input or for a value below zero or at least 360 degrees.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Pen, Point::default())?.with_twist(180.0)?;
assert_eq!(sample.twist(), Some(180.0));

pub fn with_contact_size(self, size: Size) -> Result<Self, PointerSampleError>

Sets the non-negative contact size in logical pixels.

Zero width or height is valid and distinct from None.

Errors

Returns PointerSampleError::InvalidContactSize for non-finite or negative dimensions.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point, Size};
let sample = PointerSample::new(PointerId::new(1), PointerSource::Touch, Point::default())?.with_contact_size(Size::new(4.0, 5.0))?;
assert_eq!(sample.contact_size(), Some(Size::new(4.0, 5.0)));

pub const fn with_activation(self, activation: ActivationKind) -> Self

Replaces the control-activation classification.

Examples

use ailloli_ui_core::{event::{ActivationKind, PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::MOUSE, PointerSource::Mouse, Point::default())?.with_activation(ActivationKind::FocusOnly);
assert_eq!(sample.activation(), ActivationKind::FocusOnly);

pub const fn with_primary(self, is_primary: bool) -> Self

Overrides the primary-pointer classification.

Examples

use ailloli_ui_core::{event::{PointerId, PointerSample, PointerSource}, Point};
let sample = PointerSample::new(PointerId::new(2), PointerSource::Touch, Point::default())?.with_primary(false);
assert!(!sample.is_primary());

Trait Implementations

impl Clone for PointerSample

fn clone(&self) -> PointerSample

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for PointerSample

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

Formats the value using the given formatter.

impl PartialEq for PointerSample

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for PointerSample

impl StructuralPartialEq for PointerSample