The summary field of PreferenceCategory tag

Question

I have seen something like this:

<PreferenceCategory xmlns:android="http://schemas.android.com/apk/res/android"
    android:key="vegi_category" android:title="Vegetables"

    android:summary="Preferences related to vegetable">  <!-- Why is this here? -->

    <CheckBoxPreference android:key="tomato_selection_pref"
        android:title="Tomato " android:summary="It's actually a fruit" />
    <CheckBoxPreference android:key="potato_selection_pref"
        android:title="Potato" android:summary="My favorite vegetable" />
</PreferenceCategory>

But I do not get it why is there a summary field for the pref category:

(android:summary="Preferences related to vegetable") ?

When I use pref screen the summary is presented in the view, but this is not a case with pref category. Is the existence of summary in pref category just a convention of it can be seen somehow ?

What is the actual usage of summary in pref category element ?

Answer 1

The standard PreferenceCategory widget shows only the title; the android:summary attribute is ignored.

That's because the default layout (preference_category.xml) contains only a single TextView for the title field:

<!-- Layout used for PreferenceCategory in a PreferenceActivity. -->
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    style="?android:attr/listSeparatorTextViewStyle"
    android:id="@+android:id/title"
/>

If you want to show the summary as well, you can specify your own layout using the android:layout attribute. For example:

<PreferenceCategory android:title="Category" android:summary="This is the summary"
                    android:layout="@layout/preference_category_summary">

Where layout/preference_category_summary.xml is something like:

<!-- Layout used for PreferenceCategory + SUMMARY in a PreferenceActivity. -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
              android:layout_width="match_parent" android:layout_height="wrap_content"
              android:orientation="vertical">
    <TextView android:id="@+android:id/title" 
              style="?android:attr/listSeparatorTextViewStyle"/>
    <TextView android:id="@+android:id/summary"
              android:paddingLeft="5dip" android:paddingRight="dip"
              android:layout_width="match_parent" android:layout_height="wrap_content"/>
</LinearLayout>

Before you go ahead and do this, however, you should consider whether it's less or more confusing to the user. Unless you style the summary text carefully, it will either jump out of the screen or appear to attach to the first preference in the category.