1# Keyguard Quick Affordances 2Quick Affordances are interactive UI elements that appear on the lock screen when the device is 3locked. They allow the user to perform quick actions without necessarily unlocking their device. For example: 4opening an screen that lets them control the smart devices in their home, access their touch-to-pay 5credit card, turn on the flashlight, etc. 6 7## Creating a new Quick Affordance 8All Quick Affordances are defined in System UI code. 9 10To implement a new Quick Affordance, a developer may add a new implementation of `KeyguardQuickAffordanceConfig` in the `packages/SystemUI/src/com/android/systemui/keyguard/data/quickaffordance` package/directory and add it to the set defined in `KeyguardDataQuickAffordanceModule`. 11 12Tests belong in the `packages/SystemUI/tests/src/com/android/systemui/keyguard/data/quickaffordance` package. This should be enough for the system to pick up the new config and make it available for selection by the user. 13 14## Slots 15"Slots" is what we call the position of Quick Affordances on the lock screen. Each slot has a unique ID and a capacity denoting how many Quick Affordances can be "placed" in that slot. 16 17By default, AOSP ships with a "bottom right" and a "bottom left" slot, each with a slot capacity of `1`, allowing only one Quick Affordance on each side of the lock screen. 18 19### Customizing Slots 20OEMs may choose to enable customization of slots. An entry point in settings will appear when overriding the `custom_lockscreen_shortcuts_enabled` resource in `packages/SystemUI/res/values/config.xml`. 21 22OEMs may also choose to override the IDs and number of slots and/or override the default capacities. This can be achieved by overridding the `config_keyguardQuickAffordanceSlots` resource in `packages/SystemUI/res/values/config.xml`. 23 24### Default Quick Affordances 25OEMs may also choose to predefine default Quick Affordances for each slot. To achieve this, a developer may override the `config_keyguardQuickAffordanceDefaults` resource in `packages/SystemUI/res/values/config.xml`. Note that defaults only work until the user of the device selects a different quick affordance for that slot, even if they select the "None" option. 26 27## Selections 28"Selections" are many-to-many relationships between slots and quick affordances. We add a selection when the user selects a quick affordance for a specific slot. We remove a selection when the user un-selects a quick affordance in a slot or when the user selects an additional quick affordance for a slot that is already at capacity. The definition of each slot tells us the maximum number of quick affordances that may be selected for each slot. 29 30## Building a Quick affordance Picker Experience 31This section describes how to implement a potential picker, selector, or configuration experience for quick affordances. 32 33### Accessing Quick Affordance Data 34Quick Affordances structured data are exposed to other applications through the `KeyguardQuickAffordanceProvider` content provider which is owned by the System UI process. 35 36To access this content provider, applications must have the `android.permission.CUSTOMIZE_SYSTEM_UI` permission which is a signature and privileged permission, limiting access to system apps or apps signed by the same signature as System UI. The `KeyguardQuickAffordanceProviderContract` file defines the content provider schema for consumers. 37 38Generally speaking, there are three important tables served by the content provider: `slots`, `affordances`, and `selections`. There is also a `flags` table, but that's not important and may be ignored. 39 40The `slots`, `affordances`, and `selections` tables may be queried using their `Uri` resulting with a `Cursor` where each row represents a slot, affordance, or selection, respectively. Note that the affordance list does not include the "None" option. 41 42### Modifying Quick Affordance Data 43The `selections` table accepts `insert` or `delete` operations to either add or remove a quick affordance on a slot. 44* To add a selection of a quick affordance on a slot, execute the `insert` operation on the `selections` table `Uri` and include the `slot_id` of the slot and `affordance_id` of the affordance, both in the `ContentValues` 45* To remove a selection of a specific quick affordance from a slot, execute the `delete` operation on the `selections` table `Uri` and include the `slot_id` of the slot and the `affordance_id` of the affordance to remove as the first and second selection arguments, respectively 46* To remove all selections of any currently-selected quick affordance from a specific slot, repeat the above, but omit the `affordance_id` 47 48### The Picker Experience 49A picker experience may: 50* Show the list of available slots based on the result of the `slots` table query 51* Show the list of available quick affordances on the device (regardless of selection) based on the result of the `affordances` table query 52* Show the quick affordances already selected for each slot based on the result of the `selections` table query 53* Select one quick affordance per slot at a time 54* Unselect an already-selected quick affordance from a slot 55* Unselect all already-selected quick affordances from a slot 56 57## Device Policy 58Returning `DevicePolicyManager.KEYGUARD_DISABLE_FEATURES_ALL` or 59`DevicePolicyManager.KEYGUARD_DISABLE_SHORTCUTS_ALL` from 60`DevicePolicyManager#getKeyguardDisabledFeatures` will disable the keyguard quick affordance feature on the device. 61 62## Testing 63* Add a unit test for your implementation of `KeyguardQuickAffordanceConfig` 64* Manually verify that your implementation works in multi-user environments from both the main user and a secondary user 65 66## Debugging 67To see the current state of the system, you can run `dumpsys`: 68 69``` 70$ adb shell dumpsys activity service com.android.systemui/.SystemUIService KeyguardQuickAffordances 71``` 72 73The output will spell out the current slot configuration, selections, and collection of available affordances, for example: 74``` 75 KeyguardQuickAffordances: 76 ---------------------------------------------------------------------------- 77 Slots & selections: 78 bottom_start: home (capacity = 1) 79 bottom_end is empty (capacity = 1) 80 Available affordances on device: 81 home ("Home") 82 wallet ("Wallet") 83 qr_code_scanner ("QR code scanner") 84``` 85