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 execute.
onCancel Array of Commands [] No No Commands to execute when a gesture takes over the pointer.
onDown Array of Commands [] No No Commands to execute when a pointer down event occurs.
onMove Array of Commands [] No No Commands to execute as the pointer moves.
onPress Array of Commands [] No No Commands to execute for a pointer down followed by a pointer up.
onUp Array of Commands [] No No Commands to execute 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.

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 executes the onCancel handler. The applicable gesture handler then processes and handles the pointer events.

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

onCancel

Commands to execute 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 executes in fast mode.

onDown

Commands to execute 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 executes its commands in fast mode.

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

onMove

Commands to execute 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 executes its commands in fast mode.

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

onPress

Commands to execute 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 executes its commands in normal mode.

onUp

Commands to execute 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 executes its commands in fast mode.

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 bounds of the touchable component trigger the pointer event handlers for that specific component. Alexa uses the following rules when executing these handlers:

  1. The onDown handler executes when the down pointer occurs in the bounds of the topmost touchable component.
  2. As long as the down pointer remains active, the onMove handler executes 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 executes.
    • The user touches componentA then moves the pointer into the bounds of componentB. The onMove handler for componentB doesn't execute.
  3. When the down pointer is released, the onUp handler executes if the original down event occurred in the same component.

    • The user touches componentB and then releases the pointer. The onUp handler for componentB executes.
    • The user touches componentA, moves into the bounds of componentB, and then releases the pointer. The onUp handler for componentB doesn't execute.
  4. When the down pointer is released within the bounds of the component, the onPress handler executes 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 executes.
    • The user touches componentB, moves the pointer outside the bounds of componentB and releases the pointer. The onPress handler for componentB doesn't execute.
  5. The onPress handler always executes 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 executes 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 executes 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. Execute the onPress handler.

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