diff options
| -rw-r--r-- | packages/SystemUI/docs/scene.md | 60 |
1 files changed, 59 insertions, 1 deletions
diff --git a/packages/SystemUI/docs/scene.md b/packages/SystemUI/docs/scene.md index 715d16015402..105e4385bb25 100644 --- a/packages/SystemUI/docs/scene.md +++ b/packages/SystemUI/docs/scene.md @@ -98,12 +98,16 @@ file evalutes to `true`. $ adb shell cmd statusbar echo -b SceneFramework:verbose -# Look for the log statements from the framework: +### Checking if the framework is enabled + +Look for the log statements from the framework: ```console $ adb logcat -v time SceneFramework:* *:S ``` +### Disabling the framework + To **disable** the framework, simply turn off the main aconfig flag: ```console @@ -112,6 +116,11 @@ $ adb shell device_config put systemui com.android.systemui.scene_container fals ## Defining a scene +By default, the framework ships with fully functional scenes as enumarated +[here](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/packages/SystemUI/src/com/android/systemui/scene/shared/model/SceneKey.kt). +Should a variant owner or OEM want to replace or add a new scene, they could +do so by defining their own scene. This section describes how to do that. + Each scene is defined as an implementation of the [`ComposableScene`](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/packages/SystemUI/compose/features/src/com/android/systemui/scene/ui/composable/ComposableScene.kt) interface, which has three parts: 1. The `key` property returns the @@ -305,3 +314,52 @@ top-level Dagger module at this puts together the scenes from `SceneModule`, the configuration from `SceneContainerConfigModule`, and the startable from `SceneContainerStartableModule`. + +## Integration Notes + +### Relationship to Jetpack Compose + +The scene framework depends on Jetpack Compose; therefore, compiling System UI with +Jetpack Compose is required. However, because Jetpack Compose and Android Views +[interoperate](https://developer.android.com/jetpack/compose/migrate/interoperability-apis/views-in-compose), +the UI in each scene doesn't necessarily need to be a pure hierarchy of `@Composable` +functions; instead, it's acceptable to use an `AndroidView` somewhere in the +hierarchy of composable functions to include a `View` or `ViewGroup` subtree. + +#### Interoperability with Views +The scene framework comes with built-in functionality to animate the entire scene and/or +elements within the scene in-tandem with the actual scene transition progress. + +For example, as the user drags their finger down rom the top of the lockscreen, +the shade scene becomes visible and gradually expands, the amount of expansion tracks +the movement of the finger. + +That feature of the framework uses a custom `element(ElementKey)` Jetpack Compose +`Modifier` to refer to elements within a scene. +The transition builders then use the same `ElementKey` objects to refer to those elements +and describe how they animate in-tandem with scene transitions. Because this is a +Jetpack Compose `Modifier`, it means that, in order for an element in a scene to be +animated automatically by the framework, that element must be nested within a pure +`@Composable` hierarchy. The element itself is allowed to be a classic Android `View` +(nested within a Jetpack Compose `AndroidView`) but all ancestors must be `@Composable` +functions. + +### Notifications + +As of January 2024, the integration of notifications and heads-up notifications (HUNs) +into the scene framework follows an unusual pattern. We chose this pattern due to migration +risk and performance concerns but will eventually replace it with the more common element +placement pattern that all other elements are following. + +The special pattern for notifications is that, instead of the notification list +(`NotificationStackScrollLayout` or "NSSL", which also displays HUNs) being placed in the element +hierarchy within the scenes that display notifications, the NSSL (which continues to be an Android View) +"floats" above the scene container, rendering on top of everything. This is very similar to +how NSSL is integrated with the legacy shade, prior to the scene framework. + +In order to render the NSSL as if it's part of the organic hierarchy of elements within its +scenes, we control the NSSL's self-imposed effective bounds (e.g. position offsets, clip path, +size) from `@Composable` elements within the normal scene hierarchy. These special +"placeholder" elements can be found +[here](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/packages/SystemUI/compose/features/src/com/android/systemui/notifications/ui/composable/Notifications.kt). + |