FileDocCategorySizeDatePackage
ListPreference.javaAPI DocAndroid 1.5 API9278Wed May 06 22:41:56 BST 2009android.preference

ListPreference

public class ListPreference extends DialogPreference
A {@link Preference} that displays a list of entries as a dialog.

This preference will store a string into the SharedPreferences. This string will be the value from the {@link #setEntryValues(CharSequence[])} array.

attr
ref android.R.styleable#ListPreference_entries
attr
ref android.R.styleable#ListPreference_entryValues

Fields Summary
private CharSequence[]
mEntries
private CharSequence[]
mEntryValues
private String
mValue
private int
mClickedDialogEntryIndex
Constructors Summary
public ListPreference(android.content.Context context, android.util.AttributeSet attrs)

        super(context, attrs);
        
        TypedArray a = context.obtainStyledAttributes(attrs,
                com.android.internal.R.styleable.ListPreference, 0, 0);
        mEntries = a.getTextArray(com.android.internal.R.styleable.ListPreference_entries);
        mEntryValues = a.getTextArray(com.android.internal.R.styleable.ListPreference_entryValues);
        a.recycle();
    
public ListPreference(android.content.Context context)

        this(context, null);
    
Methods Summary
public intfindIndexOfValue(java.lang.String value)
Returns the index of the given value (in the entry values array).

param
value The value whose index should be returned.
return
The index of the value, or -1 if not found.

        if (value != null && mEntryValues != null) {
            for (int i = mEntryValues.length - 1; i >= 0; i--) {
                if (mEntryValues[i].equals(value)) {
                    return i;
                }
            }
        }
        return -1;
    
public java.lang.CharSequence[]getEntries()
The list of entries to be shown in the list in subsequent dialogs.

return
The list as an array.

        return mEntries;
    
public java.lang.CharSequencegetEntry()
Returns the entry corresponding to the current value.

return
The entry corresponding to the current value, or null.

        int index = getValueIndex();
        return index >= 0 && mEntries != null ? mEntries[index] : null;
    
public java.lang.CharSequence[]getEntryValues()
Returns the array of values to be saved for the preference.

return
The array of values.

        return mEntryValues;
    
public java.lang.StringgetValue()
Returns the value of the key. This should be one of the entries in {@link #getEntryValues()}.

return
The value of the key.

        return mValue; 
    
private intgetValueIndex()

        return findIndexOfValue(mValue);
    
protected voidonDialogClosed(boolean positiveResult)

        super.onDialogClosed(positiveResult);
        
        if (positiveResult && mClickedDialogEntryIndex >= 0 && mEntryValues != null) {
            String value = mEntryValues[mClickedDialogEntryIndex].toString();
            if (callChangeListener(value)) {
                setValue(value);
            }
        }
    
protected java.lang.ObjectonGetDefaultValue(android.content.res.TypedArray a, int index)

        return a.getString(index);
    
protected voidonPrepareDialogBuilder(android.app.AlertDialog.Builder builder)

        super.onPrepareDialogBuilder(builder);
        
        if (mEntries == null || mEntryValues == null) {
            throw new IllegalStateException(
                    "ListPreference requires an entries array and an entryValues array.");
        }

        mClickedDialogEntryIndex = getValueIndex();
        builder.setSingleChoiceItems(mEntries, mClickedDialogEntryIndex, 
                new DialogInterface.OnClickListener() {
                    public void onClick(DialogInterface dialog, int which) {
                        mClickedDialogEntryIndex = which;

                        /*
                         * Clicking on an item simulates the positive button
                         * click, and dismisses the dialog.
                         */
                        ListPreference.this.onClick(dialog, DialogInterface.BUTTON_POSITIVE);
                        dialog.dismiss();
                    }
        });
        
        /*
         * The typical interaction for list-based dialogs is to have
         * click-on-an-item dismiss the dialog instead of the user having to
         * press 'Ok'.
         */
        builder.setPositiveButton(null, null);
    
protected voidonRestoreInstanceState(android.os.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());
        setValue(myState.value);
    
protected android.os.ParcelableonSaveInstanceState()

        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.value = getValue();
        return myState;
    
protected voidonSetInitialValue(boolean restoreValue, java.lang.Object defaultValue)

        setValue(restoreValue ? getPersistedString(mValue) : (String) defaultValue);
    
public voidsetEntries(java.lang.CharSequence[] entries)
Sets the human-readable entries to be shown in the list. This will be shown in subsequent dialogs.

Each entry must have a corresponding index in {@link #setEntryValues(CharSequence[])}.

param
entries The entries.
see
#setEntryValues(CharSequence[])

        mEntries = entries;
    
public voidsetEntries(int entriesResId)

see
#setEntries(CharSequence[])
param
entriesResId The entries array as a resource.

        setEntries(getContext().getResources().getTextArray(entriesResId));
    
public voidsetEntryValues(java.lang.CharSequence[] entryValues)
The array to find the value to save for a preference when an entry from entries is selected. If a user clicks on the second item in entries, the second item in this array will be saved to the preference.

param
entryValues The array to be used as values to save for the preference.

        mEntryValues = entryValues;
    
public voidsetEntryValues(int entryValuesResId)

see
#setEntryValues(CharSequence[])
param
entryValuesResId The entry values array as a resource.

        setEntryValues(getContext().getResources().getTextArray(entryValuesResId));
    
public voidsetValue(java.lang.String value)
Sets the value of the key. This should be one of the entries in {@link #getEntryValues()}.

param
value The value to set for the key.

        mValue = value;
        
        persistString(value);
    
public voidsetValueIndex(int index)
Sets the value to the given index from the entry values.

param
index The index of the value to set.

        if (mEntryValues != null) {
            setValue(mEntryValues[index].toString());
        }