Overview
Purpose: maps trackpad events (or horizontal mouse wheel events) to swipe gestures. This allows, for example, users of laptops with trackpads to manipulate a view or selection with a trackpad swipe. (The exact user interface gesture depends on the OS and its configuration. A common OS configuration requires the user to drag on the trackpad with two fingers to perform a swipe.)
This mixin works at the beginning of the Elix render pipeline. In response to touch events, the mixin may call methods on the component or call setState
directly.
events ➞ methods → setState → render DOM → post-render
Expects the component to provide:
setState
method compatible withReactiveMixin
's setState.swipeLeft
andswipeRight
methods. If the component defines these, the mixin will call them if the user makes a full-width drag to the left or right, respectively.
Provides the component with:
[internal.state].swipeFraction
member expressing how far through a swipe the user is currently is. See below.
Usage
import TrackpadSwipeMixin from "elix/src/base/TrackpadSwipeMixin.js";
class MyElement extends TrackpadSwipeMixin(HTMLElement) {}
See also the related TouchSwipeMixin, which is like TrackpadSwipeMixin
, but for touch devices instead of trackpads. Both TouchSwipeMixin
and TrackpadSwipeMixin
are designed to work with SwipeCommandsMixin to reveal commands behind list items when the user swipes.
Examples
TrackpadSwipeMixin
reveals commands behind these list items on a trackpad swipe
⇲
[internal.state].swipeFraction
This mixin calculates a state member [internal.state].swipeFraction
to track the state of a trackpad swipe operation. If no swipe is in progress, this value is null. If a swipe is in progress, then swipeFraction
holds a real number expressing the distance the user has swiped, divided by the width of the element being swiped (which, by default is the element itself). This value is negative for swipes to the left, and positive for swipes to the right.
Example: If the user touches an element with TrackpadSwipeMixin
, and drags to the left one half of the element's width, then swipeFraction
will be equal to -0.5.
The related TouchSwipeMixin may also set [internal.state].swipeFraction
, adhering to an identical definition.
Full-width drag operations
Trackpad operations may complete while the user is still dragging. If the user drags an item a full element width to the left (swipeFraction
is less or equal to -1) or to the right (swipeFraction
is greater than or equal to 1), the mixin interprets this as completing a drag. The mixin will invoke the component's swipeLeft
or swipeRight
method (if defined).
You can use TrackpadSwipeMixin
with SwipeDirectionMixin to map these swipeLeft and swipeRight calls to directional navigations. You can additionally map directional navigation operations to selection calls using DirectionCursorMixin. Elix's carousel components like SlidingPages use this chain of mixins to turn flick gestures into changes in the carousel's selection:
swipeLeft
→internal.goRight
→selectNext
swipeRight
→internal.goLeft
→selectPrevious
Trackpad timeouts
If the user slows or stops their trackpad drag operation, the operation will timeout. If the swipe is over halfway to the left or right, the mixin will invoke swipeLeft
or swipeRight
respectively. Otherwise, the mixin will cancel the drag and set [internal.state].swipeFraction
to null.
API
Used by classes Carousel, CarouselSlideshow, CarouselWithThumbnails, Drawer, DrawerWithGrip, PlainCarousel, PlainCarouselSlideshow, PlainCarouselWithThumbnails, PlainDrawer, PlainDrawerWithGrip, PlainSlideshowWithPlayControls, PlainSlidingPages, SlideshowWithPlayControls, and SlidingPages.
swipe Target property
See swipeTarget.
Type: HTMLElement