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 anAnimateItem
orSetValue
command changes thecumulativeOpacity
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 aSequence
into view changes thevisibleRegionPercentage
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 |
---|---|---|---|---|---|
|
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 |
---|---|---|---|
|
Array of commands |
Required |
Commands to run if this handler is invoked. |
|
String |
— |
Optional description. |
|
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 totrue
. - Either the
visibleRegionPercentage
orcumulativeOpacity
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 theopacity
value for the component andopacity
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.
Related topics
Last updated: Feb 17, 2024