Merge "Noted that OnSharedPreferenceChangeListener does not store a strong... (7f24adf1) · Commits · e / os / android_frameworks_base

core/java/android/content/SharedPreferences.java

+8 −1

Original line number	Original line	Diff line number	Diff line
	@@ -356,6 +356,13 @@ public interface SharedPreferences {
	/**		/**
	* Registers a callback to be invoked when a change happens to a preference.		* Registers a callback to be invoked when a change happens to a preference.
	*		*
			* <p class="caution"><strong>Caution:</strong> The preference manager does
			* not currently store a strong reference to the listener. You must store a
			* strong reference to the listener, or it will be susceptible to garbage
			* collection. We recommend you keep a reference to the listener in the
			* instance data of an object that will exist as long as you need the
			* listener.</p>
			*
	* @param listener The callback that will run.		* @param listener The callback that will run.
	* @see #unregisterOnSharedPreferenceChangeListener		* @see #unregisterOnSharedPreferenceChangeListener
	*/		*/

docs/html/guide/topics/ui/settings.jd

+39 −3

Original line number	Original line	Diff line number	Diff line
	@@ -820,7 +820,8 @@ public class SettingsActivity extends PreferenceActivity
	public static final String KEY_PREF_SYNC_CONN = "pref_syncConnectionType";		public static final String KEY_PREF_SYNC_CONN = "pref_syncConnectionType";
	...		...

	public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {		public void onSharedPreferenceChanged(SharedPreferences sharedPreferences,
			String key) {
	if (key.equals(KEY_PREF_SYNC_CONN)) {		if (key.equals(KEY_PREF_SYNC_CONN)) {
	Preference connectionPref = findPreference(key);		Preference connectionPref = findPreference(key);
	// Set summary to be the user-description for the selected value		// Set summary to be the user-description for the selected value
	@@ -863,7 +864,40 @@ protected void onPause() {
	}		}
	</pre>		</pre>

			<p class="caution"><strong>Caution:</strong> When you call {@link
			android.content.SharedPreferences#registerOnSharedPreferenceChangeListener
			registerOnSharedPreferenceChangeListener()}, the preference manager does not
			currently store a strong reference to the listener. You must store a strong
			reference to the listener, or it will be susceptible to garbage collection. We
			recommend you keep a reference to the listener in the instance data of an object
			that will exist as long as you need the listener.</p>

			<p>For example, in the following code, the caller does not keep a reference to
			the listener. As a result, the listener will be subject to garbage collection,
			and it will fail at some indeterminate time in the future:</p>

			<pre>
			prefs.registerOnSharedPreferenceChangeListener(
			// Bad! The listener is subject to garbage collection!
			new SharedPreferences.OnSharedPreferenceChangeListener() {
			public void onSharedPreferenceChanged(SharedPreferences prefs, String key) {
			// listener implementation
			}
			});
			</pre>

			<p>Instead, store a reference to the listener in an instance data field of an
			object that will exist as long as the listener is needed:</p>

			<pre>
			SharedPreferences.OnSharedPreferenceChangeListener listener =
			new SharedPreferences.OnSharedPreferenceChangeListener() {
			public void onSharedPreferenceChanged(SharedPreferences prefs, String key) {
			// listener implementation
			}
			};
			prefs.registerOnSharedPreferenceChangeListener(listener);
			</pre>

	<h2 id="NetworkUsage">Managing Network Usage</h2>		<h2 id="NetworkUsage">Managing Network Usage</h2>

	@@ -1142,13 +1176,15 @@ protected Parcelable onSaveInstanceState() {
	final Parcelable superState = super.onSaveInstanceState();		final Parcelable superState = super.onSaveInstanceState();
	// Check whether this Preference is persistent (continually saved)		// Check whether this Preference is persistent (continually saved)
	if (isPersistent()) {		if (isPersistent()) {
	// No need to save instance state since it's persistent, use superclass state		// No need to save instance state since it's persistent,
			// use superclass state
	return superState;		return superState;
	}		}

	// Create instance of custom BaseSavedState		// Create instance of custom BaseSavedState
	final SavedState myState = new SavedState(superState);		final SavedState myState = new SavedState(superState);
	// Set the state's value with the class member that holds current setting value		// Set the state's value with the class member that holds current
			// setting value
	myState.value = mNewValue;		myState.value = mNewValue;
	return myState;		return myState;
	}		}