Register now for Android Dev Summit 2019!

LeanbackSettingsFragmentCompat

public abstract class LeanbackSettingsFragmentCompat
extends Fragment implements PreferenceFragmentCompat.OnPreferenceStartFragmentCallback, PreferenceFragmentCompat.OnPreferenceStartScreenCallback, PreferenceFragmentCompat.OnPreferenceDisplayDialogCallback

java.lang.Object
   ↳ androidx.fragment.app.Fragment
     ↳ androidx.leanback.preference.LeanbackSettingsFragmentCompat


This fragment provides a container for displaying a LeanbackPreferenceFragmentCompat

The following sample code shows a simple leanback preference fragment that is populated from a resource. The resource it loads is:

<PreferenceScreen
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto">

    <PreferenceCategory
            android:title="@string/basic_preferences">

        <Preference
                android:key="preference"
                android:title="@string/title_basic_preference"
                android:summary="@string/summary_basic_preference"/>

        <Preference
                android:key="stylized"
                android:title="@string/title_stylish_preference"
                android:summary="@string/summary_stylish_preference"/>

        <Preference
                android:key="icon"
                android:title="@string/title_icon_preference"
                android:summary="@string/summary_icon_preference"
                android:icon="@android:drawable/ic_menu_camera"/>

        <Preference
                android:key="single_line_title"
                android:title="@string/title_single_line_title_preference"
                android:summary="@string/summary_single_line_title_preference"
                app:singleLineTitle="true"/>
    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/widgets">

        <CheckBoxPreference
                android:key="checkbox"
                android:title="@string/title_checkbox_preference"
                android:summary="@string/summary_checkbox_preference"/>

        <SwitchPreferenceCompat
                android:key="switch"
                android:title="@string/title_switch_preference"
                android:summary="@string/summary_switch_preference"/>

        <DropDownPreference
                android:key="dropdown"
                android:title="@string/title_dropdown_preference"
                android:entries="@array/entries"
                app:useSimpleSummaryProvider="true"
                android:entryValues="@array/entry_values"/>

        <SeekBarPreference
                android:key="seekbar"
                android:title="@string/title_seekbar_preference"
                android:max="10"
                android:defaultValue="5"/>
    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/dialogs">

        <EditTextPreference
                android:key="edittext"
                android:title="@string/title_edittext_preference"
                app:useSimpleSummaryProvider="true"
                android:dialogTitle="@string/dialog_title_edittext_preference"/>

        <ListPreference
                android:key="list"
                android:title="@string/title_list_preference"
                app:useSimpleSummaryProvider="true"
                android:entries="@array/entries"
                android:entryValues="@array/entry_values"
                android:dialogTitle="@string/dialog_title_list_preference"/>

        <MultiSelectListPreference
                android:key="multi_select_list"
                android:title="@string/title_multi_list_preference"
                android:summary="@string/summary_multi_list_preference"
                android:entries="@array/entries"
                android:entryValues="@array/entry_values"
                android:dialogTitle="@string/dialog_title_multi_list_preference"/>
    </PreferenceCategory>

    <PreferenceCategory
            android:key="advanced"
            android:title="@string/advanced_attributes"
            app:initialExpandedChildrenCount="1">

        <Preference
                android:key="expandable"
                android:title="@string/title_expandable_preference"
                android:summary="@string/summary_expandable_preference"/>

        <Preference
                android:title="@string/title_intent_preference"
                android:summary="@string/summary_intent_preference">

            <intent android:action="android.intent.action.VIEW"
                    android:data="http://www.android.com"/>

        </Preference>

        <SwitchPreferenceCompat
                android:key="parent"
                android:title="@string/title_parent_preference"
                android:summary="@string/summary_parent_preference"/>

        <SwitchPreferenceCompat
                android:key="child"
                android:dependency="parent"
                android:title="@string/title_child_preference"
                android:summary="@string/summary_child_preference"/>

        <SwitchPreferenceCompat
                android:key="toggle_summary"
                android:title="@string/title_toggle_summary_preference"
                android:summaryOn="@string/summary_on_toggle_summary_preference"
                android:summaryOff="@string/summary_off_toggle_summary_preference"/>

        <Preference
                android:key="copyable"
                android:title="@string/title_copyable_preference"
                android:summary="@string/summary_copyable_preference"
                android:selectable="false"
                app:enableCopying="true"/>
    </PreferenceCategory>

</PreferenceScreen>

The sample implements PreferenceFragmentCompat.OnPreferenceStartFragmentCallback.onPreferenceStartFragment(PreferenceFragmentCompat, Preference), PreferenceFragmentCompat.OnPreferenceStartScreenCallback.onPreferenceStartScreen(PreferenceFragmentCompat, PreferenceScreen), and onPreferenceStartInitialScreen():

public static class SettingsFragment extends LeanbackSettingsFragmentCompat {
    @Override
    public void onPreferenceStartInitialScreen() {
        startPreferenceFragment(new DemoFragment());
    }

