Actionable Component Properties (APL 1.3 and APL 1.2)

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

An actionable component can directly receive input from touch, cursor, or keyboard events. This document provides the set of properties common to all actionable components.

Actionable components

The following components are actionable components:

Properties

All actionable components have the following properties:

Property Type Default Styled Dynamic Description
onFocus Array of command [] No No Command to run when the component receives focus.
onBlur Array of command [] No No Command to run when the component loses focus.
handleKeyDown Array of keyboard handler [] No No Keyboard handler(s) to evaluate when the component receives a key down.
handleKeyUp Array of keyboard handler [] No No Keyboard handler(s) to evaluate when the component receives a key up.

onFocus

Command(s) to run when the component receives focus.

The event.source.focused value is set to the focused state of the component. The event.source.value is set to the standard source value for the component see: Event source property.

Components with the Disabled state set to true cannot receive focus, and therefor won't run the onFocus event handler. If a component has focus and then has it's Disabled state set to true, the component will lose focus and the onBlur event handler runs.

The event generated has the form:

"event": {
  "source": {
    "type": NAME,      // The type of the component that generated this event
    "handler": "Focus",
    "id": ID,          // ID of the component
    "uid": UID,        // Runtime-generated unique ID of the component
    "value": Any,      // Standard source value for the component
    "focused": Boolean // The focused state of the component
  }
}

The event type property is set to the name of the component; for example, "TouchWrapper", "ScrollView", "Sequence", etc.

onBlur

Command(s) to run when the component loses focus.

The event.source.focused value is set to the focused state of the component. The event.source.value is set to the standard source value for the component see: Event source property.

Components with the Disabled state set to true cannot receive focus, but if a component has focus and then has it's Disabled state set to true, the component will lose focus and the onBlur event handler runs.

The event generated has the form:

"event": {
  "source": {
    "type": NAME,      // The type of the component that generated this event
    "handler": "Blur",
    "id": ID,          // ID of the component
    "uid": UID,        // Runtime-generated unique ID of the component
    "value": Any,      // Standard source value for the component
    "focused": Boolean // The focused state of the component
  }
}

The event type property is set to the name of the component; for example, "TouchWrapper", "ScrollView", "Sequence", etc.

handleKeyDown

An array of keyboard event handlers to run when a key is pressed on the keyboard or when a key auto-repeats. The keyDown event is generated whenever possible; for example pressing the "shift" key should generate a keyDown event.

The event generated has the form:

"event": {
  "source": {
    "type": NAME,         // The type of the component that generated this event
    "handler": "KeyDown",
    "id": ID              // ID of the component
    "uid": UID,           // Runtime-generated unique ID of the component
    "value": Any          // Standard source value of the component
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

For more details on the keyboard property, refer to the keyboard events documentation.

handleKeyUp

An array of keyboard event handlers to run when a key is released on the keyboard. The keyUp event is generated whenver possible and not just for text entry. For example, releasing the "shift" key on a keyboard should generate a keyUp event.

The event generated has the form:

"event": {
  "source": {
    "type": NAME,         // The type of the component that generated this event
    "handler": "KeyUp",
    "id": ID              // ID of the component
    "uid": UID,           // Runtime-generated unique ID of the component
    "value": Any          // Standard source value of the component
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

The event type property is set to the name of the component; for example, "TouchWrapper", "ScrollView", "Sequence", etc.

For more details on the keyboard property, refer to the keyboard events documentation.

Was this page helpful?

Last updated: Nov 28, 2023