Overview
Purpose: maps touch events to swipe gestures.
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, orswipeDown
andswipeUp
methods. If the component defines these, the mixin will call them if the user makes a flick (fast swipe) gesture to the left/right or down/up, respectively.
Provides the component with:
[internal.state].swipeAxis
member that is either "horizontal" (default) or "vertical", indicating in which axis swipes should be tracked.[internal.state].swipeFraction
member expressing how far through a swipe the user is currently is. See below.
Usage
import TouchSwipeMixin from "elix/src/base/TouchSwipeMixin.js";
class MyElement extends TouchSwipeMixin(HTMLElement) {}
See also the related TrackpadSwipeMixin, which is like TouchSwipeMixin
, but for trackpads instead of touch devices. Both TouchSwipeMixin
and TrackpadSwipeMixin
are designed to work with SwipeCommandsMixin to reveal commands behind list items when the user swipes.
Examples
TouchSwipeMixin
reveals commands behind these list items on a touch swipe
⇲
[internal.state].swipeFraction
This mixin calculates a state member [internal.state].swipeFraction
to track the state of a touch 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 or up, and positive for swipes to the right or down.
Example: If the user touches an element with TouchSwipeMixin
, and drags to the left one half of the element's width, then swipeFraction
will be equal to -0.5.
The related TrackpadSwipeMixin may also set [internal.state].swipeFraction
, adhering to an identical definition.
Completing a swipe
When the user lifts their finger to complete a swipe, the mixin inspects the current value of [internal.state].swipeFraction
:
- If the drag is over halfway to the left/up (
swipeFraction
less than -0.5), the mixin will invoke the component'sswipeLeft
/swipeUp
method (if defined). - Conversely, if the drag ends over halfway to the right/down (
swipeFraction
greater than 0.5), the mixin will invokeswipeRight
/swipeDown
(if defined).
In all cases, when the drag completes, the mixin will set [internal.state].swipeFraction
to null.
Flick gestures
If the user ends a swipe at high speed, the gesture is interpreted as a flick. If the flick is to the left, the mixin will invoke the component's swipeLeft
method (if defined). Conversely, if the flick is to the right, the mixin will invoke swipeRight
(if defined).
You can use TouchSwipeMixin
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:
internal.swipeLeft
→internal.goRight
→selectNext
internal.swipeRight
→internal.goLeft
→selectPrevious
API
Used by classes Carousel, CarouselSlideshow, CarouselWithThumbnails, Drawer, DrawerWithGrip, PlainCarousel, PlainCarouselSlideshow, PlainCarouselWithThumbnails, PlainDrawer, PlainDrawerWithGrip, PlainPullToRefresh, PlainSlideshowWithPlayControls, PlainSlidingPages, PullToRefresh, SlideshowWithPlayControls, and SlidingPages.
swipe Target property
See swipeTarget.
Type: HTMLElement