SplitRule

open class SplitRule : EmbeddingRule

kotlin.Any
   ↳ androidx.window.embedding.EmbeddingRule
     ↳ androidx.window.embedding.SplitRule
Known direct subclasses
SplitPairRule

Split configuration rules for activity pairs.
SplitPinRule

Split configuration rules for pinning an ActivityStack.
SplitPlaceholderRule

Configuration rules for split placeholders.

Split configuration rules for activities that are launched to side in a split. Define the visual properties of the split. Can be set either via RuleController.setRules or via RuleController.addRule. The rules are always applied only to activities that will be started after the rules were set.

Note that regardless of whether the minimal requirements (minWidthDp, minHeightDp and minSmallestWidthDp) are met or not, the callback set in SplitController.setSplitAttributesCalculator will still be called for the rule if the calculator is registered via SplitController.setSplitAttributesCalculator. Whether this SplitRule's minimum requirements are satisfied is dispatched in SplitAttributesCalculatorParams.areDefaultConstraintsSatisfied instead. The width and height could be verified in the SplitAttributes calculator callback as the sample linked below shows.

It is useful if this SplitRule is supported to split the parent container in different directions with different device states.

import androidx.window.embedding.EmbeddingAnimationBackground
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 split with the dimension that larger than 600 DP. If there's no dimension
    // larger than 600 DP, show the presentation to fill the task bounds.
    val parentConfiguration = params.parentConfiguration
    val builder = SplitAttributes.Builder()
    return@setSplitAttributesCalculator if (parentConfiguration.screenWidthDp >= 600) {
        builder
            .setLayoutDirection(SplitAttributes.LayoutDirection.LOCALE)
            // Optionally set the animation background to use when switching between
            // vertical and horizontal
            .setAnimationBackground(
                EmbeddingAnimationBackground.createColorBackground(Color.GRAY)
            )
            .build()
    } else if (parentConfiguration.screenHeightDp >= 600) {
        builder
            .setLayoutDirection(SplitAttributes.LayoutDirection.TOP_TO_BOTTOM)
            // Optionally set the animation background to use when switching between
            // vertical and horizontal
            .setAnimationBackground(
                EmbeddingAnimationBackground.createColorBackground(Color.GRAY)
            )
            .build()
    } else {
        // Fallback to expand the secondary container
        builder.setSplitType(SPLIT_TYPE_EXPAND).build()
    }
}
See also
SplitPairRule
SplitPlaceholderRule

Summary

Nested types

Determines what happens with the associated container when all activities are finished in one of the containers in a split.

Constants
const Int

When the min dimension is set to this value, it means to always allow split.
const Int

The default min dimension in DP for allowing split if it is not set by apps.

Public companion properties
EmbeddingAspectRatio

The default max aspect ratio for allowing split when the parent window is in landscape.
EmbeddingAspectRatio

The default max aspect ratio for allowing split when the parent window is in portrait.

Public functions
open operator Boolean
equals(other: Any?)
open Int
open String

Public properties
SplitAttributes

The default SplitAttributes to apply on the activity containers pair when the host task bounds satisfy minWidthDp, minHeightDp, minSmallestWidthDp, maxAspectRatioInPortrait and maxAspectRatioInLandscape requirements.
EmbeddingAspectRatio

The largest value of the aspect ratio, expressed as width / height in decimal form, of the parent window bounds in landscape when the split should be used.
EmbeddingAspectRatio

The largest value of the aspect ratio, expressed as height / width in decimal form, of the parent window bounds in portrait when the split should be used.
Int

The smallest value of height of the parent task window when the split should be used, in DP.
Int

The smallest value of the smallest possible width of the parent task window in any rotation when the split should be used, in DP.
Int

The smallest value of width of the parent task window when the split should be used, in DP.

Inherited properties
From androidx.window.embedding.EmbeddingRule
String?

A unique string to identify this EmbeddingRule, which defaults to null.

Constants

SPLIT_MIN_DIMENSION_ALWAYS_ALLOW

const val SPLIT_MIN_DIMENSION_ALWAYS_ALLOW = 0: Int

When the min dimension is set to this value, it means to always allow split.

See also
minWidthDp
minSmallestWidthDp

SPLIT_MIN_DIMENSION_DP_DEFAULT

