Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 619cd2a8 authored by Alejandro Nijamkin's avatar Alejandro Nijamkin
Browse files

Developer-facing document for quick affordances 

This is a guide for developers for how to add new quick affordance
buttons to the lockscreen.

Bug: 235403546
Test: N/A
Change-Id: Id8417c48732e25331027f11442c16d0220e690c4
parent f32a6f88

packages/SystemUI/docs/device-entry/keyguard.md

+4 −0
Original line number Diff line number Diff line
@@ -30,6 +30,10 @@ An indication to power off the device most likely comes from one of two signals: 


### How the device locks



### Quick Affordances



These are interactive UI elements that appear on the lockscreen when the device is locked. They allow the user to perform quick actions without unlocking their device. To learn more about them, please see [this dedicated document](quickaffordance.md)



## Debugging Tips

Enable verbose keyguard logs that will print to logcat. Should only be used temporarily for debugging. See [KeyguardConstants][5].

```

packages/SystemUI/docs/device-entry/quickaffordance.md

0 → 100644
+25 −0
Original line number Diff line number Diff line 
# Keyguard Quick Affordances

These are interactive UI elements that appear at the bottom of the lockscreen when the device is

locked. They allow the user to perform quick actions without unlocking their device. For example:

opening an screen that lets them control the smart devices in their home, access their touch-to-pay

credit card, etc.



## Adding a new Quick Affordance

### Step 1: create a new quick affordance config

* Create a new class under the [systemui/keyguard/data/quickaffordance](../../src/com/android/systemui/keyguard/data/quickaffordance) directory

* Please make sure that the class is injected through the Dagger dependency injection system by using the `@Inject` annotation on its main constructor and the `@SysUISingleton` annotation at class level, to make sure only one instance of the class is ever instantiated

* Have the class implement the [KeyguardQuickAffordanceConfig](../../src/com/android/systemui/keyguard/data/quickaffordance/KeyguardQuickAffordanceConfig.kt) interface, notes:

  * The `state` Flow property must emit `State.Hidden` when the feature is not enabled!

  * It is safe to assume that `onQuickAffordanceClicked` will not be invoked if-and-only-if the previous rule is followed

  * When implementing `onQuickAffordanceClicked`, the implementation can do something or it can ask the framework to start an activity using an `Intent` provided by the implementation

* Please include a unit test for your new implementation under [the correct directory](../../tests/src/com/android/systemui/keyguard/data/quickaffordance)



### Step 2: choose a position and priority

* Add the new class as a dependency in the constructor of [KeyguardQuickAffordanceConfigs](../../src/com/android/systemui/keyguard/data/repository/KeyguardQuickAffordanceConfigs.kt)

* Place the new class in one of the available positions in the `configsByPosition` property, note:

  * In each position, there is a list. The order matters. The order of that list is the priority order in which the framework considers each config. The first config whose state property returns `State.Visible` determines the button that is shown for that position

  * Please only add to one position. The framework treats each position individually and there is no good way to prevent the same config from making its button appear in more than one position at the same time



### Step 3: manually verify the new quick affordance

* Build and launch SysUI on a device

* Verify that the quick affordance button for the new implementation is correctly visible and clicking it does the right thing