# RuleController

# RuleController

Artifact:[androidx.window:window](https://developer.android.com/jetpack/androidx/releases/window)  
[View Source](https://cs.android.com/search?q=file:androidx/window/embedding/RuleController.kt+class:androidx.window.embedding.RuleController)  
Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)

*** ** * ** ***

Kotlin\|[Java](https://developer.android.com/reference/androidx/window/embedding/RuleController "View this page in Java")

<br />

```
class RuleController
```

<br />

*** ** * ** ***

The controller to manage[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s. It supports:

- [addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))

- [removeRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#removeRule(androidx.window.embedding.EmbeddingRule))

- [setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set))

- [parseRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#parseRules(android.content.Context,kotlin.Int))

- [clearRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#clearRules())

- [getRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#getRules())

**Note** that this class is recommended to be configured in[androidx.startup.Initializer](https://developer.android.com/reference/kotlin/androidx/startup/Initializer)or[android.app.Application.onCreate](https://developer.android.com/reference/android/app/Application.html#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](https://developer.android.com/reference/android/app/Activity.html)launches and do not apply to already running activities.

## Summary

|                                                                                    ### Public companion functions                                                                                    |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [RuleController](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController)                                                                                            | [getInstance](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#getInstance(android.content.Context))`(context: `[Context](https://developer.android.com/reference/android/content/Context.html)`)` Obtains an instance of[RuleController](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController).                                                                                                                                                                                                               |
| [Set](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html)`<`[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)`>` | [parseRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#parseRules(android.content.Context,kotlin.Int))`(context: `[Context](https://developer.android.com/reference/android/content/Context.html)`, staticRuleResourceId: @`[XmlRes](https://developer.android.com/reference/kotlin/androidx/annotation/XmlRes)` `[Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)`)` Parses[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s from XML rule definitions. |

|                                                                                         ### Public functions                                                                                         |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Unit](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)                                                                                                                        | [addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))`(rule: `[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)`)` Registers a new rule, or updates an existing rule if the[tag](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule#tag())has been registered with[RuleController](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController).                                                                                                                                                                                                                                       |
| [Unit](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)                                                                                                                        | [clearRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#clearRules())`()` Clears the rules previously registered by[addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))or[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)).                                                                                                                                                                                                                                                                                                                                                 |
| [Set](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html)`<`[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)`>` | [getRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#getRules())`()` Returns a copy of the currently registered rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [Unit](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)                                                                                                                        | [removeRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#removeRule(androidx.window.embedding.EmbeddingRule))`(rule: `[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)`)` Unregisters a rule that was previously registered via[addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))or[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)).                                                                                                                                                                               |
| [Unit](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)                                                                                                                        | [setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set))`(rules: `[Set](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html)`<`[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)`>)` Sets a set of[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s, which replace all rules registered by[addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))or[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)). |

## Public companion functions

### getInstance

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)  

```
fun getInstance(context: Context): RuleController
```

Obtains an instance of[RuleController](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController).  

|                                         Parameters                                         |
|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `context: `[Context](https://developer.android.com/reference/android/content/Context.html) | the[Context](https://developer.android.com/reference/android/content/Context.html)to initialize the controller with |

### parseRules

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)  

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

Parses[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s from XML rule definitions.

The[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s can then set by[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)).  

|                                                                                         Parameters                                                                                         |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `context: `[Context](https://developer.android.com/reference/android/content/Context.html)                                                                                                 | the context that contains the XML rule definition resources |
| `staticRuleResourceId: @`[XmlRes](https://developer.android.com/reference/kotlin/androidx/annotation/XmlRes)` `[Int](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) | the resource containing the static split rules.             |

|                                                             Throws                                                             |
|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| [kotlin.IllegalArgumentException](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html) | if any of the rules in the XML are malformed. |

## Public functions

### addRule

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)  

```
fun addRule(rule: EmbeddingRule): Unit
```

Registers a new rule, or updates an existing rule if the[tag](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule#tag())has been registered with[RuleController](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController). Will be cleared automatically when the process is stopped.

Registering a`SplitRule`may fail if the[SplitController.splitSupportStatus](https://developer.android.com/reference/kotlin/androidx/window/embedding/SplitController#splitSupportStatus())returns`false`. If not supported, it could be either because[androidx.window.WindowProperties.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED](https://developer.android.com/reference/kotlin/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](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule) | new[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)to register. |

### clearRules

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)  

```
fun clearRules(): Unit
```

Clears the rules previously registered by[addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))or[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)).  

### getRules

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)  

```
fun getRules(): Set<EmbeddingRule>
```

Returns a copy of the currently registered rules.  

### removeRule

Added in[1.1.0](https://developer.android.com/jetpack/androidx/releases/window#1.1.0)  

```
fun removeRule(rule: EmbeddingRule): Unit
```

Unregisters a rule that was previously registered via[addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))or[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)).  

|                                                   Parameters                                                    |
|-----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `rule: `[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule) | the previously registered[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)to unregister. |

### setRules

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

Sets a set of[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s, which replace all rules registered by[addRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule))or[setRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)).

It's recommended to set the rules via an[androidx.startup.Initializer](https://developer.android.com/reference/kotlin/androidx/startup/Initializer), or[android.app.Application.onCreate](https://developer.android.com/reference/android/app/Application.html#onCreate()), so that they are applied early in the application startup before any activities appear.

The[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s can be parsed from[parseRules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#parseRules(android.content.Context,kotlin.Int))or built with rule Builders, which are:

- [SplitPairRule.Builder](https://developer.android.com/reference/kotlin/androidx/window/embedding/SplitPairRule.Builder)

- [SplitPlaceholderRule.Builder](https://developer.android.com/reference/kotlin/androidx/window/embedding/SplitPlaceholderRule.Builder)

- [ActivityRule.Builder](https://developer.android.com/reference/kotlin/androidx/window/embedding/ActivityRule.Builder)

Registering`SplitRule`s may fail if the[SplitController.splitSupportStatus](https://developer.android.com/reference/kotlin/androidx/window/embedding/SplitController#splitSupportStatus())returns`false`. If not supported, it could be either because[androidx.window.WindowProperties.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED](https://developer.android.com/reference/kotlin/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](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html)`<`[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)`>` | The[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s to set |

|                                                             Throws                                                             |
|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [kotlin.IllegalArgumentException](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html) | if[rules](https://developer.android.com/reference/kotlin/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set))contains two[EmbeddingRule](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule)s with the same[EmbeddingRule.tag](https://developer.android.com/reference/kotlin/androidx/window/embedding/EmbeddingRule#tag()). |