Overview of Scene-based Widgets

Since API version 20, scene-based widgets support special effects. For example, you can choose to extend the animation beyond the widget rendering area to create an "overflow" effect.

Basic Concepts

A scene-based widget can be in either active state or inactive state. The widget animation can be triggered when the widget data is interval-based or time-specific updated, or when users interact with the widget (for instance, by tapping). The widget switches to the active state when the animation starts and reverts to the inactive state once the animation ends.

Inactive state: The widget is like a common widget and complies with the existing widget development specifications. The widget UI is carried by the content in widgetCard.ets of the widget provider.

Active state: The interactive widget is rendered. The widget UI is rendered on the page of the LiveFormExtensionAbility developed by the widget provider. For details, see Developing a Scene-based Widget.

Figure 1 Switching interactive widget states

Figure 2 Process of triggering an interactive widget animation

How to Implement

You can call the formProvider.requestOverflow API to trigger animations on interactive widgets, for example, when a user taps the widget. The typical timing diagram is as follows.

Figure 3 Timing diagram of animations triggered by a tap

The following figure shows the timing diagram in interval-based and time-specific updates.

Figure 4 Timing diagram in interval-based and time-specific updates

Constraints

Supported Scenarios

Currently, the interactive widget animation takes effect only on a single widget with FormLocation set to DESKTOP.
Due to the impact on performance and power consumption, only some models are supported. If a model is not supported, the error code 801 is reported.

Parameter Request

The maximum valid duration of the animation is 3500 ms. When the countdown ends, the widget switches back to the inactive state. System applications support long-time activated widgets, and the animation duration is not limited. For details, see Developing a Scene-based Widget (for System Applications).
A single widget's animation triggered by interval-based and time-specific updates can occur up to 50 times a day.
As illustrated, rectangle ABCD denotes the widget's rendering area, whereas rectangle IJKL indicates the maximum animation area the widget can request. The centers of the two rectangles are aligned. The dimensions meet the requirements described in the following table.

Dimension	Length of JK	Length of IJ
1 * 2	No greater than 150% of the length of AD.	No greater than 200% of the length of AB.
2 * 2	No greater than 150% of the length of AD.	No greater than 150% of the length of AB.
2 * 4	No greater than 125% of the length of AD.	No greater than 150% of the length of AB.
4 * 4	No greater than 125% of the length of AD.	No greater than 125% of the length of AB.
6 * 4	No greater than 125% of the length of AD.	No greater than 110% of the length of AB.

Figure 5 Rules for requesting the animation area

Example: On a device, a 2×2 widget measures 158vp × 158vp. Referring to the figure above:

AD = 158vp, AB = 158vp, IJ = 158 × 1.5 = 237vp, IL = 158 × 1.5 = 237vp
Points I and A are horizontally 39.5vp apart and vertically 39.5vp apart.

Thus, with A as the origin (X-axis positive to the right, Y-axis positive downward), the valid coordinates for point E in Figure 5 can be (-20, -20). The valid lengths for sides EF and EH can both be 200vp.

You can call the formProvider.getFormRect API to obtain the dimensions and position of the interactive widget in the window. The widget provider calculates the animation request range based on this dimension. For coordinate calculations, point A in the figure is used as the origin (0,0), and the parameters corresponding to rectangle EFGH are calculated, with units in vp.

When formProvider.requestOverflow is called, the animation rendering area (rectangle EFGH) described in overflowInfo must meet the following requirements:

It contains the widget (rectangle ABCD).
It does not exceed rectangle IJKL (rectangle IJKL completely contains rectangle EFGH). This applies only to third-party applications.

For details, see Developing a Scene-based Widget.

Power Consumption

When a device enters the power-saving mode, interactive widgets do not respond to animation effect requests.
When the device's thermal level reaches HOT, it no longer responds to animation requests triggered by non-tap operations; when the thermal level reaches OVERHEATED, it no longer responds to any animation requests. For details, see ThermalLevel.

Animation Request

At a time, only one widget executes the interactive widget animation.
When a user actively triggers an animation effect for an interactive widget (for example, via a tap), this request takes priority. At this point, the current widget switches to the active state and runs the animation, while other widgets switch to the inactive state.
Other triggering modes, for example, triggering an animation via interval-based or time-specific update, are based on the first-come, first-served principle. The system processes only the first valid animation request. Other requests return failure and no cache is performed.
Other valid operations (such as tapping an application or widget, swiping pages, pulling down to access full search, dual-center, dragging a widget, and long pressing a widget) on the home screen will interrupt the current animation, and the widget will become inactive again. System applications can suspend some operations on the home screen by configuring the suspend gesture. For details, see Developing a Scene-based Widget (for System Applications).
The interactive widget does not respond to the events that exceed the animation rendering area (rectangle ABCD in Figure 5).
For details about the restrictions on the interactive widget in the active state, see LiveFormExtensionAbility.