1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.settingslib.metadata 18 19 import android.content.Context 20 import android.content.ContextWrapper 21 import android.content.Intent 22 import android.os.Bundle 23 import androidx.lifecycle.LifecycleCoroutineScope 24 import com.android.settingslib.datastore.KeyValueStore 25 import kotlinx.coroutines.CoroutineScope 26 27 /** 28 * Interface to provide dynamic preference title. 29 * 30 * Implement this interface implies that the preference title should not be cached for indexing. 31 */ 32 interface PreferenceTitleProvider { 33 34 /** Provides preference title. */ getTitlenull35 fun getTitle(context: Context): CharSequence? 36 } 37 38 /** 39 * Interface to provide dynamic preference summary. 40 * 41 * Implement this interface implies that the preference summary should not be cached for indexing. 42 */ 43 interface PreferenceSummaryProvider { 44 45 /** Provides preference summary. */ 46 fun getSummary(context: Context): CharSequence? 47 } 48 49 /** 50 * Interface to provide dynamic preference icon. 51 * 52 * Implement this interface implies that the preference icon should not be cached for indexing. 53 */ 54 interface PreferenceIconProvider { 55 56 /** Provides preference icon. */ getIconnull57 fun getIcon(context: Context): Int 58 } 59 60 /** 61 * Interface to provide the state of preference availability. 62 * 63 * UI framework normally does not show the preference widget if it is unavailable. 64 */ 65 interface PreferenceAvailabilityProvider { 66 67 /** Returns if the preference is available. */ 68 fun isAvailable(context: Context): Boolean 69 } 70 71 /** 72 * Interface to provide the managed configuration state of the preference. 73 * 74 * See [Managed configurations](https://developer.android.com/work/managed-configurations) for the 75 * Android Enterprise support. 76 */ 77 interface PreferenceRestrictionProvider { 78 79 /** Returns if preference is restricted by managed configs. */ isRestrictednull80 fun isRestricted(context: Context): Boolean 81 } 82 83 /** 84 * Preference lifecycle to deal with preference state. 85 * 86 * Implement this interface when preference depends on runtime conditions. 87 */ 88 interface PreferenceLifecycleProvider { 89 90 /** 91 * Callbacks of preference fragment `onCreate`. 92 * 93 * Invoke [PreferenceLifecycleContext.notifyPreferenceChange] to update UI when any internal 94 * state (e.g. availability, enabled state, title, summary) is changed. 95 */ 96 fun onCreate(context: PreferenceLifecycleContext) {} 97 98 /** 99 * Callbacks of preference fragment `onStart`. 100 * 101 * Invoke [PreferenceLifecycleContext.notifyPreferenceChange] to update UI when any internal 102 * state (e.g. availability, enabled state, title, summary) is changed. 103 */ 104 fun onStart(context: PreferenceLifecycleContext) {} 105 106 /** 107 * Callbacks of preference fragment `onResume`. 108 * 109 * Invoke [PreferenceLifecycleContext.notifyPreferenceChange] to update UI when any internal 110 * state (e.g. availability, enabled state, title, summary) is changed. 111 */ 112 fun onResume(context: PreferenceLifecycleContext) {} 113 114 /** Callbacks of preference fragment `onPause`. */ 115 fun onPause(context: PreferenceLifecycleContext) {} 116 117 /** Callbacks of preference fragment `onStop`. */ 118 fun onStop(context: PreferenceLifecycleContext) {} 119 120 /** Callbacks of preference fragment `onDestroy`. */ 121 fun onDestroy(context: PreferenceLifecycleContext) {} 122 123 /** 124 * Receives the result from a previous call of 125 * [PreferenceLifecycleContext.startActivityForResult]. 126 * 127 * @return true if the result is handled 128 */ 129 fun onActivityResult( 130 context: PreferenceLifecycleContext, 131 requestCode: Int, 132 resultCode: Int, 133 data: Intent?, 134 ): Boolean = false 135 } 136 137 /** 138 * [Context] for preference lifecycle. 139 * 140 * A preference fragment is associated with a [PreferenceLifecycleContext] only. 141 */ 142 abstract class PreferenceLifecycleContext(context: Context) : ContextWrapper(context) { 143 144 /** 145 * [CoroutineScope] tied to the lifecycle, which is cancelled when the lifecycle is destroyed. 146 * 147 * @see [androidx.lifecycle.lifecycleScope] 148 */ 149 abstract val lifecycleScope: LifecycleCoroutineScope 150 151 /** Returns the preference widget object associated with given key. */ findPreferencenull152 abstract fun <T> findPreference(key: String): T? 153 154 /** 155 * Returns the preference widget object associated with given key. 156 * 157 * @throws NullPointerException if preference is not found 158 */ 159 abstract fun <T : Any> requirePreference(key: String): T 160 161 /** Returns the [KeyValueStore] attached to the preference of given key *on the same screen*. */ 162 abstract fun getKeyValueStore(key: String): KeyValueStore? 163 164 /** Notifies that preference state of given key is changed and updates preference widget UI. */ 165 abstract fun notifyPreferenceChange(key: String) 166 167 /** 168 * Starts activity for result, see [android.app.Activity.startActivityForResult]. 169 * 170 * This API can be invoked by any preference, the caller must ensure the request code is unique 171 * on the preference screen. 172 */ 173 abstract fun startActivityForResult(intent: Intent, requestCode: Int, options: Bundle?) 174 } 175