Starting March 27, 2025, we recommend using android-latest-release
instead of aosp-main
to build and contribute to AOSP. For more information, see Changes to AOSP.
Preference subtitles
Stay organized with collections
Save and categorize content based on your preferences.
For the most part, adding preference summaries is relatively straightforward as it
involves just adding the android:summary
attribute to the respective preference
with the appropriate string resource. However, if the subtitles should update dynamically
then a custom preference controller may be necessary.
Static subtitles
To add a static subtitle to a preference:
- Add the
android:summary
attribute to the preference. For example, to add a
summary to the L0 display settings preference, add something like the following to the
preference attributes:
android:summary="@string/display_settings_summary"
For example, consider this full preference code sample:
<Preference
android:fragment="com.android.car.settings.display.DisplaySettingsFragment"
android:icon="@drawable/ic_settings_display"
android:key="@string/pk_display_settings_entry"
android:title="@string/display_settings"
android:summary="@string/display_settings_summary"
settings:controller="com.android.car.settings.common.DefaultRestrictionsPreferenceController"/>
Dynamic subtitles
Subtitles specified with the android:summary
attribute are static so cannot
update based on certain conditions. For dynamic subtitles, you need to modify the preference
controller for the preference. The following example modifies the L0 location preference to
have a subtitle that specifies if location is on or off and, if on, state how many apps
currently have location access.
- Define the new strings:
<!-- Summary for Location settings when location is off [CHAR LIMIT=NONE] -->
<string name="location_settings_summary_location_off">Off</string>
<!-- Summary for Location settings when location is on, explaining how many apps have location permission [CHAR LIMIT=NONE]-->
<plurals name="location_settings_summary_location_on">
<item quantity="one">On - <xliff:g id="count">%1$d</xliff:g> app has access to location</item>
<item quantity="other">On - <xliff:g id="count">%1$d</xliff:g> apps have access to location</item>
</plurals>
<!-- Location settings, loading the number of apps which have location permission [CHAR LIMIT=30] -->
<string name="location_settings_loading_app_permission_stats">Loading\u2026</string>
- Create a new PreferenceController,
LocationEntryPreferenceController
, to
dynamically set and change the location preference summary text:
public class LocationEntryPreferenceController extends PreferenceController<Preference> {
private static final Logger LOG = new Logger(LocationEntryPreferenceController.class);
private static final IntentFilter INTENT_FILTER_LOCATION_MODE_CHANGED =
new IntentFilter(LocationManager.MODE_CHANGED_ACTION);
private final Context mContext;
private final LocationManager mLocationManager;
/** Total number of apps that have location permissions. */
private int mNumTotal = -1;
private int mNumTotalLoading = 0;
private AtomicInteger mLoadingInProgress = new AtomicInteger(0);
private final BroadcastReceiver mReceiver = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
refreshUi();
}
};
public LocationEntryPreferenceController(Context context, String preferenceKey,
FragmentController fragmentController, CarUxRestrictions uxRestrictions) {
super(context, preferenceKey, fragmentController, uxRestrictions);
mContext = context;
mLocationManager = (LocationManager) getContext().getSystemService(
Service.LOCATION_SERVICE);
}
@Override
protected Class<Preference> getPreferenceType() {
return Preference.class;
}
@Override
protected void onStartInternal() {
getContext().registerReceiver(mReceiver, INTENT_FILTER_LOCATION_MODE_CHANGED);
}
@Override
protected void onStopInternal() {
getContext().unregisterReceiver(mReceiver);
}
@Override
protected void updateState(Preference preference) {
super.updateState(preference);
updateSummary(preference);
if (!mLocationManager.isLocationEnabled() || mLoadingInProgress.get() != 0) {
return;
}
mNumTotalLoading = 0;
// Retrieve a list of users inside the current user profile group.
List<UserHandle> users = mContext.getSystemService(
UserManager.class).getUserProfiles();
mLoadingInProgress.set(users.size());
for (UserHandle user : users) {
Context userContext = createPackageContextAsUser(mContext, user.getIdentifier());
if (userContext == null) {
if (mLoadingInProgress.decrementAndGet() == 0) {
setLocationAppCount(preference, mNumTotalLoading);
}
continue;
}
PermissionControllerManager permController =
userContext.getSystemService(PermissionControllerManager.class);
permController.countPermissionApps(
Arrays.asList(ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION),
PermissionControllerManager.COUNT_ONLY_WHEN_GRANTED,
(numApps) -> {
mNumTotalLoading += numApps;
if (mLoadingInProgress.decrementAndGet() == 0) {
setLocationAppCount(preference, mNumTotalLoading);
}
}, null);
}
}
@VisibleForTesting
void setLocationAppCount(Preference preference, int numApps) {
mNumTotal = numApps;
updateSummary(preference);
}
private void updateSummary(Preference preference) {
String summary = "";
if (mLocationManager.isLocationEnabled()) {
if (mNumTotal == -1) {
summary = mContext.getString(R.string.location_settings_loading_app_permission_stats);
} else {
summary = mContext.getResources().getQuantityString(
R.plurals.location_settings_summary_location_on,
mNumTotal, mNumTotal);
}
} else {
summary = mContext.getString(R.string.location_settings_summary_location_off);
}
preference.setSummary(summary);
}
private Context createPackageContextAsUser(Context context, int userId) {
try {
return context.createPackageContextAsUser(
context.getPackageName(), 0 /* flags */, UserHandle.of(userId));
} catch (PackageManager.NameNotFoundException e) {
LOG.e("Failed to create user context", e);
}
return null;
}
}
For this sample controller:
- If location is disabled, summary text is set to the
location_settings_summary_location_off
string.
- If location is enabled, the number of apps that have location permission is added. While
this is loading, the
location_settings_loading_app_permission_stats
string is
shown. When the data is loaded, the controller sets the summary to the
location_settings_summary_location_on
string with the number of apps with
access specified.
- When the preference controller is started, the controller registers a receiver and
refreshes the preference state when the location state changes.
- Modify the fragment XML file to attach the new controller to the relevant preference:
<Preference
android:fragment="com.android.car.settings.location.LocationSettingsFragment"
android:icon="@drawable/ic_settings_location"
android:key="@string/pk_location_settings_entry"
android:title="@string/location_settings_title"
settings:controller="com.android.car.settings.location.LocationEntryPreferenceController"/>
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-08-29 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[],[],null,["# Preference subtitles\n\nFor the most part, adding preference summaries is relatively straightforward as it\ninvolves just adding the `android:summary` attribute to the respective preference\nwith the appropriate string resource. However, if the subtitles should update dynamically\nthen a custom preference controller may be necessary.\n\nStatic subtitles\n----------------\n\nTo add a static subtitle to a preference:\n\n1. Add the `android:summary` attribute to the preference. For example, to add a summary to the L0 display settings preference, add something like the following to the preference attributes: \n\n android:summary=\"@string/display_settings_summary\"\n\n For example, consider this full preference code sample: \n\n ```\n \u003cPreference\n android:fragment=\"com.android.car.settings.display.DisplaySettingsFragment\"\n android:icon=\"@drawable/ic_settings_display\"\n android:key=\"@string/pk_display_settings_entry\"\n android:title=\"@string/display_settings\"\n android:summary=\"@string/display_settings_summary\"\n settings:controller=\"com.android.car.settings.common.DefaultRestrictionsPreferenceController\"/\u003e\n ```\n\nDynamic subtitles\n-----------------\n\nSubtitles specified with the `android:summary` attribute are static so cannot\nupdate based on certain conditions. For dynamic subtitles, you need to modify the preference\ncontroller for the preference. The following example modifies the L0 location preference to\nhave a subtitle that specifies if location is on or off and, if on, state how many apps\ncurrently have location access.\n\n1. Define the new strings: \n\n ```\n \u003c!-- Summary for Location settings when location is off [CHAR LIMIT=NONE] --\u003e\n \u003cstring name=\"location_settings_summary_location_off\"\u003eOff\u003c/string\u003e\n \u003c!-- Summary for Location settings when location is on, explaining how many apps have location permission [CHAR LIMIT=NONE]--\u003e\n \u003cplurals name=\"location_settings_summary_location_on\"\u003e\n \u003citem quantity=\"one\"\u003eOn - \u003cxliff:g id=\"count\"\u003e%1$d\u003c/xliff:g\u003e app has access to location\u003c/item\u003e\n \u003citem quantity=\"other\"\u003eOn - \u003cxliff:g id=\"count\"\u003e%1$d\u003c/xliff:g\u003e apps have access to location\u003c/item\u003e\n \u003c/plurals\u003e\n \u003c!-- Location settings, loading the number of apps which have location permission [CHAR LIMIT=30] --\u003e\n \u003cstring name=\"location_settings_loading_app_permission_stats\"\u003eLoading\\u2026\u003c/string\u003e\n ```\n2. Create a new PreferenceController, `LocationEntryPreferenceController`, to dynamically set and change the location preference summary text: \n\n ```\n public class LocationEntryPreferenceController extends PreferenceController\u003cPreference\u003e {\n\n private static final Logger LOG = new Logger(LocationEntryPreferenceController.class);\n private static final IntentFilter INTENT_FILTER_LOCATION_MODE_CHANGED =\n new IntentFilter(LocationManager.MODE_CHANGED_ACTION);\n\n private final Context mContext;\n private final LocationManager mLocationManager;\n /** Total number of apps that have location permissions. */\n private int mNumTotal = -1;\n private int mNumTotalLoading = 0;\n private AtomicInteger mLoadingInProgress = new AtomicInteger(0);\n\n private final BroadcastReceiver mReceiver = new BroadcastReceiver() {\n @Override\n public void onReceive(Context context, Intent intent) {\n refreshUi();\n }\n };\n\n public LocationEntryPreferenceController(Context context, String preferenceKey,\n FragmentController fragmentController, CarUxRestrictions uxRestrictions) {\n super(context, preferenceKey, fragmentController, uxRestrictions);\n mContext = context;\n mLocationManager = (LocationManager) getContext().getSystemService(\n Service.LOCATION_SERVICE);\n }\n\n @Override\n protected Class\u003cPreference\u003e getPreferenceType() {\n return Preference.class;\n }\n\n @Override\n protected void onStartInternal() {\n getContext().registerReceiver(mReceiver, INTENT_FILTER_LOCATION_MODE_CHANGED);\n }\n\n @Override\n protected void onStopInternal() {\n getContext().unregisterReceiver(mReceiver);\n }\n\n @Override\n protected void updateState(Preference preference) {\n super.updateState(preference);\n updateSummary(preference);\n if (!mLocationManager.isLocationEnabled() || mLoadingInProgress.get() != 0) {\n return;\n }\n mNumTotalLoading = 0;\n // Retrieve a list of users inside the current user profile group.\n List\u003cUserHandle\u003e users = mContext.getSystemService(\n UserManager.class).getUserProfiles();\n mLoadingInProgress.set(users.size());\n for (UserHandle user : users) {\n Context userContext = createPackageContextAsUser(mContext, user.getIdentifier());\n if (userContext == null) {\n if (mLoadingInProgress.decrementAndGet() == 0) {\n setLocationAppCount(preference, mNumTotalLoading);\n }\n continue;\n }\n PermissionControllerManager permController =\n userContext.getSystemService(PermissionControllerManager.class);\n permController.countPermissionApps(\n Arrays.asList(ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION),\n PermissionControllerManager.COUNT_ONLY_WHEN_GRANTED,\n (numApps) -\u003e {\n mNumTotalLoading += numApps;\n if (mLoadingInProgress.decrementAndGet() == 0) {\n setLocationAppCount(preference, mNumTotalLoading);\n }\n }, null);\n }\n }\n\n @VisibleForTesting\n void setLocationAppCount(Preference preference, int numApps) {\n mNumTotal = numApps;\n updateSummary(preference);\n }\n\n private void updateSummary(Preference preference) {\n String summary = \"\";\n if (mLocationManager.isLocationEnabled()) {\n if (mNumTotal == -1) {\n summary = mContext.getString(R.string.location_settings_loading_app_permission_stats);\n } else {\n summary = mContext.getResources().getQuantityString(\n R.plurals.location_settings_summary_location_on,\n mNumTotal, mNumTotal);\n }\n } else {\n summary = mContext.getString(R.string.location_settings_summary_location_off);\n }\n preference.setSummary(summary);\n }\n\n private Context createPackageContextAsUser(Context context, int userId) {\n try {\n return context.createPackageContextAsUser(\n context.getPackageName(), 0 /* flags */, UserHandle.of(userId));\n } catch (PackageManager.NameNotFoundException e) {\n LOG.e(\"Failed to create user context\", e);\n }\n return null;\n }\n }\n ```\n\n For this sample controller:\n - If location is disabled, summary text is set to the `location_settings_summary_location_off` string.\n - If location is enabled, the number of apps that have location permission is added. While this is loading, the `location_settings_loading_app_permission_stats` string is shown. When the data is loaded, the controller sets the summary to the `location_settings_summary_location_on` string with the number of apps with access specified.\n - When the preference controller is started, the controller registers a receiver and refreshes the preference state when the location state changes.\n3. Modify the fragment XML file to attach the new controller to the relevant preference: \n\n ```\n \u003cPreference\n android:fragment=\"com.android.car.settings.location.LocationSettingsFragment\"\n android:icon=\"@drawable/ic_settings_location\"\n android:key=\"@string/pk_location_settings_entry\"\n android:title=\"@string/location_settings_title\"\n settings:controller=\"com.android.car.settings.location.LocationEntryPreferenceController\"/\u003e\n ```"]]