Touchable Component Properties

A touchable component receives input from touch or pointer events and invokes handlers to support custom touch interaction behavior.

Touchable components

The following components are touchable components:

Properties

All touchable components have the following properties:

Property Type Default Styled Dynamic Description
gesture, gestures Array of gesture handlers [] No No An array of gesture handlers to run.
onCancel Array of Commands [] No No Commands to run when a gesture takes over the pointer.
onDown Array of Commands [] No No Commands to run when a pointer down event occurs.
onMove Array of Commands [] No No Commands to run as the pointer moves.
onPress Array of Commands [] No No Commands to run for a pointer down followed by a pointer up.
onUp Array of Commands [] No No Commands to run when releasing the pointer.

Use the SendEvent command to send an Alexa.Presentation.APL.UserEvent request to your skill. For an example of a UserEvent handler, see Handle a UserEvent request.

layoutDirection component property

The layoutDirection property on a touchable component determines how the direction property for a SwipeAway gesture works.

For details, see the SwipeAway direction property.

gesture, gestures

An array of gesture handlers.

When pointer events occur, Alexa checks the gesture handler list (in order) to determine if the event represents a supported gesture. When a gesture handler applies, Alexa runs the onCancel handler. The applicable gesture handler then processes and handles the pointer events. Examples of gestures include double tap (DoublePress) and long-press (LongPress).

When no gesture handlers apply to the pointer event, Alexa passes the event to the applicable onDown, onMove, and onUp handlers.

For details about gestures, see Gestures. For examples, see the individual gesture handler topics:

onCancel

Commands to run when a gesture handler takes over control of the pointer. The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE, // The type of the component (such as "TouchWrapper", "VectorGraphic")
    "handler": "Cancel",
    ...                     // Component source properties
  },
  "component": {
    "x": Number,            // X-position of the down event in the component (dp)
    "y": Number,            // Y-position of the down event in the component (dp)
    "width": Number,        // Width of the component in dp
    "height": Number,       // Height of the component in dp
  }
}

Refer to Event source for a description of event.source properties.

The onCancel handler runs in fast mode in the component data-binding context.

onDown

Commands to run when a pointer down event occurs. The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE, // The type of the component (e.g., "TouchWrapper", "VectorGraphic")
    "handler": "Down",
    ...                     // Component source properties
  },
  "component": {
    "x": Number,            // X-position of the down event in the component (dp)
    "y": Number,            // Y-position of the down event in the component (dp)
    "width": Number,        // Width of the component in dp
    "height": Number,       // Height of the component in dp
  }
}

Refer to Event source for a description of event.source properties.

The onDown handler runs its commands in fast mode in the component data-binding context.

The VectorGraphic component adds an additional viewport property to this event.

onMove

Commands to run when the pointer location moves. The event generated has the following form.

"event": {
  "source": {
    "type": COMPONENT_TYPE, // The type of the component (e.g., "TouchWrapper", "VectorGraphic")
    "handler": "Move",
    ...                     // Component source properties
  },
  "component": {
    "x": Number,            // X-position of the move event in the component (dp)
    "y": Number,            // Y-position of the move event in the component (dp)
    "width": Number,        // Width of the component in dp
    "height": Number,       // Height of the component in dp
  },
  "inBounds": Boolean       // True if the pointer is within the component bounds
}

The inBounds calculation for the pointer position doesn't consider any overlapping components.

Refer to Event source for a description of event.source properties.

The onMove handler runs its commands in fast mode in the component data-binding context.

The VectorGraphic component adds an additional viewport property to this event.

onPress

Commands to run when a press event occurs. The event generated has the form:

"event": {
  "source": {
    "type": COMPONENT_TYPE, // The type of the component (e.g., "TouchWrapper", "VectorGraphic")
    "handler": "Press",
    ...                     // Component source properties
  }
}

Refer to Event source for a description of event.source properties.

The onPress handler runs its commands in normal mode in the component data-binding context.

onUp

Commands to run when a pointer up event occurs. The event generated has the form:

"event": {
  "source": {
    "type": COMPONENT_TYPE, // The type of the component (e.g., "TouchWrapper", "VectorGraphic")
    "handler": "Up",
    ...                     // Component source properties
  },
  "component": {
    "x": Number,            // X-position of the up event in the component (dp)
    "y": Number,            // Y-position of the up event in the component (dp)
    "width": Number,        // Width of the component in dp
    "height": Number,       // Height of the component in dp
  }
  "inBounds": Boolean       // True if the pointer is within the component bounds
}

The inBounds calculation for the pointer position doesn't consider any overlapping components.

Refer to Event source for a description of event.source properties.

The onUp handler runs its commands in fast mode in the component data-binding context.

The VectorGraphic component adds an additional viewport property to this event.

Event handler rules

Mouse or tap events that the user initiates or performs within the transformed bounds of the touchable component trigger the pointer event handlers for that specific component. Alexa uses the following rules when running these handlers:

  1. The onDown handler runs when the down pointer occurs in the transformed bounds of the topmost touchable component.

  2. As long as the down pointer remains active, the onMove handler runs as the pointer location changes if the original down event occurred in the same component.

    For example, assume two components, componentA and componentB.

    • The user touches componentB and moves the pointer. The onMove handler for componentB runs.
    • The user touches componentA then moves the pointer into the bounds of componentB. The onMove handler for componentB doesn't run.

  3. When the down pointer is released, the onUp handler runs if the original down event occurred in the same component.

    • The user touches componentB and then releases the pointer. The onUp handler for componentB runs.
    • The user touches componentA, moves into the bounds of componentB, and then releases the pointer. The onUp handler for componentB doesn't run.

  4. When the down pointer is released within the transformed bounds of the component, the onPress handler runs if the original down event occurred in the same component.

    • The user touches componentB, keeps the pointer within the bounds of componentB and then releases the pointer. The onPress handler for componentB runs.
    • The user touches componentB, moves the pointer outside the bounds of componentB and releases the pointer. The onPress handler for componentB doesn't run.
  5. The onPress handler always runs after the onUp handler.

If two or more visible touchable components overlap at the point of the initial down pointer event, the topmost component receives the down event and all subsequent move, up, and press events. The lower components don't receive any events.

Gestures are special-purpose handlers that interpret specific motions or pointer actions, such as a swipe or a double-tap. When a gesture handler recognizes that a gesture has started, it runs the onCancel handler. After the onCancel handler completes, the gesture handler captures all the pointer events. The onUp and onMove handlers are ignored.

The onCancel handler also runs if APL loses control of the pointer. This might occur if another app takes over the screen.

A touchable component is an actionable component and responds to "enter" key presses when the component has an onPress handler. If the component doesn't have an onPress handler, the component does nothing.

When the component has an onPress handler, "enter" key presses do the following:

  1. Set the pressed component state to true when the user presses the enter key.
  2. Set the pressed component state back to false when the user releases the enter key.
  3. Run the onPress handler.

You can override this behavior by capturing the Enter and NumpadEnter keyboard code events and blocking propagation of the event.

Was this page helpful?

Last updated: Feb 29, 2024