# 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)

*** ** * ** ***


```
public final class RuleController
```

<br />

*** ** * ** ***

The controller to manage `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule`s. It supports:

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

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

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

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

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

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

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

## Summary

| ### Public methods |
|---|---|
| `final void` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule rule)` Registers a new rule, or updates an existing rule if the `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule#tag()` has been registered with `https://developer.android.com/reference/androidx/window/embedding/RuleController`. |
| `final void` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#clearRules()()` Clears the rules previously registered by `https://developer.android.com/reference/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule)` or `https://developer.android.com/reference/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)`. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/RuleController` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#getInstance(android.content.Context)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html context)` Obtains an instance of `https://developer.android.com/reference/androidx/window/embedding/RuleController`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Set.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule>` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#getRules()()` Returns a copy of the currently registered rules. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Set.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule>` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#parseRules(android.content.Context,kotlin.Int)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html context, @https://developer.android.com/reference/androidx/annotation/XmlRes int staticRuleResourceId)` Parses `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule`s from XML rule definitions. |
| `final void` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#removeRule(androidx.window.embedding.EmbeddingRule)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule rule)` Unregisters a rule that was previously registered via `https://developer.android.com/reference/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule)` or `https://developer.android.com/reference/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)`. |
| `final void` | `https://developer.android.com/reference/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Set.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule> rules)` Sets a set of `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule`s, which replace all rules registered by `https://developer.android.com/reference/androidx/window/embedding/RuleController#addRule(androidx.window.embedding.EmbeddingRule)` or `https://developer.android.com/reference/androidx/window/embedding/RuleController#setRules(kotlin.collections.Set)`. |

## Public methods

### addRule

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

```
public final void addRule(@NonNull EmbeddingRule rule)
```

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

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

### clearRules

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

```
public final void clearRules()
```

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

### getInstance

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

```
public static final @NonNull RuleController getInstance(@NonNull Context context)
```

Obtains an instance of `https://developer.android.com/reference/androidx/window/embedding/RuleController`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html context` | the `https://developer.android.com/reference/android/content/Context.html` to initialize the controller with |

### getRules

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

```
public final @NonNull Set<@NonNull EmbeddingRule> getRules()
```

Returns a copy of the currently registered rules.

### parseRules

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

```
public static final @NonNull Set<@NonNull EmbeddingRule> parseRules(@NonNull Context context, @XmlRes int staticRuleResourceId)
```

Parses `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule`s from XML rule definitions.

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Context.html context` | the context that contains the XML rule definition resources |
| `@https://developer.android.com/reference/androidx/annotation/XmlRes int staticRuleResourceId` | the resource containing the static split rules. |

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

### removeRule

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

```
public final void removeRule(@NonNull EmbeddingRule rule)
```

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule rule` | the previously registered `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule` to unregister. |

### setRules

```
public final void setRules(@NonNull Set<@NonNull EmbeddingRule> rules)
```

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

It's recommended to set the rules via an `https://developer.android.com/reference/androidx/startup/Initializer`, or `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 `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule`s can be parsed from `https://developer.android.com/reference/androidx/window/embedding/RuleController#parseRules(android.content.Context,kotlin.Int)` or built with rule Builders, which are:

- `https://developer.android.com/reference/androidx/window/embedding/SplitPairRule.Builder`

- `https://developer.android.com/reference/androidx/window/embedding/SplitPlaceholderRule.Builder`

- `https://developer.android.com/reference/androidx/window/embedding/ActivityRule.Builder`

Registering `SplitRule`s may fail if the `https://developer.android.com/reference/androidx/window/embedding/SplitController#splitSupportStatus()` returns `false`. If not supported, it could be either because `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Set.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule> rules` | The `https://developer.android.com/reference/androidx/window/embedding/EmbeddingRule`s to set |

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