Actionable Component Properties

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 handlers to evaluate when the component receives a key down.
handleKeyUp Array of keyboard handler [] No No Keyboard handlers to evaluate when the component receives a key up.

Actionable components do not add any properties to the component definitions of the event.source or event.target properties.

onFocus

Commands to run when the component receives focus.

Components with the Disabled state set to true can't receive focus, and don't run the onFocus event handler. If a component has focus and then has it's Disabled state set to true, the component loses focus and runs the onBlur event handler.

Components with the inheritParentState property set to true can't receive focus and don't run the onFocus event handler.

The event generated has the following form.

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

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

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

onBlur

Commands to run when the component loses focus.

Components with the Disabled state set to true can't receive focus. If the Disabled state for a component changes to true when the component already has focus, the component loses focus and runs the onBlur event handler.

Components with the inheritParentState property set to true can't receive focus and don't run the onBlur event handler.

The event generated has the form:

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

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

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

handleKeyDown

An array of keyboard event handlers to run when the user presses a key on the keyboard or when a key auto-repeats. The keyDown event is generated whenever possible, not just for text entry. For example, pressing the "shift" key should generate a keyDown event.

The event generated has the form:

"event": {
  "source": {
    "type": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "KeyDown",
    ...                     // Component source properties
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

For more details on the keyboard property, see Keyboard Event Handlers.

The handleKeyDown event handler runs in normal mode in the component data-binding context.

handleKeyUp

An array of keyboard event handlers to run when the user releases a key on the keyboard. The keyUp event is generated whenever possible, 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": "COMPONENT_TYPE", // The type of the component (e.g., "Pager", "TouchWrapper")
    "handler": "KeyUp",
    ...                     // Component source properties
  },
  "keyboard": {
    "altKey":   Boolean
    "code":     String,
    "ctrlKey":  Boolean,
    "key":      String,
    "metaKey":  Boolean,
    "repeat":   Boolean,
    "shiftKey": Boolean
  }
}

The event.source.type property contains the name of the component, such as "TouchWrapper" or "ScrollView". Refer to Event source for a description of event.source properties.

For more details on the keyboard property, see Keyboard Event Handlers.

The handleKeyUp event handler runs in normal mode in the component data-binding context.

Actionable component event handler example

The following example shows the onFocus and onBlur handlers. The document displays a Sequence of TouchWrapper components, along with two buttons. Each list item runs commands in onFocus and onBlur to update bind variables to track which component gained or lost focus. The onMount for the document sets the focus to the first item in the list.

On a device with a keyboard, use the Tab and Shift+Tab keys to change the focus and note the results of the onFocus and onBlur handlers.

Was this page helpful?

Last updated: Dec 18, 2024