public abstract class

TwoStatePreference

extends Preference

 java.lang.Object

androidx.preference.Preference

↳androidx.preference.TwoStatePreference

Subclasses:

SwitchPreference, CheckBoxPreference, SwitchPreferenceCompat

Gradle dependencies

compile group: 'androidx.preference', name: 'preference', version: '1.2.0'

  • groupId: androidx.preference
  • artifactId: preference
  • version: 1.2.0

Artifact androidx.preference:preference:1.2.0 it located at Google repository (https://maven.google.com/)

Androidx artifact mapping:

androidx.preference:preference com.android.support:preference-v7

Androidx class mapping:

androidx.preference.TwoStatePreference android.support.v7.preference.TwoStatePreference

Overview

Common base class for preferences that have two selectable states, save a boolean value, and may have dependent preferences that are enabled/disabled based on the current state.

Summary

Fields
protected booleanmChecked

from PreferenceDEFAULT_ORDER
Constructors
publicTwoStatePreference(Context context)

publicTwoStatePreference(Context context, AttributeSet attrs)

publicTwoStatePreference(Context context, AttributeSet attrs, int defStyleAttr)

publicTwoStatePreference(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Methods
public booleangetDisableDependentsState()

Returns whether dependents are disabled when this preference is on (true) or when this preference is off (false).

public java.lang.CharSequencegetSummaryOff()

Returns the summary to be shown when unchecked.

public java.lang.CharSequencegetSummaryOn()

Returns the summary to be shown when checked.

public booleanisChecked()

Returns the checked state.

protected voidonClick()

Processes a click on the preference.

protected java.lang.ObjectonGetDefaultValue(TypedArray a, int index)

Called when a preference is being inflated and the default value attribute needs to be read.

protected voidonRestoreInstanceState(Parcelable state)

Hook allowing a preference to re-apply a representation of its internal state that had previously been generated by Preference.onSaveInstanceState().

protected ParcelableonSaveInstanceState()

Hook allowing a preference to generate a representation of its internal state that can later be used to create a new instance with that same state.

protected voidonSetInitialValue(java.lang.Object defaultValue)

Implement this to set the initial value of the preference.

public voidsetChecked(boolean checked)

Sets the checked state and saves it.

public voidsetDisableDependentsState(boolean disableDependentsState)

Sets whether dependents are disabled when this preference is on (true) or when this preference is off (false).

public voidsetSummaryOff(java.lang.CharSequence summary)

Sets the summary to be shown when unchecked.

public voidsetSummaryOff(int summaryResId)

public voidsetSummaryOn(java.lang.CharSequence summary)

Sets the summary to be shown when checked.

public voidsetSummaryOn(int summaryResId)

public booleanshouldDisableDependents()

Checks whether this preference's dependents should currently be disabled.

protected voidsyncSummaryView(PreferenceViewHolder holder)

Sync a summary holder contained within holder's sub-hierarchy with the correct summary text.

protected voidsyncSummaryView(View view)

from PreferencecallChangeListener, compareTo, findPreferenceInHierarchy, getContext, getDependency, getExtras, getFragment, getIcon, getIntent, getKey, getLayoutResource, getOnPreferenceChangeListener, getOnPreferenceClickListener, getOrder, getParent, getPersistedBoolean, getPersistedFloat, getPersistedInt, getPersistedLong, getPersistedString, getPersistedStringSet, getPreferenceDataStore, getPreferenceManager, getSharedPreferences, getShouldDisableView, getSummary, getSummaryProvider, getTitle, getWidgetLayoutResource, hasKey, isCopyingEnabled, isEnabled, isIconSpaceReserved, isPersistent, isSelectable, isShown, isSingleLineTitle, isVisible, notifyChanged, notifyDependencyChange, notifyHierarchyChanged, onAttached, onAttachedToHierarchy, onAttachedToHierarchy, onBindViewHolder, onDependencyChanged, onDetached, onInitializeAccessibilityNodeInfo, onParentChanged, onPrepareForRemoval, onSetInitialValue, peekExtras, performClick, performClick, persistBoolean, persistFloat, persistInt, persistLong, persistString, persistStringSet, restoreHierarchyState, saveHierarchyState, setCopyingEnabled, setDefaultValue, setDependency, setEnabled, setFragment, setIcon, setIconSpaceReserved, setIntent, setKey, setLayoutResource, setOnPreferenceChangeListener, setOnPreferenceClickListener, setOrder, setPersistent, setPreferenceDataStore, setSelectable, setShouldDisableView, setSingleLineTitle, setSummary, setSummary, setSummaryProvider, setTitle, setTitle, setViewId, setVisible, setWidgetLayoutResource, shouldPersist, toString
from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Fields

protected boolean mChecked

Constructors

public TwoStatePreference(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

public TwoStatePreference(Context context, AttributeSet attrs, int defStyleAttr)

public TwoStatePreference(Context context, AttributeSet attrs)

public TwoStatePreference(Context context)

Methods

protected void onClick()

Processes a click on the preference. This includes saving the value to the SharedPreferences. However, the overridden method should call Preference.callChangeListener(Object) to make sure the client wants to update the preference's state with the new value.

public boolean isChecked()

Returns the checked state.

Returns:

The checked state

public void setChecked(boolean checked)

Sets the checked state and saves it.

Parameters:

checked: The checked state

public boolean shouldDisableDependents()

Checks whether this preference's dependents should currently be disabled.

Returns:

true if the dependents should be disabled, otherwise false

public void setSummaryOn(java.lang.CharSequence summary)

Sets the summary to be shown when checked.

For more complex configuration of this preference's summary, you should use a Preference.SummaryProvider

Parameters:

summary: The summary to be shown when checked

public java.lang.CharSequence getSummaryOn()

Returns the summary to be shown when checked.

Returns:

The summary

public void setSummaryOn(int summaryResId)

Parameters:

summaryResId: The summary as a resource

See also: TwoStatePreference.setSummaryOn(CharSequence)

public void setSummaryOff(java.lang.CharSequence summary)

Sets the summary to be shown when unchecked.

For more complex configuration of this preference's summary, you should use a Preference.SummaryProvider

Parameters:

summary: The summary to be shown when unchecked

public java.lang.CharSequence getSummaryOff()

Returns the summary to be shown when unchecked.

Returns:

The summary

public void setSummaryOff(int summaryResId)

Parameters:

summaryResId: The summary as a resource

See also: TwoStatePreference.setSummaryOff(CharSequence)

public boolean getDisableDependentsState()

Returns whether dependents are disabled when this preference is on (true) or when this preference is off (false).

Returns:

Whether dependents are disabled when this preference is on (true) or when this preference is off (false).

public void setDisableDependentsState(boolean disableDependentsState)

Sets whether dependents are disabled when this preference is on (true) or when this preference is off (false).

Parameters:

disableDependentsState: The preference state that should disable dependents

protected java.lang.Object onGetDefaultValue(TypedArray a, int index)

Called when a preference is being inflated and the default value attribute needs to be read. Since different preference types have different value types, the subclass should get and return the default value which will be its value type.

For example, if the value type is String, the body of the method would proxy to .

Parameters:

a: The set of attributes
index: The index of the default value attribute

Returns:

The default value of this preference type

protected void onSetInitialValue(java.lang.Object defaultValue)

Implement this to set the initial value of the preference.

If you are persisting values to SharedPreferences or a PreferenceDataStore you should restore the saved value for the preference.

If you are not persisting values, or there is no value saved for the preference, you should set the value of the preference to defaultValue.

Parameters:

defaultValue: The default value for the preference if set, otherwise null.

protected void syncSummaryView(PreferenceViewHolder holder)

Sync a summary holder contained within holder's sub-hierarchy with the correct summary text.

Parameters:

holder: A PreferenceViewHolder which holds a reference to the summary view

protected void syncSummaryView(View view)

protected Parcelable onSaveInstanceState()

Hook allowing a preference to generate a representation of its internal state that can later be used to create a new instance with that same state. This state should only contain information that is not persistent or can be reconstructed later.

Returns:

A Parcelable object containing the current dynamic state of this preference, or null if there is nothing interesting to save. The default implementation returns null.

See also: Preference.onRestoreInstanceState(Parcelable), Preference.saveHierarchyState(Bundle)

protected void onRestoreInstanceState(Parcelable state)

Hook allowing a preference to re-apply a representation of its internal state that had previously been generated by Preference.onSaveInstanceState(). This function will never be called with a null state.

Parameters:

state: The saved state that had previously been returned by Preference.onSaveInstanceState().

See also: Preference.onSaveInstanceState(), Preference.restoreHierarchyState(Bundle)

Source

/*
 * Copyright 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.preference;

import static androidx.annotation.RestrictTo.Scope.LIBRARY;

import android.content.Context;
import android.content.res.TypedArray;
import android.os.Parcel;
import android.os.Parcelable;
import android.text.TextUtils;
import android.util.AttributeSet;
import android.view.View;
import android.widget.TextView;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RestrictTo;

/**
 * Common base class for preferences that have two selectable states, save a boolean value, and
 * may have dependent preferences that are enabled/disabled based on the
 * current state.
 */
public abstract class TwoStatePreference extends Preference {

    protected boolean mChecked;
    private CharSequence mSummaryOn;
    private CharSequence mSummaryOff;
    private boolean mCheckedSet;
    private boolean mDisableDependentsState;

    public TwoStatePreference(
            @NonNull Context context, @Nullable AttributeSet attrs, int defStyleAttr,
            int defStyleRes) {
        super(context, attrs, defStyleAttr, defStyleRes);
    }

    public TwoStatePreference(@NonNull Context context, @Nullable AttributeSet attrs,
            int defStyleAttr) {
        this(context, attrs, defStyleAttr, 0);
    }

    public TwoStatePreference(@NonNull Context context, @Nullable AttributeSet attrs) {
        this(context, attrs, 0);
    }

    public TwoStatePreference(@NonNull Context context) {
        this(context, null);
    }

    @Override
    protected void onClick() {
        super.onClick();

        final boolean newValue = !isChecked();
        if (callChangeListener(newValue)) {
            setChecked(newValue);
        }
    }

    /**
     * Returns the checked state.
     *
     * @return The checked state
     */
    public boolean isChecked() {
        return mChecked;
    }

    /**
     * Sets the checked state and saves it.
     *
     * @param checked The checked state
     */
    public void setChecked(boolean checked) {
        // Always persist/notify the first time; don't assume the field's default of false.
        final boolean changed = mChecked != checked;
        if (changed || !mCheckedSet) {
            mChecked = checked;
            mCheckedSet = true;
            persistBoolean(checked);
            if (changed) {
                notifyDependencyChange(shouldDisableDependents());
                notifyChanged();
            }
        }
    }

    @Override
    public boolean shouldDisableDependents() {
        boolean shouldDisable = mDisableDependentsState ? mChecked : !mChecked;
        return shouldDisable || super.shouldDisableDependents();
    }

    /**
     * Sets the summary to be shown when checked.
     *
     * <p>For more complex configuration of this preference's summary, you should use a
     * {@link Preference.SummaryProvider}
     *
     * @param summary The summary to be shown when checked
     */
    public void setSummaryOn(@Nullable CharSequence summary) {
        mSummaryOn = summary;
        if (isChecked()) {
            notifyChanged();
        }
    }

    /**
     * Returns the summary to be shown when checked.
     *
     * @return The summary
     */
    @Nullable
    public CharSequence getSummaryOn() {
        return mSummaryOn;
    }

    /**
     * @param summaryResId The summary as a resource
     * @see #setSummaryOn(CharSequence)
     */
    public void setSummaryOn(int summaryResId) {
        setSummaryOn(getContext().getString(summaryResId));
    }

    /**
     * Sets the summary to be shown when unchecked.
     *
     * <p>For more complex configuration of this preference's summary, you should use a
     * {@link Preference.SummaryProvider}
     *
     * @param summary The summary to be shown when unchecked
     */
    public void setSummaryOff(@Nullable CharSequence summary) {
        mSummaryOff = summary;
        if (!isChecked()) {
            notifyChanged();
        }
    }

    /**
     * Returns the summary to be shown when unchecked.
     *
     * @return The summary
     */
    @Nullable
    public CharSequence getSummaryOff() {
        return mSummaryOff;
    }

    /**
     * @param summaryResId The summary as a resource
     * @see #setSummaryOff(CharSequence)
     */
    public void setSummaryOff(int summaryResId) {
        setSummaryOff(getContext().getString(summaryResId));
    }

    /**
     * Returns whether dependents are disabled when this preference is on ({@code true})
     * or when this preference is off ({@code false}).
     *
     * @return Whether dependents are disabled when this preference is on ({@code true})
     * or when this preference is off ({@code false}).
     */
    public boolean getDisableDependentsState() {
        return mDisableDependentsState;
    }

    /**
     * Sets whether dependents are disabled when this preference is on ({@code true})
     * or when this preference is off ({@code false}).
     *
     * @param disableDependentsState The preference state that should disable dependents
     */
    public void setDisableDependentsState(boolean disableDependentsState) {
        mDisableDependentsState = disableDependentsState;
    }

    @Override
    protected @Nullable Object onGetDefaultValue(@NonNull TypedArray a, int index) {
        return a.getBoolean(index, false);
    }

    @Override
    protected void onSetInitialValue(Object defaultValue) {
        if (defaultValue == null) {
            defaultValue = false;
        }
        setChecked(getPersistedBoolean((Boolean) defaultValue));
    }

    /**
     * Sync a summary holder contained within holder's sub-hierarchy with the correct summary text.
     *
     * @param holder A {@link PreferenceViewHolder} which holds a reference to the summary view
     */
    protected void syncSummaryView(@NonNull PreferenceViewHolder holder) {
        // Sync the summary holder
        View view = holder.findViewById(android.R.id.summary);
        syncSummaryView(view);
    }

    /**
     * @hide
     */
    @RestrictTo(LIBRARY)
    protected void syncSummaryView(View view) {
        if (!(view instanceof TextView)) {
            return;
        }
        TextView summaryView = (TextView) view;
        boolean useDefaultSummary = true;
        if (mChecked && !TextUtils.isEmpty(mSummaryOn)) {
            summaryView.setText(mSummaryOn);
            useDefaultSummary = false;
        } else if (!mChecked && !TextUtils.isEmpty(mSummaryOff)) {
            summaryView.setText(mSummaryOff);
            useDefaultSummary = false;
        }
        if (useDefaultSummary) {
            final CharSequence summary = getSummary();
            if (!TextUtils.isEmpty(summary)) {
                summaryView.setText(summary);
                useDefaultSummary = false;
            }
        }
        int newVisibility = View.GONE;
        if (!useDefaultSummary) {
            // Someone has written to it
            newVisibility = View.VISIBLE;
        }
        if (newVisibility != summaryView.getVisibility()) {
            summaryView.setVisibility(newVisibility);
        }
    }

    @Nullable
    @Override
    protected Parcelable onSaveInstanceState() {
        final Parcelable superState = super.onSaveInstanceState();
        if (isPersistent()) {
            // No need to save instance state since it's persistent
            return superState;
        }

        final SavedState myState = new SavedState(superState);
        myState.mChecked = isChecked();
        return myState;
    }

    @Override
    protected void onRestoreInstanceState(@Nullable Parcelable state) {
        if (state == null || !state.getClass().equals(SavedState.class)) {
            // Didn't save state for us in onSaveInstanceState
            super.onRestoreInstanceState(state);
            return;
        }

        SavedState myState = (SavedState) state;
        super.onRestoreInstanceState(myState.getSuperState());
        setChecked(myState.mChecked);
    }

    static class SavedState extends BaseSavedState {
        public static final Parcelable.Creator<SavedState> CREATOR =
                new Parcelable.Creator<SavedState>() {
                    @Override
                    public SavedState createFromParcel(Parcel in) {
                        return new SavedState(in);
                    }

                    @Override
                    public SavedState[] newArray(int size) {
                        return new SavedState[size];
                    }
                };

        boolean mChecked;

        SavedState(Parcel source) {
            super(source);
            mChecked = source.readInt() == 1;
        }

        SavedState(Parcelable superState) {
            super(superState);
        }

        @Override
        public void writeToParcel(Parcel dest, int flags) {
            super.writeToParcel(dest, flags);
            dest.writeInt(mChecked ? 1 : 0);
        }
    }
}