ui/ Touchable
Application support for gestures.
import Touchable from '@enact/ui/Touchable';
Members
TouchableHigher-Order Component
A higher-order component that provides a consistent set of pointer events -- onDown
, onUp
,
and onTap
-- across mouse and touch interfaces along with support for common gestures including
onFlick
, onDrag
, onHoldStart
, onHold
, and onHoldEnd
.
Note: This HoC passes a number of props to the wrapped component that should be passed to the main DOM node or consumed by the wrapped component.
import Touchable from '@enact/ui/Touchable';
Configuration
Configures the prop name to pass the active state to the wrapped component
Default: null
Properties added to wrapped component
Disables the component.
Default: falseInstance-specific overrides of the drag configuration.
Instance-specific overrides of the flick configuration.
Instance-specific overrides of the hold configuration.
Prevents resuming the touch events and gestures when re-entering the component.
Default: falseEvent handler for 'down' pointer events.
Event handler for a drag gesture.
Event payload includes:
type
- Type of event,'onDrag'
x
- Horizontal position of the drag, relative to the viewporty
- Vertical position of the drag, relative to the viewport
Event handler for the end of a drag gesture.
Event payload includes:
type
- Type of event,'onDragEnd'
Event handler for the start of a drag gesture.
Event payload includes:
type
- Type of event,'onDragStart'
x
- Horizontal position of the drag, relative to the viewporty
- Vertical position of the drag, relative to the viewport
Event handler for a flick gesture.
Event payload includes:
type
- Type of event,'onFlick'
direction
- Primary direction of the flick, either'horizontal'
or'vertical'
velocity
- Velocity of flickvelocityX
- Velocity of flick along te horizontal axisvelocityY
- Velocity of flick along te vertical axis
Event handler for hold pulse events.
Event payload includes:
type
- Type of event,'onHold'
time
- Time, in milliseconds, since the hold began
Event handler for the end of hold events.
Event payload includes:
type
- Type of event,'onHoldEnd'
time
- Time, in milliseconds, since the hold began
Event handler for hold events.
Event payload includes:
type
- Type of event,'onHoldStart'
name
- The name of the hold as configured in the events listtime
- Time, in milliseconds, configured for this hold which may vary slightly from time since the hold began
Event handler for 'move' pointer events.
Event handler for 'tap' pointer events.
Event handler for 'up' pointer events.
configureFunction
configure( cfg )undefined
Configures the global gesture configuration for the application.
Example:
// Updates the `maxMoves`, `moveTolerance`, and `frequency` configurations while retaining the
// current value of all other configurations
configure({
flick: {
maxMoves: 10
},
hold: {
moveTolerance: 32,
frequency: 400
}
});
Each type of gesture has its own set of configuration properties grouped within a separate object keyed by the name of the gesture. Partial configurations may be passed and will be merged with the current configuration.
drag
boxSizing
- The part of the component's box model is used as the bounds of the constraint. Only applies whenglobal
isfalse
.'border-box'
- the default, includes the padding and border but excludes the margin.'content-box'
- excludes the padding, border, and margin.
global
- Whentrue
, drag gestures will continue when leaving the bounds of the component or blurring the component.moveTolerance
- The number of pixels from the start position of the drag that the pointer may move before cancelling the drag. Defaults to16
.
flick
maxDuration
- The amount of time, in milliseconds, to complete a flick gesture before it is cancelled. Defaults to 250.maxMoves
- The number of moves tracked to determine if a flick occurred. Defaults to5
.minVelocity
- The minimum threshold, measured as the change in pixels over the change in time per move, that must be exceeded to generate aonFlick
event.
hold
cancelOnMove
- Whentrue
, the hold is cancelled when moving beyond themoveTolerance
. Defaults tofalse
global
- Whentrue
, hold gestures will continue when leaving the bounds of the component or blurring the component.moveTolerance
- The number of pixels from the start position of the hold that the pointer may move before cancelling the hold. Ignored whencancelOnMove
isfalse
. Defaults to16
.frequency
- The time, in milliseconds, to poll for hold events. Defaults to200
.events
- An array ofonHoldStart
events which each contain aname
andtime
. Thetime
controls the amount of time that must pass before thisonHoldStart
event is fired and should be a multiple offrequency
.
1 Param
- cfg Object
A partial or complete configuration object
Returns
- undefined