SplitRule

public class SplitRule extends EmbeddingRule

java.lang.Object
   ↳ 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
public final class SplitRule.FinishBehavior

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

Constants
static final int

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

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

Public fields
static final @NonNull EmbeddingAspectRatio

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

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

Public methods
boolean
equals(Object other)
final @NonNull SplitAttributes

The default SplitAttributes to apply on the activity containers pair when the host task bounds satisfy minWidthDp, minHeightDp, minSmallestWidthDp, maxAspectRatioInPortrait and maxAspectRatioInLandscape requirements.
final @NonNull 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.
final @NonNull 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.
final int

The smallest value of height of the parent task window when the split should be used, in DP.
final 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.
final int

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

Inherited methods
From androidx.window.embedding.EmbeddingRule
final String

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

Constants

SPLIT_MIN_DIMENSION_ALWAYS_ALLOW

public static final int SPLIT_MIN_DIMENSION_ALWAYS_ALLOW = 0

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

See also
minWidthDp
minSmallestWidthDp

SPLIT_MIN_DIMENSION_DP_DEFAULT

public static final int SPLIT_MIN_DIMENSION_DP_DEFAULT = 600

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 fields

SPLIT_MAX_ASPECT_RATIO_LANDSCAPE_DEFAULT

public static final @NonNull EmbeddingAspectRatio SPLIT_MAX_ASPECT_RATIO_LANDSCAPE_DEFAULT

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

See also
maxAspectRatioInLandscape

SPLIT_MAX_ASPECT_RATIO_PORTRAIT_DEFAULT

public static final @NonNull EmbeddingAspectRatio SPLIT_MAX_ASPECT_RATIO_PORTRAIT_DEFAULT

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

See also
maxAspectRatioInPortrait

Public methods

equals

public boolean equals(Object other)

getDefaultSplitAttributes

Added in 1.1.0
public final @NonNull SplitAttributes getDefaultSplitAttributes()

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.

getMaxAspectRatioInLandscape

Added in 1.1.0
public final @NonNull EmbeddingAspectRatio getMaxAspectRatioInLandscape()

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

getMaxAspectRatioInPortrait

Added in 1.1.0
public final @NonNull EmbeddingAspectRatio getMaxAspectRatioInPortrait()

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

getMinHeightDp

Added in 1.1.0
public final int getMinHeightDp()

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

getMinSmallestWidthDp

Added in 1.1.0
public final int getMinSmallestWidthDp()

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.

getMinWidthDp

Added in 1.1.0
public final int getMinWidthDp()

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.

hashCode

public int hashCode()

toString

public @NonNull String toString()