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, 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
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 events.

Event payload includes:

  • type - Type of event, 'onHold'

  • 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

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

onHoldPulse
Function

Event handler for hold pulse events

Event payload includes:

  • type - Type of event, 'onHoldPulse'

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

onTap
Function

Event handler for 'tap' pointer events

onUp
Function

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 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 onHold events which each contain a name and time. The time controls the amount of time that must pass before this onHold event is fired and should be a multiple of frequency.

1 Param
cfg Object

A partial or complete configuration object

ArrayBooleanFunctionModuleNumberObjectString