2 * Copyright (C) 2011 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 package android.support.v2.app;
19 import android.app.Activity;
20 import android.content.Context;
21 import android.content.Intent;
22 import android.content.res.Configuration;
23 import android.content.res.TypedArray;
24 import android.os.Bundle;
25 import android.os.Handler;
26 import android.os.Message;
27 import android.os.Parcelable;
28 import android.util.AttributeSet;
29 import android.util.Log;
30 import android.view.KeyEvent;
31 import android.view.Menu;
32 import android.view.MenuItem;
33 import android.view.View;
34 import android.view.Window;
36 import java.io.FileDescriptor;
37 import java.io.PrintWriter;
38 import java.util.ArrayList;
39 import java.util.HashMap;
42 * Base class for activities that want to use the support-based Fragment and
45 * <p>Known limitations:</p>
47 * <li> <p>When using the <fragment> tag, this implementation can not
48 * use the parent view's ID as the new fragment's ID. You must explicitly
49 * specify an ID (or tag) in the <fragment>.</p>
50 * <li> <p>Prior to Honeycomb (3.0), an activity's state was saved before pausing.
51 * Fragments are a significant amount of new state, and dynamic enough that one
52 * often wants them to change between pausing and stopping. These classes
53 * throw an exception if you try to change the fragment state after it has been
54 * saved, to avoid accidental loss of UI state. However this is too restrictive
55 * prior to Honeycomb, where the state is saved before pausing. To address this,
56 * when running on platforms prior to Honeycomb an exception will not be thrown
57 * if you change fragments between the state save and the activity being stopped.
58 * This means that is some cases if the activity is restored from its last saved
59 * state, this may be a snapshot slightly before what the user last saw.</p>
62 public class FragmentActivity extends Activity {
63 private static final String TAG = "FragmentActivity";
65 private static final String FRAGMENTS_TAG = "android:support:fragments";
67 // This is the SDK API version of Honeycomb (3.0).
68 private static final int HONEYCOMB = 11;
70 static final int MSG_REALLY_STOPPED = 1;
72 final Handler mHandler = new Handler() {
74 public void handleMessage(Message msg) {
76 case MSG_REALLY_STOPPED:
82 super.handleMessage(msg);
87 final FragmentManagerImpl mFragments = new FragmentManagerImpl();
91 boolean mReallyStopped;
93 boolean mOptionsMenuInvalidated;
95 boolean mCheckedForLoaderManager;
96 boolean mLoadersStarted;
97 HCSparseArray<LoaderManagerImpl> mAllLoaderManagers;
98 LoaderManagerImpl mLoaderManager;
100 static final class NonConfigurationInstances {
102 HashMap<String, Object> children;
103 ArrayList<Fragment> fragments;
104 HCSparseArray<LoaderManagerImpl> loaders;
107 static class FragmentTag {
108 public static final int[] Fragment = {
109 0x01010003, 0x010100d0, 0x010100d1
111 public static final int Fragment_id = 1;
112 public static final int Fragment_name = 0;
113 public static final int Fragment_tag = 2;
116 // ------------------------------------------------------------------------
117 // HOOKS INTO ACTIVITY
118 // ------------------------------------------------------------------------
121 * Dispatch incoming result to the correct fragment.
124 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
125 int index = requestCode>>16;
128 if (mFragments.mActive == null || index < 0 || index >= mFragments.mActive.size()) {
129 Log.w(TAG, "Activity result fragment index out of range: 0x"
130 + Integer.toHexString(requestCode));
133 Fragment frag = mFragments.mActive.get(index);
135 Log.w(TAG, "Activity result no fragment exists for index: 0x"
136 + Integer.toHexString(requestCode));
138 frag.onActivityResult(requestCode&0xffff, resultCode, data);
142 super.onActivityResult(requestCode, resultCode, data);
146 * Take care of popping the fragment back stack or finishing the activity
149 public void onBackPressed() {
150 if (!mFragments.popBackStackImmediate()) {
156 * Dispatch configuration change to all fragments.
159 public void onConfigurationChanged(Configuration newConfig) {
160 super.onConfigurationChanged(newConfig);
161 mFragments.dispatchConfigurationChanged(newConfig);
165 * Perform initialization of all fragments and loaders.
168 protected void onCreate(Bundle savedInstanceState) {
169 mFragments.attachActivity(this);
170 // Old versions of the platform didn't do this!
171 if (getLayoutInflater().getFactory() == null) {
172 getLayoutInflater().setFactory(this);
175 super.onCreate(savedInstanceState);
177 NonConfigurationInstances nc = (NonConfigurationInstances)
178 getLastNonConfigurationInstance();
180 mAllLoaderManagers = nc.loaders;
182 if (savedInstanceState != null) {
183 Parcelable p = savedInstanceState.getParcelable(FRAGMENTS_TAG);
184 mFragments.restoreAllState(p, nc != null ? nc.fragments : null);
186 mFragments.dispatchCreate();
190 * Dispatch to Fragment.onCreateOptionsMenu().
193 public boolean onCreatePanelMenu(int featureId, Menu menu) {
194 if (featureId == Window.FEATURE_OPTIONS_PANEL) {
195 boolean show = super.onCreatePanelMenu(featureId, menu);
196 show |= mFragments.dispatchCreateOptionsMenu(menu, getMenuInflater());
197 //v4 if (android.os.Build.VERSION.SDK_INT >= HONEYCOMB) {
198 if (android.support.v2.os.Build.VERSION.SDK_INT >= HONEYCOMB) {
201 // Prior to Honeycomb, the framework can't invalidate the options
202 // menu, so we must always say we have one in case the app later
203 // invalidates it and needs to have it shown.
206 return super.onCreatePanelMenu(featureId, menu);
210 * Add support for inflating the <fragment> tag.
213 public View onCreateView(String name, Context context, AttributeSet attrs) {
214 if (!"fragment".equals(name)) {
215 return super.onCreateView(name, context, attrs);
218 String fname = attrs.getAttributeValue(null, "class");
219 TypedArray a = context.obtainStyledAttributes(attrs, FragmentTag.Fragment);
221 fname = a.getString(FragmentTag.Fragment_name);
223 int id = a.getResourceId(FragmentTag.Fragment_id, View.NO_ID);
224 String tag = a.getString(FragmentTag.Fragment_tag);
227 View parent = null; // NOTE: no way to get parent pre-Honeycomb.
228 int containerId = parent != null ? parent.getId() : 0;
229 if (containerId == View.NO_ID && id == View.NO_ID && tag == null) {
230 throw new IllegalArgumentException(attrs.getPositionDescription()
231 + ": Must specify unique android:id, android:tag, or have a parent with an id for " + fname);
234 // If we restored from a previous state, we may already have
235 // instantiated this fragment from the state and should use
236 // that instance instead of making a new one.
237 Fragment fragment = id != View.NO_ID ? mFragments.findFragmentById(id) : null;
238 if (fragment == null && tag != null) {
239 fragment = mFragments.findFragmentByTag(tag);
241 if (fragment == null && containerId != View.NO_ID) {
242 fragment = mFragments.findFragmentById(containerId);
245 if (FragmentManagerImpl.DEBUG) Log.v(TAG, "onCreateView: id=0x"
246 + Integer.toHexString(id) + " fname=" + fname
247 + " existing=" + fragment);
248 if (fragment == null) {
249 fragment = Fragment.instantiate(this, fname);
250 fragment.mFromLayout = true;
251 fragment.mFragmentId = id != 0 ? id : containerId;
252 fragment.mContainerId = containerId;
254 fragment.mInLayout = true;
255 fragment.mImmediateActivity = this;
256 fragment.mFragmentManager = mFragments;
257 fragment.onInflate(this, attrs, fragment.mSavedFragmentState);
258 mFragments.addFragment(fragment, true);
260 } else if (fragment.mInLayout) {
261 // A fragment already exists and it is not one we restored from
263 throw new IllegalArgumentException(attrs.getPositionDescription()
264 + ": Duplicate id 0x" + Integer.toHexString(id)
265 + ", tag " + tag + ", or parent id 0x" + Integer.toHexString(containerId)
266 + " with another fragment for " + fname);
268 // This fragment was retained from a previous instance; get it
270 fragment.mInLayout = true;
271 fragment.mImmediateActivity = this;
272 // If this fragment is newly instantiated (either right now, or
273 // from last saved state), then give it the attributes to
274 // initialize itself.
275 if (!fragment.mRetaining) {
276 fragment.onInflate(this, attrs, fragment.mSavedFragmentState);
278 mFragments.moveToState(fragment);
281 if (fragment.mView == null) {
282 throw new IllegalStateException("Fragment " + fname
283 + " did not create a view.");
286 fragment.mView.setId(id);
288 if (fragment.mView.getTag() == null) {
289 fragment.mView.setTag(tag);
291 return fragment.mView;
295 * Destroy all fragments and loaders.
298 protected void onDestroy() {
303 mFragments.dispatchDestroy();
304 if (mLoaderManager != null) {
305 mLoaderManager.doDestroy();
310 * Take care of calling onBackPressed() for pre-Eclair platforms.
313 public boolean onKeyDown(int keyCode, KeyEvent event) {
314 //v4 if (android.os.Build.VERSION.SDK_INT < 5 /* ECLAIR */
315 if (android.support.v2.os.Build.VERSION.SDK_INT < 5 /* ECLAIR */
316 && keyCode == KeyEvent.KEYCODE_BACK
317 && event.getRepeatCount() == 0) {
318 // Take care of calling this method on earlier versions of
319 // the platform where it doesn't exist.
324 return super.onKeyDown(keyCode, event);
328 * Dispatch onLowMemory() to all fragments.
331 public void onLowMemory() {
333 mFragments.dispatchLowMemory();
337 * Dispatch context and options menu to fragments.
340 public boolean onMenuItemSelected(int featureId, MenuItem item) {
341 if (super.onMenuItemSelected(featureId, item)) {
346 case Window.FEATURE_OPTIONS_PANEL:
347 return mFragments.dispatchOptionsItemSelected(item);
349 case Window.FEATURE_CONTEXT_MENU:
350 return mFragments.dispatchContextItemSelected(item);
358 * Call onOptionsMenuClosed() on fragments.
361 public void onPanelClosed(int featureId, Menu menu) {
363 case Window.FEATURE_OPTIONS_PANEL:
364 mFragments.dispatchOptionsMenuClosed(menu);
367 super.onPanelClosed(featureId, menu);
371 * Dispatch onPause() to fragments.
374 protected void onPause() {
377 mFragments.dispatchPause();
381 * Dispatch onActivityCreated() on fragments.
384 protected void onPostCreate(Bundle savedInstanceState) {
385 super.onPostCreate(savedInstanceState);
386 mFragments.dispatchActivityCreated();
390 * Dispatch onResume() to fragments.
393 protected void onPostResume() {
394 super.onPostResume();
395 mFragments.dispatchResume();
396 mFragments.execPendingActions();
400 * Dispatch onPrepareOptionsMenu() to fragments.
403 public boolean onPreparePanel(int featureId, View view, Menu menu) {
404 if (featureId == Window.FEATURE_OPTIONS_PANEL && menu != null) {
405 if (mOptionsMenuInvalidated) {
406 mOptionsMenuInvalidated = false;
408 onCreatePanelMenu(featureId, menu);
410 boolean goforit = super.onPreparePanel(featureId, view, menu);
411 goforit |= mFragments.dispatchPrepareOptionsMenu(menu);
412 return goforit && menu.hasVisibleItems();
414 return super.onPreparePanel(featureId, view, menu);
418 * Ensure any outstanding fragment transactions have been committed.
421 protected void onResume() {
424 mFragments.execPendingActions();
428 * Retain all appropriate fragment and loader state. You can NOT
429 * override this yourself!
432 public final Object onRetainNonConfigurationInstance() {
437 ArrayList<Fragment> fragments = mFragments.retainNonConfig();
438 boolean retainLoaders = false;
439 if (mAllLoaderManagers != null) {
440 // prune out any loader managers that were already stopped and so
441 // have nothing useful to retain.
442 for (int i=mAllLoaderManagers.size()-1; i>=0; i--) {
443 LoaderManagerImpl lm = mAllLoaderManagers.valueAt(i);
445 retainLoaders = true;
448 mAllLoaderManagers.removeAt(i);
452 if (fragments == null && !retainLoaders) {
456 NonConfigurationInstances nci = new NonConfigurationInstances();
459 nci.fragments = fragments;
460 nci.loaders = mAllLoaderManagers;
465 * Save all appropriate fragment state.
468 protected void onSaveInstanceState(Bundle outState) {
469 super.onSaveInstanceState(outState);
470 Parcelable p = mFragments.saveAllState();
472 outState.putParcelable(FRAGMENTS_TAG, p);
477 * Dispatch onStart() to all fragments. Ensure any created loaders are
481 protected void onStart() {
485 mHandler.removeMessages(MSG_REALLY_STOPPED);
487 mFragments.noteStateNotSaved();
488 mFragments.execPendingActions();
491 if (!mLoadersStarted) {
492 mLoadersStarted = true;
493 if (mLoaderManager != null) {
494 mLoaderManager.doStart();
495 } else if (!mCheckedForLoaderManager) {
496 mLoaderManager = getLoaderManager(-1, mLoadersStarted, false);
498 mCheckedForLoaderManager = true;
500 // NOTE: HC onStart goes here.
502 mFragments.dispatchStart();
503 if (mAllLoaderManagers != null) {
504 for (int i=mAllLoaderManagers.size()-1; i>=0; i--) {
505 mAllLoaderManagers.valueAt(i).finishRetain();
511 * Dispatch onStop() to all fragments. Ensure all loaders are stopped.
514 protected void onStop() {
518 mHandler.sendEmptyMessage(MSG_REALLY_STOPPED);
520 mFragments.dispatchStop();
523 // ------------------------------------------------------------------------
525 // ------------------------------------------------------------------------
527 void supportInvalidateOptionsMenu() {
528 //v4 if (android.os.Build.VERSION.SDK_INT >= HONEYCOMB) {
529 if (android.support.v2.os.Build.VERSION.SDK_INT >= HONEYCOMB) {
530 // If we are running on HC or greater, we can use the framework
531 // API to invalidate the options menu.
532 //ActivityCompatHoneycomb.invalidateOptionsMenu(this);
536 // Whoops, older platform... we'll use a hack, to manually rebuild
537 // the options menu the next time it is prepared.
538 mOptionsMenuInvalidated = true;
542 * Print the Activity's state into the given stream. This gets invoked if
543 * you run "adb shell dumpsys activity <activity_component_name>".
545 * @param prefix Desired prefix to prepend at each line of output.
546 * @param fd The raw file descriptor that the dump is being sent to.
547 * @param writer The PrintWriter to which you should dump your state. This will be
548 * closed for you after you return.
549 * @param args additional arguments to the dump request.
551 public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) {
552 //v4 if (android.os.Build.VERSION.SDK_INT >= HONEYCOMB) {
553 if (android.support.v2.os.Build.VERSION.SDK_INT >= HONEYCOMB) {
554 // XXX This can only work if we can call the super-class impl. :/
555 //ActivityCompatHoneycomb.dump(this, prefix, fd, writer, args);
557 writer.print(prefix); writer.print("Local FragmentActivity ");
558 writer.print(Integer.toHexString(System.identityHashCode(this)));
559 writer.println(" State:");
560 String innerPrefix = prefix + " ";
561 writer.print(innerPrefix); writer.print("mResumed=");
562 writer.print(mResumed); writer.print(" mStopped=");
563 writer.print(mStopped); writer.print(" mReallyStopped=");
564 writer.println(mReallyStopped);
565 writer.print(innerPrefix); writer.print("mLoadersStarted=");
566 writer.println(mLoadersStarted);
567 if (mLoaderManager != null) {
568 writer.print(prefix); writer.print("Loader Manager ");
569 writer.print(Integer.toHexString(System.identityHashCode(mLoaderManager)));
571 mLoaderManager.dump(prefix + " ", fd, writer, args);
573 mFragments.dump(prefix, fd, writer, args);
576 void doReallyStop(boolean retaining) {
577 if (!mReallyStopped) {
578 mReallyStopped = true;
579 mHandler.removeMessages(MSG_REALLY_STOPPED);
580 onReallyStop(retaining);
585 * Pre-HC, we didn't have a way to determine whether an activity was
586 * being stopped for a config change or not until we saw
587 * onRetainNonConfigurationInstance() called after onStop(). However
588 * we need to know this, to know whether to retain fragments. This will
589 * tell us what we need to know.
591 void onReallyStop(boolean retaining) {
592 if (mLoadersStarted) {
593 mLoadersStarted = false;
594 if (mLoaderManager != null) {
596 mLoaderManager.doStop();
598 mLoaderManager.doRetain();
603 mFragments.dispatchReallyStop(retaining);
606 // ------------------------------------------------------------------------
608 // ------------------------------------------------------------------------
611 * Called when a fragment is attached to the activity.
613 public void onAttachFragment(Fragment fragment) {
617 * Return the FragmentManager for interacting with fragments associated
618 * with this activity.
620 public FragmentManager getSupportFragmentManager() {
625 * Modifies the standard behavior to allow results to be delivered to fragments.
626 * This imposes a restriction that requestCode be <= 0xffff.
629 public void startActivityForResult(Intent intent, int requestCode) {
630 if (requestCode != -1 && (requestCode&0xffff0000) != 0) {
631 throw new IllegalArgumentException("Can only use lower 16 bits for requestCode");
633 super.startActivityForResult(intent, requestCode);
637 * Called by Fragment.startActivityForResult() to implement its behavior.
639 public void startActivityFromFragment(Fragment fragment, Intent intent,
641 if (requestCode == -1) {
642 super.startActivityForResult(intent, -1);
645 if ((requestCode&0xffff0000) != 0) {
646 throw new IllegalArgumentException("Can only use lower 16 bits for requestCode");
648 super.startActivityForResult(intent, ((fragment.mIndex+1)<<16) + (requestCode&0xffff));
651 void invalidateSupportFragmentIndex(int index) {
652 //Log.v(TAG, "invalidateFragmentIndex: index=" + index);
653 if (mAllLoaderManagers != null) {
654 LoaderManagerImpl lm = mAllLoaderManagers.get(index);
658 mAllLoaderManagers.remove(index);
662 // ------------------------------------------------------------------------
664 // ------------------------------------------------------------------------
667 * Return the LoaderManager for this fragment, creating it if needed.
669 public LoaderManager getSupportLoaderManager() {
670 if (mLoaderManager != null) {
671 return mLoaderManager;
673 mCheckedForLoaderManager = true;
674 mLoaderManager = getLoaderManager(-1, mLoadersStarted, true);
675 return mLoaderManager;
678 LoaderManagerImpl getLoaderManager(int index, boolean started, boolean create) {
679 if (mAllLoaderManagers == null) {
680 mAllLoaderManagers = new HCSparseArray<LoaderManagerImpl>();
682 LoaderManagerImpl lm = mAllLoaderManagers.get(index);
685 lm = new LoaderManagerImpl(this, started);
686 mAllLoaderManagers.put(index, lm);
689 lm.updateActivity(this);