RuleController

class RuleController


The controller to manage EmbeddingRules. It supports:

Note that this class is recommended to be configured in androidx.startup.Initializer or android.app.Application.onCreate, so that the rules are applied early in the application startup before any activities complete initialization. The rule updates only apply to future android.app.Activity launches and do not apply to already running activities.

Summary

Public companion functions

RuleController
getInstance(context: Context)

Obtains an instance of RuleController.

Set<EmbeddingRule>
parseRules(context: Context, staticRuleResourceId: @XmlRes Int)

Parses EmbeddingRules from XML rule definitions.

Public functions

Unit

Registers a new rule, or updates an existing rule if the tag has been registered with RuleController.

Unit

Clears the rules previously registered by addRule or setRules.

Set<EmbeddingRule>

Returns a copy of the currently registered rules.

Unit

Unregisters a rule that was previously registered via addRule or setRules.

Unit

Sets a set of EmbeddingRules, which replace all rules registered by addRule or setRules.

Public companion functions

getInstance

Added in 1.1.0
fun getInstance(context: Context): RuleController

Obtains an instance of RuleController.

Parameters
context: Context

the Context to initialize the controller with

parseRules

Added in 1.1.0
fun parseRules(context: Context, staticRuleResourceId: @XmlRes Int): Set<EmbeddingRule>

Parses EmbeddingRules from XML rule definitions.

The EmbeddingRules can then set by setRules.

Parameters
context: Context

the context that contains the XML rule definition resources

staticRuleResourceId: @XmlRes Int

the resource containing the static split rules.

Throws
kotlin.IllegalArgumentException

if any of the rules in the XML are malformed.

Public functions

addRule

Added in 1.1.0
fun addRule(rule: EmbeddingRule): Unit

Registers a new rule, or updates an existing rule if the tag has been registered with RuleController. Will be cleared automatically when the process is stopped.

Registering a SplitRule may fail if the SplitController.splitSupportStatus returns false. If not supported, it could be either because androidx.window.WindowProperties.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED not enabled in AndroidManifest or the feature not available on the device.

Note that registering a new rule or updating the existing rule will not be applied to any existing split activity container, and will only be used for new split containers created with future activity launches.

Parameters
rule: EmbeddingRule

new EmbeddingRule to register.

clearRules

Added in 1.1.0
fun clearRules(): Unit

Clears the rules previously registered by addRule or setRules.

getRules

Added in 1.1.0
fun getRules(): Set<EmbeddingRule>

Returns a copy of the currently registered rules.

removeRule

Added in 1.1.0
fun removeRule(rule: EmbeddingRule): Unit

Unregisters a rule that was previously registered via addRule or setRules.

Parameters
rule: EmbeddingRule

the previously registered EmbeddingRule to unregister.

setRules

fun setRules(rules: Set<EmbeddingRule>): Unit

Sets a set of EmbeddingRules, which replace all rules registered by addRule or setRules.

It's recommended to set the rules via an androidx.startup.Initializer, or android.app.Application.onCreate, so that they are applied early in the application startup before any activities appear.

The EmbeddingRules can be parsed from parseRules or built with rule Builders, which are:

Registering SplitRules may fail if the SplitController.splitSupportStatus returns false. If not supported, it could be either because androidx.window.WindowProperties.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED not enabled in AndroidManifest or the feature not available on the device.

Note that updating the existing rules will not be applied to any existing split activity container, and will only be used for new split containers created with future activity launches.

Parameters
rules: Set<EmbeddingRule>

The EmbeddingRules to set

Throws
kotlin.IllegalArgumentException

if rules contains two EmbeddingRules with the same EmbeddingRule.tag.