Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

Configure a panel

A panel describes the properties of the area it occupies and acts as an app container. You use XML configurations to define panels, which provide a flexible and code-free approach for customizing UIs. To manage instances and states, the system tracks defined panels.

Panel list

The System UI loads the definitions of its panels from an array resource named window_states. This resource array points to the XML files, in which individual panel configurations are defined. This centralized approach means that panels managed by Scalable UI are loaded as intended and ready for use by the system.

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <array name="window_states">
       <item>@xml/app_panel</item>
       <item>@xml/back_panel</item>
       ...
   </array>
</resources>

Panel definition

Each panel in the Scalable UI framework is defined with an XML tag named <TaskPanel>, which describes the properties of an app container. System UI loads these panel definitions and tracks the panels until another configuration is loaded.

For example, by a configuration change due to rotation or explicit system request. The <TaskPanel> serves as a foundational component for building a customized experience through configurable UI components.

XML attributes

The <TaskPanel> tag can contain these attributes you can use to define states and transitions.

Attribute	Status	Description
`id`	Mandatory	Specifies a unique identifier for the panel. This attribute is used to retrieve the panel from the `PanelPool` and to manage its state within the system.
`role`	Mandatory	Defines the purpose or function of the panel in the system. The value can refer to a string resource, a string array of component names, or a layout ID. For example, it can define persistent activities that should always be displayed on the panel, or a layout to be inflated.
`defaultVariant`	Optional	Specifies the ID of the variant that the panel should initially adopt when it is loaded. If not specified, the system can use the first defined variant as the default.
`displayId`	Optional	Specifies the ID of the display to which the panel is intended to appear.
`defaultLayer`	Optional	Can specify a default Z-order for the panel's variants if the variants don't explicitly define a layer.
`controller`	Optional, subject to change	References a resource (usually an XML ID) that defines a panel-specific controller, which allows for the storing and passing of configuration values to custom panel controllers. These controllers should implement the `com.android.car.scalableui.panel.TaskPanelController` interface. A common use case of these controllers is to define flexible runtime task allocations on the panel.

XML child elements

The <TaskPanel> tag can include these attributes to define characteristics and default behaviors,

Attribute Description

Attribute	Description
`<Variant>`	Nested tag describes a specific visual configuration for the panel at any given time. A panel can have multiple variants, each identified by a unique ID. Each variant defines properties like bounds, visibility, layer, alpha, corner radius, and insets for that particular configuration. Variants can also inherit properties from a parent variant.
`<KeyFrameVariant>`	Extension of `<Variant>` allows for the interpolation of visual properties between different variants based on a continuous fraction value (0 to 1) and is used for smooth and dynamic transitions, such as during a drag operation, when the panel's state depends on a continuous input such as a drag amount.
`<Transitions>`	Nested tag contains a collection of `<Transition>` definitions, which describe how the UI should animate between different variants. Each `<Transition>` defines the from and to variants, the event that triggers it, and can optionally specify a custom Animator to use for the animation, as well as a duration and interpolator.

<Variant>

Nested tag describes a specific visual configuration for the panel at any given time. A panel can have multiple variants, each identified by a unique ID.

Each variant defines properties like bounds, visibility, layer, alpha, corner radius, and insets for that particular configuration. Variants can also inherit properties from a parent variant.

<KeyFrameVariant> Extension of <Variant> allows for the interpolation of visual properties between different variants based on a continuous fraction value (0 to 1) and is used for smooth and dynamic transitions, such as during a drag operation, when the panel's state depends on a continuous input such as a drag amount.

<Transitions>

Nested tag contains a collection of <Transition> definitions, which describe how the UI should animate between different variants.

Each <Transition> defines the from and to variants, the event that triggers it, and can optionally specify a custom Animator to use for the animation, as well as a duration and interpolator.

Sample code

<Panel id="@+id/panelId"
        role="@array/roleValue"
        defaultVariant="@id/closed"
        displayId="0" >

 <Variant id="@+id/base">
        <Bounds left="0" top="0" width="100%" height="100%"/>
 </Variant>

<Variant id="@+id/opened" parent="@id/base">
    <Visibility isVisible="true"/>
</Variant>
<Variant id="@+id/closed"  parent="@id/base">
    <Visibility isVisible="false"/>
</Variant>

<Transitions>
    <Transition fromVariant="@id/closed"
                toVariant="@id/opened"
                onEvent="open_event"/>
        <Event id="_System_TaskOpenEvent" panelId="@id/panelId" />
    </Transition>
</Transitions>
</Panel>

Implement advanced windowing

Configure a variant