Enact
Edit on GitHub

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
activeProp
String

Configures the prop name to pass the active state to the wrapped component

Default: null
Properties added to wrapped component
disabled
Boolean

Disables the component.

Default: false
dragConfig
Object

Instance-specific overrides of the drag configuration.

See: ui/Touchable.configure
flickConfig
Object

Instance-specific overrides of the flick configuration.

See: ui/Touchable.configure
holdConfig
Object

Instance-specific overrides of the hold configuration.

See: ui/Touchable.configure
noResume
Boolean

Prevents resuming the touch events and gestures when re-entering the component.

Default: false
onDown
Function

Event handler for 'down' pointer events.

onDrag
Function

Event handler for a drag gesture.

Event payload includes:

  • type - Type of event, 'onDrag'

  • x - Horizontal position of the drag, relative to the viewport

  • y - Vertical position of the drag, relative to the viewport

onDragEnd
Function

Event handler for the end of a drag gesture.

Event payload includes:

  • type - Type of event, 'onDragEnd'

onDragStart
Function

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 viewport

  • y - Vertical position of the drag, relative to the viewport

onFlick
Function

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 flick

  • velocityX - Velocity of flick along te horizontal axis

  • velocityY - Velocity of flick along te vertical axis

onHold
Function

Event handler for hold pulse events.

Event payload includes:

  • type - Type of event, 'onHold'

  • time - Time, in milliseconds, since the hold began

onHoldEnd
Function

Event handler for the end of hold events.

Event payload includes:

  • type - Type of event, 'onHoldEnd'

  • time - Time, in milliseconds, since the hold began

onHoldStart
Function

Event handler for hold events.

Event payload includes:

  • type - Type of event, 'onHoldStart'

  • name - The name of the hold as configured in the events list

  • time - Time, in milliseconds, configured for this hold which may vary slightly from time since the hold began

onMove
Function

Event handler for 'move' pointer events.

onTap
Function

Event handler for 'tap' pointer events.

onUp
Function

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 when global is false.

    • 'border-box' - the default, includes the padding and border but excludes the margin.

    • 'content-box' - excludes the padding, border, and margin.

  • global - When true, 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 to 16.

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 to 5.

  • minVelocity - The minimum threshold, measured as the change in pixels over the change in time per move, that must be exceeded to generate a onFlick event.

hold

  • cancelOnMove - When true, the hold is cancelled when moving beyond the moveTolerance. Defaults to false

  • global - When true, 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 when cancelOnMove is false. Defaults to 16.

  • frequency - The time, in milliseconds, to poll for hold events. Defaults to 200.

  • events - An array of onHoldStart events which each contain a name and time. The time controls the amount of time that must pass before this onHoldStart event is fired and should be a multiple of frequency.

1 Param
cfg Object

A partial or complete configuration object

Returns
undefined
ArrayBooleanFunctionModuleNumberObjectString