Use a variant to design a visual state

A variant defines a specific visual state for a panel, allowing a single panel to have multiple distinct visual representations, such as an opened or closed state. Use XML to configure variant. Use a sub-tag within a <Panel> element.

Each <Variant> tag has a mandatory id attribute to uniquely identify it. The tag can also refer to a parent variant to inherit properties. This inheritance mechanism allows for the efficient definition of common properties across multiple variants.

XML attributes

To define states and transitions, use these attributes with the <TaskPanel> or <DecorPanel> tag.

Attribute Status Description
id Mandatory Unique identifier of the variant. This ID is used to refer to the variant in transitions or as the defaultVariant for a panel.
parent Optional Specifies the ID of another variant from which the current variant should inherit properties. If a property is not explicitly defined in the current variant, it falls back to the value defined in its parent variant.

XML child elements

Use these optional elements to specify the visual characteristics of the panel when it's in this variant's state.

Child element Description
<Visibility> Specifies if the panel is visible or hidden and contains an isVisible attribute (boolean).
<Alpha> Specifies the transparency level of the panel; contains an alpha attribute (float, 0.0 to 1.0).
<Layer> Sets the Z-order of the panel relative to other panels; contains a layer attribute (integer). Higher values are drawn on top.
<Focus> Specifies if the panel can gain focus during a transition; contains an onTransition attribute (boolean).
<Bounds>

Defines the rectangular area (position and size) of the panel on the screen. This area is controlled by attributes such as left, top, bottom, width, and height.

  • left and right specify the distance from the left edge of the screen.
  • top and bottom specify the distance from the top edge of the screen.
  • width and height specify the width and height of the rectangle and is needed only when both left and right (or top and bottom) aren't specified.
  • dimensions can be specified in pixels, DP, percentages, or resource references.

When using percentages, you can employ offset attributes to apply fixed adjustments to the percentage-based boundaries — leftOffset, topOffset, rightOffset, and bottomOffset.

For example, to designate that a panel occupy 100% of the screen height while excluding a fixed-height navigation bar at the bottom, set the height to 100% and the bottomOffset to the fixed height of the navigation bar. Doing so pulls the panel's bottom edge upward.
<SafeBounds> Specifies a safe area within the panel's bounds that's not overlapped by display cutouts or insets, to underscore compatibility for apps drawn within it. Its attributes are similar to <Bounds>.
<Corner> Defines the radius for the corners of the panel, allowing for rounded corners and contains a radius attribute (integer). A sharp corner is the default and needn't be defined.
<Insets>

Specifies the insets (padding) for the panel. It contains left, top, right, bottom attributes. These insets are reported to those apps launched within the panel.

  • left specifies the inset on the left side.
  • right specifies the inset on the right side. For example, a zero right inset indicates no insets on the right side.
  • top specifies the inset on the top side.
  • bottom specifies the inset on the bottom side. For example, a zero right inset indicates no insets on the right side.
<Background> Introduces an optional background decor panel, to prevent see-through effects when apps are switched. It defines properties like color and alpha for this decor layer. The decor layer's properties, such as bounds and layer, default to the variant's properties when not already set.

Sample code

<Variant id="@id/opened">
    <Visibility isVisible="true"/>
    <Bounds left="0dp"
            top="0dp"
            right="100%"
            bottom="100%"
            bottomOffset="100dp"/>
    <Alpha value="1.0"/>
    <Layer value="10"/>
    <Focus onTransition="true"/>
    <Corner radius="24dp"/>
    <Insets left="16dp" top="0dp" right="16dp" bottom="48dp"/>
    <Background color="@color/app_background" alpha="0.9"/>
</Variant>

Interpolate visual properties

Use KeyFrameVariant to interpolate visual properties. This specialized extension of variant is based on a continuous fractional value (0 to 1) that allows for smooth, dynamic transitions driven by continuous input, such as a drag operation when the panel's state dynamically changes with the drag amount.

XML attributes

KeyFrameVariant doesn't have attributes. The <KeyFrameVariant> tag contains the information needed to define a KeyFrameVariant.

XML child elements

KeyFrameVariant contains one or more <KeyFrame> child tags. Each <KeyFrame> has a framePosition attribute (0-100) and refers to a variant attribute (the ID of another variant). These keyframes define the panel's state at specific points in a continuous transition.

Samole code

<KeyFrameVariant id="@id/panel_resizing">
    <KeyFrame framePosition="0" variant="@id/minimized"/>
    <KeyFrame framePosition="75" variant="@id/opened"/>
    <KeyFrame framePosition="100" variant="@id/expanded"/>
</KeyFrameVariant>
Previous
Configure a panel
Next
Configure transitions