APL TouchWrapper

A TouchWrapper wraps a single child component and responds to touch events.

Properties

The TouchWrapper component has the following properties:

Property Type Default Styled Dynamic Description
item, items Component [ ] No No Child item to display

When the TouchWrapper is the source or target of an event, the following values are reported in event.source or event.target:

{
  // TouchWrapper-specific values
  "type": "TouchWrapper",

  // General component values
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

item, items

The child component or layout to display. The user can tap or select the component on the screen to invoke the actionable and touchable event handlers. If you provide multiple items, the TouchWrapper uses the single child logic described in APL Conditional Component Inflation to select and display one item. To combine multiple components for the item, use a Container or Layout.

Actionable properties

A TouchWrapper is an actionable component. The TouchWrapper inherits all of the actionable properties.

Touchable properties

A TouchWrapper is a touchable component. The TouchWrapper inherits all of the touchable properties.

For details about the source event the TouchWrapper generates, see Touchable Component Properties. The specific values used by TouchWrapper are:

event.source.type = "TouchWrapper"
event.source.value = Boolean    // The checked state of the touch wrapper

TouchWrapper examples

Individual component

In this example, the TouchWrapper wraps a Text component. When the user presses the text, the component runs two commands:

  • A SendEvent command. The SendEvent command sends an Alexa.Presentation.APL.UserEvent request to the skill service. The skill service should include a handler to process UserEvent requests.
  • A SetValue command that updates the text property of a Text component.

To see the results of the SetValue command in this example, click the text.

To experiment with the SendEvent command, copy this APL document to a full skill. The following example shows the UserEvent request generated by the SendEvent command.

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-02-21T18:09:14Z",
  "locale": "en-US",
  "arguments": [
    "peasinapod"
  ],
  "components": {},
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "fivePeasInAPodTouchWrapper",
    "value": false
  },
  "token": "token-provided-in-the-RenderDocument-directive"
}

For an example of a UserEvent handler, see Handle a UserEvent request.

List items in a Sequence

The following example shows a Sequence that uses a TouchWrapper for the item property. The TouchWrapper wraps a Text component.

The Sequence displays the TouchWrapper one time for each item in the provided data array (touchWrapperInSequenceData.listItems). Because each list item is a TouchWrapper, the user can select any item from the list. The TouchWrapper runs the SetValue command to update a Text component with information about the selected item, and the SendEvent command to send a UserRequest to the skill.

To experiment with the SendEvent command, copy this APL document to a full skill. The following example shows the UserEvent request generated by the SendEvent command in this example.

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2023-02-21T20:26:53Z",
  "locale": "en-US",
  "arguments": [
    {
      "itemOrdinal": 17,
      "itemIndex": 16,
      "action": "ItemSelected",
      "itemId": "item_16"
    }
  ],
  "components": {},
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "item_16",
    "value": false
  },
  "token": "token-provided-in-the-RenderDocument-directive"
}

For details about the Sequence properties, see Sequence.

Last updated: Mar 02, 2023