const val SPLIT_MIN_DIMENSION_DP_DEFAULT = 600: Int

The default min dimension in DP for allowing split if it is not set by apps. The value reflects androidx.window.core.layout.WindowWidthSizeClass.MEDIUM.

Public companion properties

SPLIT_MAX_ASPECT_RATIO_LANDSCAPE_DEFAULT

val SPLIT_MAX_ASPECT_RATIO_LANDSCAPE_DEFAULT: EmbeddingAspectRatio

The default max aspect ratio for allowing split when the parent window is in landscape.

See also
maxAspectRatioInLandscape

SPLIT_MAX_ASPECT_RATIO_PORTRAIT_DEFAULT

val SPLIT_MAX_ASPECT_RATIO_PORTRAIT_DEFAULT: EmbeddingAspectRatio

The default max aspect ratio for allowing split when the parent window is in portrait.

See also
maxAspectRatioInPortrait

Public functions

equals

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

hashCode

open fun hashCode(): Int

toString

open fun toString(): String

Public properties

defaultSplitAttributes

Added in 1.1.0
val defaultSplitAttributes: SplitAttributes

The default SplitAttributes to apply on the activity containers pair when the host task bounds satisfy minWidthDp, minHeightDp, minSmallestWidthDp, maxAspectRatioInPortrait and maxAspectRatioInLandscape requirements.

It is set to split the host parent task vertically and equally by default.

maxAspectRatioInLandscape

Added in 1.1.0
val maxAspectRatioInLandscape: EmbeddingAspectRatio

The largest value of the aspect ratio, expressed as width / height in decimal form, of the parent window bounds in landscape when the split should be used. When the window aspect ratio is greater than requested here, activities in the secondary container will be stacked on top of the activities in the primary one, completely overlapping them.

This value is only used when the parent window is in landscape (width height).

The default is SPLIT_MAX_ASPECT_RATIO_LANDSCAPE_DEFAULT, which is the recommend value to always allow split when the parent window is in landscape.

See also
ratio
ALWAYS_ALLOW
ALWAYS_DISALLOW

maxAspectRatioInPortrait

Added in 1.1.0
val maxAspectRatioInPortrait: EmbeddingAspectRatio

The largest value of the aspect ratio, expressed as height / width in decimal form, of the parent window bounds in portrait when the split should be used. When the window aspect ratio is greater than requested here, activities in the secondary container will be stacked on top of the activities in the primary one, completely overlapping them.

This value is only used when the parent window is in portrait (height >= width).

The default is SPLIT_MAX_ASPECT_RATIO_PORTRAIT_DEFAULT, which is the recommend value to only allow split when the parent window is not too stretched in portrait.

See also
ratio
ALWAYS_ALLOW
ALWAYS_DISALLOW

minHeightDp

Added in 1.1.0
val minHeightDp: Int

The smallest value of height of the parent task window when the split should be used, in DP. When the window size is smaller than requested here, activities in the secondary container will be stacked on top of the activities in the primary one, completely overlapping them. It is useful if it's necessary to split the parent window horizontally for this SplitRule.

The default is SPLIT_MIN_DIMENSION_DP_DEFAULT if the app doesn't set. SPLIT_MIN_DIMENSION_ALWAYS_ALLOW means to always allow split.

See also
TOP_TO_BOTTOM
BOTTOM_TO_TOP

minSmallestWidthDp

Added in 1.1.0
val minSmallestWidthDp: Int

The smallest value of the smallest possible width of the parent task window in any rotation when the split should be used, in DP. When the window size is smaller than requested here, activities in the secondary container will be stacked on top of the activities in the primary one, completely overlapping them.

The default is SPLIT_MIN_DIMENSION_DP_DEFAULT if the app doesn't set. SPLIT_MIN_DIMENSION_ALWAYS_ALLOW means to always allow split.

minWidthDp

Added in 1.1.0
val minWidthDp: Int

The smallest value of width of the parent task window when the split should be used, in DP. When the window size is smaller than requested here, activities in the secondary container will be stacked on top of the activities in the primary one, completely overlapping them.

The default is SPLIT_MIN_DIMENSION_DP_DEFAULT if the app doesn't set. SPLIT_MIN_DIMENSION_ALWAYS_ALLOW means to always allow split.