An event triggers state changes and initiates actions. Events act as signals, dispatched from the System UI or from outside the process using an intent. Events inform the Scalable UI about occurrences that require a response.
A Scalable UI event is a system signal, triggered by hardware or software changes, that can alter a panel's state. These events notify the framework about occurrences that require a UI response. For more precise control over panel states, you can also define custom events, in addition to built-in system events.
Structure of an event
A mandatory unique identifier (ID) identifies an event. This ID categorizes the
type of occurrence, such as _System_AppOpenEvent or _System_PanelEmptyEvent.
In addition to this ID, an event can optionally carry tokens, key-value pairs to provide context and details about the event. These tokens allow for more granular filtering of events, enabling transitions or actions to be triggered only under specific conditions.
Tokens are passed to the event as a list of key-value pairs separated by
a semi-colon (;). Here is the list of system supported keys:
| Key | Description |
|---|---|
panelId |
Identifies a specific UI panel associated with the event. |
component |
Specifies the component name, such as an activity linked to the event. |
package |
Indicates the package name related to the event. |
panelToVariantId |
Specifies the target variant of a panel in specific contexts. Use this attribute to cascade animations by listening to a panel transition. For example, triggering panel B transition to close state when panel A is transitioned to an open state. |
For example:
"component=com.android.app;panelId=panel1"
Event matching logic
When an event is dispatched, it must be matched against defined criteria to trigger a transition or an action. The matching process occurs in two stages:
Strict event
idmatching: Theidof the dispatched event must match exactly theidspecified in the transition or action event filter. If the IDs don't match, the event is deemed as not a match.Partial event token matching: When event IDs match, the system uses partial matching to evaluate an event's tokens against tokens defined in the filter.
For a match to occur, all event properties (tokens) specified in the transition's event definition must strictly match the corresponding properties in the dispatched event.
That said, the dispatched event can contain additional tokens not explicitly defined in the filter. Extra tokens don't prevent a match. Instead, they're ignored in the matching evaluation.
Conversely, if the filter specifies a token that isn't present in the dispatched event or, if the value of a matching token doesn't align, it isn't considered a match.
For example, consider a transition defined to trigger when id="app_open" takes
place on panelId="panel1" with component="com.android.myapp.Activity".
If a dispatched event has id="app_open", panelId="panel1", and
component="com.android.myapp.Activity", a match is made. All filter
criteria are met and the more specific value for the Activity value in the
dispatched event is considered a match forcom.android.myapp`.
However, the match fails should the dispatched event when id="app_open",
panelId="panel1", and component="com.android.yourapp.Activity".
Though id and panelId match, the component not equal to component
in the transition — com.android.myapp — doesn't match com.android.yourapp
in the dispatched event.
Transition trigger
While a transition may be a match, this doesn't mean it's triggered. Only one transition can be triggered for each event. Scalable UI aims to trigger only the closest match.
For example, when two transitions — one with a component name and one without a
component name -m — are a match, only the transition with the component name
is triggered.
Event dispatch and handling
Events are central to the dynamic behavior of the Scalable UI. Events can be dispatched from the System UI or from external processes with an intent.
System events
The framework defines several system events that facilitate these actions:
| Attribute | Description |
|---|---|
_System_OnHomeEvent( SYSTEM_HOME_EVENT_ID) |
Signifies that the system received a request to display the Home screen. In AAOS, Home can be a flexible configuration of windows, such as a combination of widgets, or even a map. This event is crucial for transitions or actions that depend on the user viewing the primary home interface. |
_System_TaskOpenEvent( SYSTEM_TASK_OPEN_EVENT_ID) |
Is dispatched when a task or app is opened. This general event can trigger actions or transitions based on the launching of an app. This event contains tokens such as |
_System_TaskCloseEvent( SYSTEM_TASK_CLOSE_EVENT_ID) |
Signals that a task or app has closed and serves as the counterpart to
_System_TaskOpenEvent. This allows the system to react to apps
being dismissed. This can trigger transitions to return a panel to a default
state or to initiate other cleanup actions.
|
_System_TaskPanelEmptyEvent( SYSTEM_TASK_PANEL_EMPTY_EVENT_ID) |
Dispatched when a specific panel becomes empty and includes the
This event is important for robust error recovery and to relaunch apps when associated content crashes or unexpectedly terminates to prevent the display of empty UI panels. For example, if a |
_System_EnterSuwEvent( SYSTEM_ENTER_SUW_EVENT_ID) |
Indicates the system entering the Setup Wizard (SUW). This event signals system readiness and can be configured to launch apps or bring designated panels into view once the system is initialized. Entering such a critical system state requires a dedicated event to trigger the appropriate UI adjustments or actions. |
_System_ExitSuwEvent( SYSTEM_EXIT_SUW_EVENT_ID) |
Indicates the system exiting the Setup Wizard (SUW). Similar to
_System_EnterSuwEvent, this event allows the system to respond
to the completion of the setup process by launching default apps or
transitioning to a standard UI. |
_System_OnAnimationEndEvent( SYSTEM_ON_ANIMATION_END_EVENT_ID) |
Triggered when an animation is completed in the UI. You can use this
event to trigger subsequent actions or state changes that depend on the
completion of a visual transition.
This event contains a token for |