SplitAttributes.SplitType


class SplitAttributes.SplitType


The type of parent window split, which defines the proportion of the parent window occupied by the primary and secondary activity containers.

Summary

Public companion functions

SplitAttributes.SplitType
ratio(
    ratio: @FloatRange(from = 0.0, to = 1.0, fromInclusive = false, toInclusive = false) Float
)

Creates a split type based on the proportion of the parent window occupied by the primary container of the split.

Public companion properties

SplitAttributes.SplitType

A split type in which the primary and secondary containers occupy equal portions of the parent window.

SplitAttributes.SplitType

A split type in which the primary and secondary activity containers each expand to fill the parent window; the secondary container overlays the primary container.

SplitAttributes.SplitType

A split type in which the split ratio conforms to the position of a hinge or separating fold in the device display.

Public functions

open operator Boolean
equals(other: Any?)

Determines whether this object is the same type of split as the compared object.

open Int

Returns a hash code for this split type.

open String

A string representation of this split type.

Public companion functions

ratio

Added in 1.1.0
fun ratio(
    ratio: @FloatRange(from = 0.0, to = 1.0, fromInclusive = false, toInclusive = false) Float
): SplitAttributes.SplitType

Creates a split type based on the proportion of the parent window occupied by the primary container of the split.

Values in the non-inclusive range (0.0, 1.0) define the size of the primary container relative to the size of the parent window:

  • 0.5 — Primary container occupies half of the parent window; secondary container, the other half

  • > 0.5 — Primary container occupies a larger proportion of the parent window than the secondary container

  • < 0.5 — Primary container occupies a smaller proportion of the parent window than the secondary container

Parameters
ratio: @FloatRange(from = 0.0, to = 1.0, fromInclusive = false, toInclusive = false) Float

The proportion of the parent window occupied by the primary container of the split.

Returns
SplitAttributes.SplitType

An instance of SplitType with the specified ratio.

Public companion properties

SPLIT_TYPE_EQUAL

val SPLIT_TYPE_EQUALSplitAttributes.SplitType

A split type in which the primary and secondary containers occupy equal portions of the parent window.

Serves as the default SplitType.

SPLIT_TYPE_EXPAND

val SPLIT_TYPE_EXPANDSplitAttributes.SplitType

A split type in which the primary and secondary activity containers each expand to fill the parent window; the secondary container overlays the primary container.

It is useful to use this SplitType with the function set in SplitController.setSplitAttributesCalculator to expand the activity containers in some device or window states. The following sample shows how to always fill the parent bounds if the device is in portrait orientation:

import androidx.window.embedding.SplitAttributes
import androidx.window.embedding.SplitAttributes.SplitType.Companion.SPLIT_TYPE_EXPAND
import androidx.window.embedding.SplitController

SplitController.getInstance(context).setSplitAttributesCalculator { params ->
    // A sample to always fill task bounds when the device is in portrait.
    val tag = params.splitRuleTag
    val bounds = params.parentWindowMetrics.bounds
    val defaultSplitAttributes = params.defaultSplitAttributes
    val areDefaultConstraintsSatisfied = params.areDefaultConstraintsSatisfied

    val expandContainersAttrs =
        SplitAttributes.Builder().setSplitType(SPLIT_TYPE_EXPAND).build()
    if (!areDefaultConstraintsSatisfied) {
        return@setSplitAttributesCalculator expandContainersAttrs
    }
    // Always expand containers for the splitRule tagged as
    // TAG_SPLIT_RULE_EXPAND_IN_PORTRAIT if the device is in portrait
    // even if [areDefaultConstraintsSatisfied] reports true.
    if (bounds.height() > bounds.width() && TAG_SPLIT_RULE_EXPAND_IN_PORTRAIT == tag) {
        return@setSplitAttributesCalculator expandContainersAttrs
    }
    // Otherwise, use the default splitAttributes.
    return@setSplitAttributesCalculator defaultSplitAttributes
}

SPLIT_TYPE_HINGE

val SPLIT_TYPE_HINGESplitAttributes.SplitType

A split type in which the split ratio conforms to the position of a hinge or separating fold in the device display.

The split type works only if:

  • The host task is not in multi-window mode (e.g., split-screen mode or picture-in-picture mode)
  • The device has a hinge or separating fold reported by [androidx.window.layout.FoldingFeature.isSeparating]
  • The hinge or separating fold orientation matches how the parent bounds are split:
    • The hinge or fold orientation is vertical, and the parent bounds are also split vertically (containers are side by side)
    • The hinge or fold orientation is horizontal, and the parent bounds are also split horizontally (containers are top and bottom)

Otherwise, this SplitType fallback to show the split with SPLIT_TYPE_EQUAL.

If the app wants to have another fallback SplitType if SPLIT_TYPE_HINGE cannot be applied. It is suggested to use SplitController.setSplitAttributesCalculator to customize the fallback SplitType.

The following sample shows how to fallback to SPLIT_TYPE_EXPAND if there's no hinge area in the parent window container bounds.

import androidx.window.embedding.SplitAttributes
import androidx.window.embedding.SplitAttributes.SplitType.Companion.SPLIT_TYPE_EXPAND
import androidx.window.embedding.SplitAttributes.SplitType.Companion.SPLIT_TYPE_HINGE
import androidx.window.embedding.SplitController
import androidx.window.layout.FoldingFeature

SplitController.getInstance(context).setSplitAttributesCalculator { params ->
    SplitAttributes.Builder()
        .setSplitType(
            if (
                params.parentWindowLayoutInfo.displayFeatures
                    .filterIsInstance<FoldingFeature>()
                    .isNotEmpty()
            ) {
                SPLIT_TYPE_HINGE
            } else {
                SPLIT_TYPE_EXPAND
            }
        )
        .build()
}

Public functions

equals

open operator fun equals(other: Any?): Boolean

Determines whether this object is the same type of split as the compared object.

Parameters
other: Any?

The object to compare to this object.

Returns
Boolean

True if the objects are the same split type, false otherwise.

hashCode

open fun hashCode(): Int

Returns a hash code for this split type.

Returns
Int

The hash code for this object.

toString

open fun toString(): String

A string representation of this split type.

Returns
String

The string representation of the object.