    @Override
    public boolean onPreferenceStartFragment(PreferenceFragmentCompat caller, Preference pref) {
        final Bundle args = pref.getExtras();
        final Fragment f = getChildFragmentManager().getFragmentFactory().instantiate(
                requireActivity().getClassLoader(), pref.getFragment());
        f.setArguments(args);
        f.setTargetFragment(caller, 0);
        if (f instanceof PreferenceFragmentCompat
                || f instanceof PreferenceDialogFragmentCompat) {
            startPreferenceFragment(f);
        } else {
            startImmersiveFragment(f);
        }
        return true;
    }

    @Override
    public boolean onPreferenceStartScreen(PreferenceFragmentCompat caller,
            PreferenceScreen pref) {
        final Fragment fragment = new DemoFragment();
        final Bundle args = new Bundle(1);
        args.putString(PreferenceFragmentCompat.ARG_PREFERENCE_ROOT, pref.getKey());
        fragment.setArguments(args);
        startPreferenceFragment(fragment);
        return true;
    }
}

/**
 * The fragment that is embedded in SettingsFragment
 */
public static class DemoFragment extends LeanbackPreferenceFragmentCompat {

    @Override
    public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
        // Load the preferences from an XML resource
        setPreferencesFromResource(R.xml.preferences, rootKey);
    }
}

Summary

Public constructors

LeanbackSettingsFragmentCompat()

Public methods

View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)

Called to have the fragment instantiate its user interface view.

void onPause()

Called when the Fragment is no longer resumed.

boolean onPreferenceDisplayDialog(PreferenceFragmentCompat caller, Preference pref)
abstract void onPreferenceStartInitialScreen()

Called to instantiate the initial PreferenceFragment to be shown in this fragment.

void onResume()

Called when the fragment is visible to the user and actively running.

void onViewCreated(View view, Bundle savedInstanceState)

Called immediately after onCreateView(LayoutInflater, ViewGroup, Bundle) has returned, but before any saved state has been restored in to the view.

void startImmersiveFragment(Fragment fragment)

Displays a fragment to the user, temporarily replacing the contents of this fragment.

void startPreferenceFragment(Fragment fragment)

Displays a preference fragment to the user.

Inherited methods

Public constructors

LeanbackSettingsFragmentCompat

public LeanbackSettingsFragmentCompat ()

Public methods

onCreateView

public View onCreateView (LayoutInflater inflater, 
                ViewGroup container, 
                Bundle savedInstanceState)

Called to have the fragment instantiate its user interface view. This is optional, and non-graphical fragments can return null. This will be called between onCreate(Bundle) and onActivityCreated(Bundle).

A default View can be returned by calling Fragment(int) in your constructor. Otherwise, this method returns null.

It is recommended to only inflate the layout in this method and move logic that operates on the returned View to onViewCreated(View, Bundle).

If you return a View from here, you will later be called in onDestroyView() when the view is being released.

Parameters
inflater LayoutInflater: The LayoutInflater object that can be used to inflate any views in the fragment,

container ViewGroup: If non-null, this is the parent view that the fragment's UI should be attached to. The fragment should not add the view itself, but this can be used to generate the LayoutParams of the view.

savedInstanceState Bundle: If non-null, this fragment is being re-constructed from a previous saved state as given here.

Returns
View Return the View for the fragment's UI, or null.

onPause

public void onPause ()

Called when the Fragment is no longer resumed. This is generally tied to Activity.onPause of the containing Activity's lifecycle.

onPreferenceDisplayDialog

public boolean onPreferenceDisplayDialog (PreferenceFragmentCompat caller, 
                Preference pref)

Parameters
caller PreferenceFragmentCompat

pref Preference

Returns
boolean

onPreferenceStartInitialScreen

public abstract void onPreferenceStartInitialScreen ()

Called to instantiate the initial PreferenceFragment to be shown in this fragment. Implementations are expected to call startPreferenceFragment(Fragment).

onResume

public void onResume ()

Called when the fragment is visible to the user and actively running. This is generally tied to Activity.onResume of the containing Activity's lifecycle.

onViewCreated

public void onViewCreated (View view, 
                Bundle savedInstanceState)

Called immediately after onCreateView(LayoutInflater, ViewGroup, Bundle) has returned, but before any saved state has been restored in to the view. This gives subclasses a chance to initialize themselves once they know their view hierarchy has been completely created. The fragment's view hierarchy is not however attached to its parent at this point.

Parameters
view View: The View returned by onCreateView(LayoutInflater, ViewGroup, Bundle).

savedInstanceState Bundle: If non-null, this fragment is being re-constructed from a previous saved state as given here.

startImmersiveFragment

public void startImmersiveFragment (Fragment fragment)

Displays a fragment to the user, temporarily replacing the contents of this fragment.

Parameters
fragment Fragment: Fragment instance to be added.

startPreferenceFragment

public void startPreferenceFragment (Fragment fragment)

Displays a preference fragment to the user. This method can also be used to display list-style fragments on top of the stack of preference fragments.

Parameters
fragment Fragment: Fragment instance to be added.