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
, onHold
, and onHoldPulse
.
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 events.
Event payload includes:
type
- Type of event,'onHold'
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 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 pulse events
Event payload includes:
type
- Type of event,'onHoldPulse'
time
- Time, in milliseconds, since the hold began
Event handler for 'tap' pointer events
Event handler for 'up' pointer events
configureFunction
configure( cfg )
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 ofonHold
events which each contain aname
andtime
. Thetime
controls the amount of time that must pass before thisonHold
event is fired and should be a multiple offrequency
.
1 Param
- cfg Object
A partial or complete configuration object