Visibility Change Event Handlers

Alexa Presentation Language (APL) generates visibility change events when the visibility of a component changes. You can use a handleVisibilityChange event handler to capture these events and run commands.

Types of changes that generate visibility change events

There are two types of changes that trigger a visibility change event:

  • The overall opacity (cumulativeOpacity) of the component changes. For example, changing a component's opacity with an AnimateItem or SetValue command changes the cumulativeOpacity for the component and generates an event.
  • The percentage of the component's bounding box that's visible within its parent component changes (visibleRegionPercentage). For example, scrolling a child component within a Sequence into view changes the visibleRegionPercentage for the child component and generates an event.

Visibility change event handlers

You can define a handler to capture visibility changes for a component. All components have the handleVisibilityChange property, which takes an array of visibility change handlers. The handlers are called after the component is first mounted, and then subsequently when the visibleRegionPercentage or cumulativeOpacity changes.

Property Type Default Styled Dynamic Description

handleVisibilityChange

Array of visibility change handlers

[]

No

No

Visibility handlers to invoke when visibility of the component changes.

A visibility change handler is an object with the properties shown in the following table.

Property Type Default Description

commands

Array of commands

Required

Commands to run if this handler is invoked.

description

String

—

Optional description.

when

Boolean

true

When true, invoke this handler.

The array of visibility change handlers runs in parallel. Each handler has a when property. The handler runs when both of the following conditions are met:

  • The when clause for the handler evaluates to true.
  • Either the visibleRegionPercentage or cumulativeOpacity for the component changes.

commands

An array of commands to run when this visibility change handler is invoked.

The event generated has the following form:

{
  "event": {
    "source": {
      "type": "COMPONENT_TYPE",         // The type of the component, such as "Pager", "TouchWrapper"
      "handler": "VisibilityChange"
      ...                               // Component source properties
    },
    "visibleRegionPercentage": NUMBER, // Visible percentage of component's area as a fraction of defined dimensions [0.0, 1.0]
    "cumulativeOpacity": NUMBER        // Overall component opacity as a fraction [0.0, 1.0]
  }
}

The event.source.type property is set to the name of the component, such as TouchWrapper, ScrollView, or Sequence. For details about event.source properties, see event.source.

Commands always run in *fast mode**.

when

When true, this handler is invoked for visibility changes.

Limitations when evaluating the visibleRegionPercentage

The visibleRegionPercentage is the percentage of the bounding box of the element that's visible within its parent component. The value doesn't consider the following:

  • The visibleRegionPercentage doesn't consider applied component transforms: translations, rotations, and scale. Don't rely on the visibility calculation if the component or any ancestor component has a transformation applied.
  • The visibleRegionPercentage doesn't consider that a component might be obscured by a child or an absolutely positioned component on top of it.

Performance considerations

Transitive visibility calculations might be relatively expensive depending on document hierarchy. Therefore, consider the following:

  • Only use the handleVisibilityChange property on components when absolutely necessary.
  • The cumulativeOpacity for a component is calculated as the product of the opacity value for the component and opacity for each of the component's ancestors. Therefore, a change in the opacity to any of the ancestors of the component might trigger the handler. This calculation is more efficient when the target component is as close to the root of the hierarchy as possible.
  • Use the when property to disable the handler when it isn't needed.

Timing of visibility change events

The visibility change handler fires when the document object model updates the component visibility. There is a small lag time between the model change and the screen reflecting the change. The length of the delay depends on multiple factors, including:

  • The document complexity
  • Operating system load
  • Delays in the graphic processing pipeline

Often, the screen update occurs within a single graphic frame (16 ms), but this isn't guaranteed. Therefore, consider this potential lag time when doing any kind of performance measurement or developing a system that requires precise calculations.

Visibility change handler examples

The following example uses a handler to display a message when at least 50 percent of the last item in a Sequence is visible for one second.

The following example displays buttons to increase and decrease the opacity of a Frame component. The visibility change handler on the Frame updates variables used to display the current opacity of the component and determine when to enable and disable the buttons.

Was this page helpful?

Last updated: Feb 17, 2024