diff --git a/packages/SystemUI/docs/clock-plugins.md b/packages/SystemUI/docs/clock-plugins.md index 5e4f6c79f47a1..2226d7956ded8 100644 --- a/packages/SystemUI/docs/clock-plugins.md +++ b/packages/SystemUI/docs/clock-plugins.md @@ -1,35 +1,92 @@ # Clock Plugins -## Introduction - The clock appearing on the lock screen and always on display (AOD) can be -customized via the ClockPlugin plugin interface. +customized via the ClockProviderPlugin plugin interface. + +## Lock screen integration +The lockscreen code has two main components, a [clock customization library](../customization), and +the SystemUI [lockscreen host code](../src/com/android/keyguard). The customization library contains +the default clock, and some support code for managing clocks and picking the correct one to render. +It is used by both SystemUI for rendering and ThemePicker for selecting clocks. The SystemUI host is +responsible for maintaining the view within the hierarchy and propagating events to the rendered +clock controller. + +### Clock Library Code +[ClockProvider and ClockController](../plugin/src/com/android/systemui/plugins/ClockProviderPlugin.kt) +serve as the interface between the lockscreen (or other host application) and the clock that is +being rendered. Implementing these interfaces is the primary integration point for rendering clocks +in SystemUI. Many of the methods have an empty default implementation and are optional for +implementations if the related event is not interesting to your use case. + +[DefaultClockProvider](../customization/src/com/android/systemui/shared/clocks/DefaultClockProvider.kt) and +[DefaultClockController](../customization/src/com/android/systemui/shared/clocks/DefaultClockController.kt) +implement these interfaces for the default lockscreen clock. They handle relevant events from the +lockscreen to update and control the small and large clock view as appropriate. +[AnimatableClockView](../customization/src/com/android/systemui/shared/clocks/AnimatableClockView.kt) +is the view that DefaultClockController uses to render both the small and large clock. +AnimatableClockView has moved location within the repo, but is largely unchanged from previous +versions of android. + +The [ClockRegistry](../customization/src/com/android/systemui/shared/clocks/ClockRegistry.kt) +determines which clock should be shown, and handles creating them. It does this by maintaining a +list of [ClockProviders](../plugin/src/com/android/systemui/plugins/ClockProviderPlugin.kt) and +delegating work to them as appropriate. The DefaultClockProvider is compiled in so that it is +guaranteed to be available, and additional ClockProviders are loaded at runtime via +[PluginManager](../plugin_core/src/com/android/systemui/plugins/PluginManager.java). + +[ClockPlugin](../plugin/src/com/android/systemui/plugins/ClockPlugin.java) is deprecated and no +longer used by keyguard to render clocks. The host code has been disabled but most of it is still +present in the source tree, although it will likely be removed in a later patch. + +### Lockscreen Host +[ClockEventController](../src/com/android/keyguard/ClockEventController.kt) propagates events from +SystemUI event dispatchers to the clock controllers. It maintains a set of event listeners, but +otherwise attempts to do as little work as possible. It does maintain some state where necessary. + +[KeyguardClockSwitchController](../src/com/android/keyguard/KeyguardClockSwitchController.java) is +the primary controller for the [KeyguardClockSwitch](../src/com/android/keyguard/KeyguardClockSwitch.java), +which serves as the view parent within SystemUI. Together they ensure the correct clock (either +large or small) is shown, handle animation between clock sizes, and control some sizing/layout +parameters for the clocks. + +### Creating a custom clock +In order to create a custom clock, a partner must: + - Write an implementation of ClockProviderPlugin and the subinterfaces relevant to your use-case. + - Build this into a seperate plugin apk, and deploy that apk to the device. + - Alternatively, it could be compiled directly into the customization lib like DefaultClockProvider. + - PluginManager should automatically notify ClockRegistry of your plugin apk when it arrives on + device. ClockRegistry will print info logs when it successfully loads a plugin. + - Set the clock either in ThemePicker or through adb: + `adb shell settings put secure lock_screen_custom_clock_face '''{\"clockId\":\"ID\"}'''` + - SystemUI should immediately load and render the new clock if it is available. + +### Picker integration +Picker logic for choosing between clocks is available to our partners as part of the ThemePicker. +The clock picking UI will be enabled by default if there is more than 1 clock provided, otherwise +it will be hidden from the UI. ## System Health -Clocks are high risk for battery consumption and screen burn-in because they -modify the UI of AOD. +Clocks are high risk for battery consumption and screen burn-in because they modify the UI of AOD. -To reduce battery consumption, it is recommended to -target a maximum on-pixel-ratio (OPR) of 5%. Clocks that are composed of -large blocks of color that cause the OPR to exceed 5% should be avoided. +To reduce battery consumption, it is recommended to target a maximum on-pixel-ratio (OPR) of 10%. +Clocks that are composed of large blocks of color that cause the OPR to exceed 10% should be +avoided, but this target will differ depending on the device hardware. -To prevent screen burn-in, clocks should not be composed of large solid -blocks of color, and the clock should be moved around the screen to -distribute the on pixels across a large number of pixels. Software -burn-in testing is a good starting point to assess the pixel shifting -(clock movement) scheme and shape of the clock. +To prevent screen burn-in, clocks should not be composed of large solid blocks of color, and the +clock should be moved around the screen to distribute the on pixels across a large number of pixels. +Software burn-in testing is a good starting point to assess the pixel shifting (clock movement) +scheme and shape of the clock. SystemUI currently treats all clocks the same in this regard using +[KeyguardClockPositionAlgorithm](../src/com/android/systemui/statusbar/phone/KeyguardClockPositionAlgorithm.java) ### Software Burn-In Test -The goal is to look for bright spots in the luminosity average over a period of -time. It is difficult to define a threshold where burn-in will occur. It is, -therefore, recommended to compare against an element on AOD that is known not -to cause problems. +The goal is to look for bright spots in the luminosity average over a period of time. It is +difficult to define a threshold where burn-in will occur. It is, therefore, recommended to compare +against an element on AOD that is known not to cause problems. -For clock face that contain color, it is recommended to use an all white -version of the face. Since white has the highest luminosity, this version of -the clock face represents the worst case scenario. +For clock face that contain color, it is recommended to use an all white version of the face. Since +white has the highest luminosity, this version of the clock face represents the worst case scenario. To start, generate a sequence of screenshots for each minute over a 12 hr interval. @@ -87,6 +144,5 @@ if __name__=='__main__': main(sys.argv[1]) ``` -Look for bright spots in the luminosity average. If bright spots are found, -action should be taken to change the shape of the clock face or increase the -amount of pixel shifting. +Look for bright spots in the luminosity average. If bright spots are found, action should be taken +to change the shape of the clock face or increase the amount of pixel shifting. diff --git a/packages/SystemUI/docs/plugin_hooks.md b/packages/SystemUI/docs/plugin_hooks.md index cde5094f652eb..6ce7ee08da818 100644 --- a/packages/SystemUI/docs/plugin_hooks.md +++ b/packages/SystemUI/docs/plugin_hooks.md @@ -1,7 +1,6 @@ # Plugin hooks ### Action: com.android.systemui.action.PLUGIN_OVERLAY -Expected interface: [OverlayPlugin](/frameworks/base/packages/SystemUI/plugin/src/com/android -/systemui/plugins/OverlayPlugin.java) +Expected interface: [OverlayPlugin](/frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/OverlayPlugin.java) Use: Allows plugin access to the status bar and nav bar window for whatever nefarious purposes you can imagine. @@ -52,10 +51,10 @@ Expected interface: [NotificationSwipeActionHelper](/frameworks/base/packages/Sy Use: Control over swipes/input for notification views, can be used to control what happens when you swipe/long-press -### Action: com.android.systemui.action.PLUGIN_CLOCK -Expected interface: [ClockPlugin](/frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/ClockPlugin.java) +### Action: com.android.systemui.action.PLUGIN_CLOCK_PROVIDER +Expected interface: [ClockProviderPlugin](/frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/ClockProviderPlugin.kt) -Use: Allows replacement of the keyguard main clock. +Use: Allows replacement of the keyguard main clock. See [additional Documentation](./clock-plugins.md). ### Action: com.android.systemui.action.PLUGIN_TOAST Expected interface: [ToastPlugin](/frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/ToastPlugin.java)