SplitPairRule.Builder

public final class SplitPairRule.Builder

Builder for SplitPairRule.

Summary

Public constructors

Public methods
final @NonNull SplitPairRule

Builds a SplitPairRule instance.
final @NonNull SplitPairRule.Builder
setClearTop(boolean clearTop)

Sets whether the existing secondary container on top and all activities in it should be destroyed when a new split is created using this rule.
final @NonNull SplitPairRule.Builder
setDefaultSplitAttributes(
    @NonNull SplitAttributes defaultSplitAttributes
)

Sets 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 SplitPairRule.Builder
setFinishPrimaryWithSecondary(
    @NonNull SplitRule.FinishBehavior finishPrimaryWithSecondary
)

Sets the behavior of the primary container when all activities are finished in the associated secondary container.
final @NonNull SplitPairRule.Builder
setFinishSecondaryWithPrimary(
    @NonNull SplitRule.FinishBehavior finishSecondaryWithPrimary
)

Sets the behavior of the secondary container when all activities are finished in the associated primary container.
final @NonNull SplitPairRule.Builder

Sets 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 SplitPairRule.Builder

Sets 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 @NonNull SplitPairRule.Builder
setMinHeightDp(@IntRange(from = 0) int minHeightDp)

Sets the smallest value of height of the parent task window when the split should be used, in DP.
final @NonNull SplitPairRule.Builder
setMinSmallestWidthDp(@IntRange(from = 0) int minSmallestWidthDp)

Sets the smallest value of the smallest possible width of the parent window in any rotation when the split should be used, in DP.
final @NonNull SplitPairRule.Builder
setMinWidthDp(@IntRange(from = 0) int minWidthDp)

Sets the smallest value of width of the parent window when the split should be used, in DP.
final @NonNull SplitPairRule.Builder

Sets a unique string to identify this SplitPairRule, which defaults to null.

Public constructors

Builder

Added in 1.1.0
public Builder(@NonNull Set<@NonNull SplitPairFilter> filters)
Parameters
@NonNull Set<@NonNull SplitPairFilter> filters

Filters used to choose when to apply this rule. The rule may be used if any one of the provided filters matches.

Public methods

build

Added in 1.1.0
public final @NonNull SplitPairRule build()

Builds a SplitPairRule instance.

Returns
@NonNull SplitPairRule

The new SplitPairRule instance.

setClearTop

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setClearTop(boolean clearTop)

Sets whether the existing secondary container on top and all activities in it should be destroyed when a new split is created using this rule. Otherwise the new secondary will appear on top by default.

Parameters
boolean clearTop

whether the existing secondary container on top and all activities in it should be destroyed when a new split is created using this rule.

setDefaultSplitAttributes

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setDefaultSplitAttributes(
    @NonNull SplitAttributes defaultSplitAttributes
)

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

Parameters
@NonNull SplitAttributes defaultSplitAttributes

the default SplitAttributes to apply on the activity containers pair when the host task bounds satisfy all the rule requirements.

setFinishPrimaryWithSecondary

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setFinishPrimaryWithSecondary(
    @NonNull SplitRule.FinishBehavior finishPrimaryWithSecondary
)

Sets the behavior of the primary container when all activities are finished in the associated secondary container.

Parameters
@NonNull SplitRule.FinishBehavior finishPrimaryWithSecondary

the SplitRule.FinishBehavior of the primary container when all activities are finished in the associated secondary container.
See also
NEVER
ALWAYS
ADJACENT

setFinishSecondaryWithPrimary

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setFinishSecondaryWithPrimary(
    @NonNull SplitRule.FinishBehavior finishSecondaryWithPrimary
)

Sets the behavior of the secondary container when all activities are finished in the associated primary container.

Parameters
@NonNull SplitRule.FinishBehavior finishSecondaryWithPrimary

the SplitRule.FinishBehavior of the secondary container when all activities are finished in the associated primary container.
See also
NEVER
ALWAYS
ADJACENT

setMaxAspectRatioInLandscape

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setMaxAspectRatioInLandscape(@NonNull EmbeddingAspectRatio aspectRatio)

Sets 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 if the app doesn't set, which is the recommend value to always allow split when the parent window is in landscape.

Parameters
@NonNull EmbeddingAspectRatio aspectRatio

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.
See also
ratio
ALWAYS_ALLOW
ALWAYS_DISALLOW

setMaxAspectRatioInPortrait

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setMaxAspectRatioInPortrait(@NonNull EmbeddingAspectRatio aspectRatio)

Sets 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 if the app doesn't set, which is the recommend value to only allow split when the parent window is not too stretched in portrait.

Parameters
@NonNull EmbeddingAspectRatio aspectRatio

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.
See also
ratio
ALWAYS_ALLOW
ALWAYS_DISALLOW

setMinHeightDp

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setMinHeightDp(@IntRange(from = 0) int minHeightDp)

Sets 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 SplitPairRule.

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

Parameters
@IntRange(from = 0) int minHeightDp

the smallest value of height of the parent task window when the split should be used, in DP.
See also
TOP_TO_BOTTOM
BOTTOM_TO_TOP

setMinSmallestWidthDp

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setMinSmallestWidthDp(@IntRange(from = 0) int minSmallestWidthDp)

Sets the smallest value of the smallest possible width of the parent 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.

Parameters
@IntRange(from = 0) int minSmallestWidthDp

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

setMinWidthDp

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setMinWidthDp(@IntRange(from = 0) int minWidthDp)

Sets the smallest value of width of the parent 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.

Parameters
@IntRange(from = 0) int minWidthDp

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

setTag

Added in 1.1.0
public final @NonNull SplitPairRule.Builder setTag(String tag)

Sets a unique string to identify this SplitPairRule, which defaults to null. The suggested usage is to set the tag to be able to differentiate between different rules in the SplitAttributesCalculatorParams.splitRuleTag.

Parameters
String tag

unique string to identify this SplitPairRule.