/* * Copyright (C) 2006 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 android.app; import com.android.internal.policy.PolicyManager; import android.content.ComponentCallbacks; import android.content.ComponentName; import android.content.ContentResolver; import android.content.Context; import android.content.Intent; import android.content.IIntentSender; import android.content.SharedPreferences; import android.content.pm.ActivityInfo; import android.content.res.Configuration; import android.content.res.Resources; import android.database.Cursor; import android.graphics.Bitmap; import android.graphics.Canvas; import android.graphics.drawable.Drawable; import android.media.AudioManager; import android.net.Uri; import android.os.Bundle; import android.os.Handler; import android.os.IBinder; import android.os.RemoteException; import android.text.Selection; import android.text.SpannableStringBuilder; import android.text.TextUtils; import android.text.method.TextKeyListener; import android.util.AttributeSet; import android.util.Config; import android.util.EventLog; import android.util.Log; import android.util.SparseArray; import android.view.ContextMenu; import android.view.ContextThemeWrapper; import android.view.KeyEvent; import android.view.LayoutInflater; import android.view.Menu; import android.view.MenuInflater; import android.view.MenuItem; import android.view.MotionEvent; import android.view.View; import android.view.ViewGroup; import android.view.ViewManager; import android.view.Window; import android.view.WindowManager; import android.view.ContextMenu.ContextMenuInfo; import android.view.View.OnCreateContextMenuListener; import android.view.ViewGroup.LayoutParams; import android.view.accessibility.AccessibilityEvent; import android.widget.AdapterView; import java.util.ArrayList; import java.util.HashMap; /** * An activity is a single, focused thing that the user can do. Almost all * activities interact with the user, so the Activity class takes care of * creating a window for you in which you can place your UI with * {@link #setContentView}. While activities are often presented to the user * as full-screen windows, they can also be used in other ways: as floating * windows (via a theme with {@link android.R.attr#windowIsFloating} set) * or embedded inside of another activity (using {@link ActivityGroup}). * * There are two methods almost all subclasses of Activity will implement: * * * *

To be of use with {@link android.content.Context#startActivity Context.startActivity()}, all * activity classes must have a corresponding * {@link android.R.styleable#AndroidManifestActivity <activity>} * declaration in their package's AndroidManifest.xml.

* *

The Activity class is an important part of an application's overall lifecycle, * and the way activities are launched and put together is a fundamental * part of the platform's application model. For a detailed perspective on the structure of * Android applications and lifecycles, please read the Dev Guide document on * Application Fundamentals.

* *

Topics covered here: *

    *
  1. Activity Lifecycle *
  2. Configuration Changes *
  3. Starting Activities and Getting Results *
  4. Saving Persistent State *
  5. Permissions *
  6. Process Lifecycle *
* * *

Activity Lifecycle

* *

Activities in the system are managed as an activity stack. * When a new activity is started, it is placed on the top of the stack * and becomes the running activity -- the previous activity always remains * below it in the stack, and will not come to the foreground again until * the new activity exits.

* *

An activity has essentially four states:

* * *

The following diagram shows the important state paths of an Activity. * The square rectangles represent callback methods you can implement to * perform operations when the Activity moves between states. The colored * ovals are major states the Activity can be in.

* *

State diagram for an Android Activity Lifecycle.

* *

There are three key loops you may be interested in monitoring within your * activity: * *

* *

The entire lifecycle of an activity is defined by the following * Activity methods. All of these are hooks that you can override * to do appropriate work when the activity changes state. All * activities will implement {@link android.app.Activity#onCreate} * to do their initial setup; many will also implement * {@link android.app.Activity#onPause} to commit changes to data and * otherwise prepare to stop interacting with the user. You should always * call up to your superclass when implementing these methods.

* *

* 
 * public class Activity extends ApplicationContext {
 *     protected void onCreate(Bundle savedInstanceState);
 *
 *     protected void onStart();
 *     
 *     protected void onRestart();
 *
 *     protected void onResume();
 *
 *     protected void onPause();
 *
 *     protected void onStop();
 *
 *     protected void onDestroy();
 * }
 *
* *

In general the movement through an activity's lifecycle looks like * this:

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Method Description Killable? Next
{@link android.app.Activity#onCreate onCreate()}Called when the activity is first created. * This is where you should do all of your normal static set up: * create views, bind data to lists, etc. This method also * provides you with a Bundle containing the activity's previously * frozen state, if there was one. *

Always followed by onStart().

NoonStart()
    {@link android.app.Activity#onRestart onRestart()}Called after your activity has been stopped, prior to it being * started again. *

Always followed by onStart()

NoonStart()
{@link android.app.Activity#onStart onStart()}Called when the activity is becoming visible to the user. *

Followed by onResume() if the activity comes * to the foreground, or onStop() if it becomes hidden.

NoonResume() or onStop()
    {@link android.app.Activity#onResume onResume()}Called when the activity will start * interacting with the user. At this point your activity is at * the top of the activity stack, with user input going to it. *

Always followed by onPause().

NoonPause()
{@link android.app.Activity#onPause onPause()}Called when the system is about to start resuming a previous * activity. This is typically used to commit unsaved changes to * persistent data, stop animations and other things that may be consuming * CPU, etc. Implementations of this method must be very quick because * the next activity will not be resumed until this method returns. *

Followed by either onResume() if the activity * returns back to the front, or onStop() if it becomes * invisible to the user.

YesonResume() or
* onStop()
{@link android.app.Activity#onStop onStop()}Called when the activity is no longer visible to the user, because * another activity has been resumed and is covering this one. This * may happen either because a new activity is being started, an existing * one is being brought in front of this one, or this one is being * destroyed. *

Followed by either onRestart() if * this activity is coming back to interact with the user, or * onDestroy() if this activity is going away.

YesonRestart() or
* onDestroy()
{@link android.app.Activity#onDestroy onDestroy()}The final call you receive before your * activity is destroyed. This can happen either because the * activity is finishing (someone called {@link Activity#finish} on * it, or because the system is temporarily destroying this * instance of the activity to save space. You can distinguish * between these two scenarios with the {@link * Activity#isFinishing} method.Yesnothing
* *

Note the "Killable" column in the above table -- for those methods that * are marked as being killable, after that method returns the process hosting the * activity may killed by the system at any time without another line * of its code being executed. Because of this, you should use the * {@link #onPause} method to write any persistent data (such as user edits) * to storage. In addition, the method * {@link #onSaveInstanceState(Bundle)} is called before placing the activity * in such a background state, allowing you to save away any dynamic instance * state in your activity into the given Bundle, to be later received in * {@link #onCreate} if the activity needs to be re-created. * See the Process Lifecycle * section for more information on how the lifecycle of a process is tied * to the activities it is hosting. Note that it is important to save * persistent data in {@link #onPause} instead of {@link #onSaveInstanceState} * because the later is not part of the lifecycle callbacks, so will not * be called in every situation as described in its documentation.

* *

For those methods that are not marked as being killable, the activity's * process will not be killed by the system starting from the time the method * is called and continuing after it returns. Thus an activity is in the killable * state, for example, between after onPause() to the start of * onResume().

* * *

Configuration Changes

* *

If the configuration of the device (as defined by the * {@link Configuration Resources.Configuration} class) changes, * then anything displaying a user interface will need to update to match that * configuration. Because Activity is the primary mechanism for interacting * with the user, it includes special support for handling configuration * changes.

* *

Unless you specify otherwise, a configuration change (such as a change * in screen orientation, language, input devices, etc) will cause your * current activity to be destroyed, going through the normal activity * lifecycle process of {@link #onPause}, * {@link #onStop}, and {@link #onDestroy} as appropriate. If the activity * had been in the foreground or visible to the user, once {@link #onDestroy} is * called in that instance then a new instance of the activity will be * created, with whatever savedInstanceState the previous instance had generated * from {@link #onSaveInstanceState}.

* *

This is done because any application resource, * including layout files, can change based on any configuration value. Thus * the only safe way to handle a configuration change is to re-retrieve all * resources, including layouts, drawables, and strings. Because activities * must already know how to save their state and re-create themselves from * that state, this is a convenient way to have an activity restart itself * with a new configuration.

* *

In some special cases, you may want to bypass restarting of your * activity based on one or more types of configuration changes. This is * done with the {@link android.R.attr#configChanges android:configChanges} * attribute in its manifest. For any types of configuration changes you say * that you handle there, you will receive a call to your current activity's * {@link #onConfigurationChanged} method instead of being restarted. If * a configuration change involves any that you do not handle, however, the * activity will still be restarted and {@link #onConfigurationChanged} * will not be called.

* * *

Starting Activities and Getting Results

* *

The {@link android.app.Activity#startActivity} * method is used to start a * new activity, which will be placed at the top of the activity stack. It * takes a single argument, an {@link android.content.Intent Intent}, * which describes the activity * to be executed.

* *

Sometimes you want to get a result back from an activity when it * ends. For example, you may start an activity that lets the user pick * a person in a list of contacts; when it ends, it returns the person * that was selected. To do this, you call the * {@link android.app.Activity#startActivityForResult(Intent, int)} * version with a second integer parameter identifying the call. The result * will come back through your {@link android.app.Activity#onActivityResult} * method.

* *

When an activity exits, it can call * {@link android.app.Activity#setResult(int)} * to return data back to its parent. It must always supply a result code, * which can be the standard results RESULT_CANCELED, RESULT_OK, or any * custom values starting at RESULT_FIRST_USER. In addition, it can optionally * return back an Intent containing any additional data it wants. All of this * information appears back on the * parent's Activity.onActivityResult(), along with the integer * identifier it originally supplied.

* *

If a child activity fails for any reason (such as crashing), the parent * activity will receive a result with the code RESULT_CANCELED.

* * 
 * public class MyActivity extends Activity {
 *     ...
 *
 *     static final int PICK_CONTACT_REQUEST = 0;
 *
 *     protected boolean onKeyDown(int keyCode, KeyEvent event) {
 *         if (keyCode == KeyEvent.KEYCODE_DPAD_CENTER) {
 *             // When the user center presses, let them pick a contact.
 *             startActivityForResult(
 *                 new Intent(Intent.ACTION_PICK,
 *                 new Uri("content://contacts")),
 *                 PICK_CONTACT_REQUEST);
 *            return true;
 *         }
 *         return false;
 *     }
 *
 *     protected void onActivityResult(int requestCode, int resultCode,
 *             Intent data) {
 *         if (requestCode == PICK_CONTACT_REQUEST) {
 *             if (resultCode == RESULT_OK) {
 *                 // A contact was picked.  Here we will just display it
 *                 // to the user.
 *                 startActivity(new Intent(Intent.ACTION_VIEW, data));
 *             }
 *         }
 *     }
 * }
 *
* * *

Saving Persistent State

* *

There are generally two kinds of persistent state than an activity * will deal with: shared document-like data (typically stored in a SQLite * database using a {@linkplain android.content.ContentProvider content provider}) * and internal state such as user preferences.

* *

For content provider data, we suggest that activities use a * "edit in place" user model. That is, any edits a user makes are effectively * made immediately without requiring an additional confirmation step. * Supporting this model is generally a simple matter of following two rules:

* * * *

This model is designed to prevent data loss when a user is navigating * between activities, and allows the system to safely kill an activity (because * system resources are needed somewhere else) at any time after it has been * paused. Note this implies * that the user pressing BACK from your activity does not * mean "cancel" -- it means to leave the activity with its current contents * saved away. Cancelling edits in an activity must be provided through * some other mechanism, such as an explicit "revert" or "undo" option.

* *

See the {@linkplain android.content.ContentProvider content package} for * more information about content providers. These are a key aspect of how * different activities invoke and propagate data between themselves.

* *

The Activity class also provides an API for managing internal persistent state * associated with an activity. This can be used, for example, to remember * the user's preferred initial display in a calendar (day view or week view) * or the user's default home page in a web browser.

* *

Activity persistent state is managed * with the method {@link #getPreferences}, * allowing you to retrieve and * modify a set of name/value pairs associated with the activity. To use * preferences that are shared across multiple application components * (activities, receivers, services, providers), you can use the underlying * {@link Context#getSharedPreferences Context.getSharedPreferences()} method * to retrieve a preferences * object stored under a specific name. * (Note that it is not possible to share settings data across application * packages -- for that you will need a content provider.)

* *

Here is an excerpt from a calendar activity that stores the user's * preferred view mode in its persistent settings:

* * 
 * public class CalendarActivity extends Activity {
 *     ...
 *
 *     static final int DAY_VIEW_MODE = 0;
 *     static final int WEEK_VIEW_MODE = 1;
 *
 *     private SharedPreferences mPrefs;
 *     private int mCurViewMode;
 *
 *     protected void onCreate(Bundle savedInstanceState) {
 *         super.onCreate(savedInstanceState);
 *
 *         SharedPreferences mPrefs = getSharedPreferences();
 *         mCurViewMode = mPrefs.getInt("view_mode" DAY_VIEW_MODE);
 *     }
 *
 *     protected void onPause() {
 *         super.onPause();
 * 
 *         SharedPreferences.Editor ed = mPrefs.edit();
 *         ed.putInt("view_mode", mCurViewMode);
 *         ed.commit();
 *     }
 * }
 *
* * *

Permissions

* *

The ability to start a particular Activity can be enforced when it is * declared in its * manifest's {@link android.R.styleable#AndroidManifestActivity <activity>} * tag. By doing so, other applications will need to declare a corresponding * {@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>} * element in their own manifest to be able to start that activity. * *

See the Security and Permissions * document for more information on permissions and security in general. * * *

Process Lifecycle

* *

The Android system attempts to keep application process around for as * long as possible, but eventually will need to remove old processes when * memory runs low. As described in Activity * Lifecycle, the decision about which process to remove is intimately * tied to the state of the user's interaction with it. In general, there * are four states a process can be in based on the activities running in it, * listed here in order of importance. The system will kill less important * processes (the last ones) before it resorts to killing more important * processes (the first ones). * *

    *

  1. The foreground activity (the activity at the top of the screen * that the user is currently interacting with) is considered the most important. * Its process will only be killed as a last resort, if it uses more memory * than is available on the device. Generally at this point the device has * reached a memory paging state, so this is required in order to keep the user * interface responsive. *

  2. A visible activity (an activity that is visible to the user * but not in the foreground, such as one sitting behind a foreground dialog) * is considered extremely important and will not be killed unless that is * required to keep the foreground activity running. *

  3. A background activity (an activity that is not visible to * the user and has been paused) is no longer critical, so the system may * safely kill its process to reclaim memory for other foreground or * visible processes. If its process needs to be killed, when the user navigates * back to the activity (making it visible on the screen again), its * {@link #onCreate} method will be called with the savedInstanceState it had previously * supplied in {@link #onSaveInstanceState} so that it can restart itself in the same * state as the user last left it. *

  4. An empty process is one hosting no activities or other * application components (such as {@link Service} or * {@link android.content.BroadcastReceiver} classes). These are killed very * quickly by the system as memory becomes low. For this reason, any * background operation you do outside of an activity must be executed in the * context of an activity BroadcastReceiver or Service to ensure that the system * knows it needs to keep your process around. *

* *

Sometimes an Activity may need to do a long-running operation that exists * independently of the activity lifecycle itself. An example may be a camera * application that allows you to upload a picture to a web site. The upload * may take a long time, and the application should allow the user to leave * the application will it is executing. To accomplish this, your Activity * should start a {@link Service} in which the upload takes place. This allows * the system to properly prioritize your process (considering it to be more * important than other non-visible applications) for the duration of the * upload, independent of whether the original activity is paused, stopped, * or finished. */ public class Activity extends ContextThemeWrapper implements LayoutInflater.Factory, Window.Callback, KeyEvent.Callback, OnCreateContextMenuListener, ComponentCallbacks { private static final String TAG = "Activity"; /** Standard activity result: operation canceled. */ public static final int RESULT_CANCELED = 0; /** Standard activity result: operation succeeded. */ public static final int RESULT_OK = -1; /** Start of user-defined activity results. */ public static final int RESULT_FIRST_USER = 1; private static long sInstanceCount = 0; private static final String WINDOW_HIERARCHY_TAG = "android:viewHierarchyState"; private static final String SAVED_DIALOG_IDS_KEY = "android:savedDialogIds"; private static final String SAVED_DIALOGS_TAG = "android:savedDialogs"; private static final String SAVED_DIALOG_KEY_PREFIX = "android:dialog_"; private SparseArray

mManagedDialogs; // set by the thread after the constructor and before onCreate(Bundle savedInstanceState) is called. private Instrumentation mInstrumentation; private IBinder mToken; private int mIdent; /*package*/ String mEmbeddedID; private Application mApplication; /*package*/ Intent mIntent; private ComponentName mComponent; /*package*/ ActivityInfo mActivityInfo; /*package*/ ActivityThread mMainThread; /*package*/ Object mLastNonConfigurationInstance; /*package*/ HashMap mLastNonConfigurationChildInstances; Activity mParent; boolean mCalled; private boolean mResumed; private boolean mStopped; boolean mFinished; boolean mStartedActivity; /*package*/ int mConfigChangeFlags; /*package*/ Configuration mCurrentConfig; private SearchManager mSearchManager; private Window mWindow; private WindowManager mWindowManager; /*package*/ View mDecor = null; /*package*/ boolean mWindowAdded = false; /*package*/ boolean mVisibleFromServer = false; /*package*/ boolean mVisibleFromClient = true; private CharSequence mTitle; private int mTitleColor = 0; private static final class ManagedCursor { ManagedCursor(Cursor cursor) { mCursor = cursor; mReleased = false; mUpdated = false; } private final Cursor mCursor; private boolean mReleased; private boolean mUpdated; } private final ArrayList mManagedCursors = new ArrayList(); // protected by synchronized (this) int mResultCode = RESULT_CANCELED; Intent mResultData = null; private boolean mTitleReady = false; private int mDefaultKeyMode = DEFAULT_KEYS_DISABLE; private SpannableStringBuilder mDefaultKeySsb = null; protected static final int[] FOCUSED_STATE_SET = {com.android.internal.R.attr.state_focused}; private Thread mUiThread; private final Handler mHandler = new Handler(); public Activity() { ++sInstanceCount; } @Override protected void finalize() throws Throwable { super.finalize(); --sInstanceCount; } public static long getInstanceCount() { return sInstanceCount; } /** Return the intent that started this activity. */ public Intent getIntent() { return mIntent; } /** * Change the intent returned by {@link #getIntent}. This holds a * reference to the given intent; it does not copy it. Often used in * conjunction with {@link #onNewIntent}. * * @param newIntent The new Intent object to return from getIntent * * @see #getIntent * @see #onNewIntent */ public void setIntent(Intent newIntent) { mIntent = newIntent; } /** Return the application that owns this activity. */ public final Application getApplication() { return mApplication; } /** Is this activity embedded inside of another activity? */ public final boolean isChild() { return mParent != null; } /** Return the parent activity if this view is an embedded child. */ public final Activity getParent() { return mParent; } /** Retrieve the window manager for showing custom windows. */ public WindowManager getWindowManager() { return mWindowManager; } /** * Retrieve the current {@link android.view.Window} for the activity. * This can be used to directly access parts of the Window API that * are not available through Activity/Screen. * * @return Window The current window, or null if the activity is not * visual. */ public Window getWindow() { return mWindow; } /** * Calls {@link android.view.Window#getCurrentFocus} on the * Window of this Activity to return the currently focused view. * * @return View The current View with focus or null. * * @see #getWindow * @see android.view.Window#getCurrentFocus */ public View getCurrentFocus() { return mWindow != null ? mWindow.getCurrentFocus() : null; } @Override public int getWallpaperDesiredMinimumWidth() { int width = super.getWallpaperDesiredMinimumWidth(); return width <= 0 ? getWindowManager().getDefaultDisplay().getWidth() : width; } @Override public int getWallpaperDesiredMinimumHeight() { int height = super.getWallpaperDesiredMinimumHeight(); return height <= 0 ? getWindowManager().getDefaultDisplay().getHeight() : height; } /** * Called when the activity is starting. This is where most initialization * should go: calling {@link #setContentView(int)} to inflate the * activity's UI, using {@link #findViewById} to programmatically interact * with widgets in the UI, calling * {@link #managedQuery(android.net.Uri , String[], String, String[], String)} to retrieve * cursors for data being displayed, etc. * *

You can call {@link #finish} from within this function, in * which case onDestroy() will be immediately called without any of the rest * of the activity lifecycle ({@link #onStart}, {@link #onResume}, * {@link #onPause}, etc) executing. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @param savedInstanceState If the activity is being re-initialized after * previously being shut down then this Bundle contains the data it most * recently supplied in {@link #onSaveInstanceState}. Note: Otherwise it is null. * * @see #onStart * @see #onSaveInstanceState * @see #onRestoreInstanceState * @see #onPostCreate */ protected void onCreate(Bundle savedInstanceState) { mVisibleFromClient = mWindow.getWindowStyle().getBoolean( com.android.internal.R.styleable.Window_windowNoDisplay, true); mCalled = true; } /** * The hook for {@link ActivityThread} to restore the state of this activity. * * Calls {@link #onSaveInstanceState(android.os.Bundle)} and * {@link #restoreManagedDialogs(android.os.Bundle)}. * * @param savedInstanceState contains the saved state */ final void performRestoreInstanceState(Bundle savedInstanceState) { onRestoreInstanceState(savedInstanceState); restoreManagedDialogs(savedInstanceState); } /** * This method is called after {@link #onStart} when the activity is * being re-initialized from a previously saved state, given here in * state. Most implementations will simply use {@link #onCreate} * to restore their state, but it is sometimes convenient to do it here * after all of the initialization has been done or to allow subclasses to * decide whether to use your default implementation. The default * implementation of this method performs a restore of any view state that * had previously been frozen by {@link #onSaveInstanceState}. * *

This method is called between {@link #onStart} and * {@link #onPostCreate}. * * @param savedInstanceState the data most recently supplied in {@link #onSaveInstanceState}. * * @see #onCreate * @see #onPostCreate * @see #onResume * @see #onSaveInstanceState */ protected void onRestoreInstanceState(Bundle savedInstanceState) { if (mWindow != null) { Bundle windowState = savedInstanceState.getBundle(WINDOW_HIERARCHY_TAG); if (windowState != null) { mWindow.restoreHierarchyState(windowState); } } } /** * Restore the state of any saved managed dialogs. * * @param savedInstanceState The bundle to restore from. */ private void restoreManagedDialogs(Bundle savedInstanceState) { final Bundle b = savedInstanceState.getBundle(SAVED_DIALOGS_TAG); if (b == null) { return; } final int[] ids = b.getIntArray(SAVED_DIALOG_IDS_KEY); final int numDialogs = ids.length; mManagedDialogs = new SparseArray

(numDialogs); for (int i = 0; i < numDialogs; i++) { final Integer dialogId = ids[i]; Bundle dialogState = b.getBundle(savedDialogKeyFor(dialogId)); if (dialogState != null) { // Calling onRestoreInstanceState() below will invoke dispatchOnCreate // so tell createDialog() not to do it, otherwise we get an exception final Dialog dialog = createDialog(dialogId, dialogState); mManagedDialogs.put(dialogId, dialog); onPrepareDialog(dialogId, dialog); dialog.onRestoreInstanceState(dialogState); } } } private Dialog createDialog(Integer dialogId, Bundle state) { final Dialog dialog = onCreateDialog(dialogId); if (dialog == null) { throw new IllegalArgumentException("Activity#onCreateDialog did " + "not create a dialog for id " + dialogId); } dialog.dispatchOnCreate(state); return dialog; } private String savedDialogKeyFor(int key) { return SAVED_DIALOG_KEY_PREFIX + key; } /** * Called when activity start-up is complete (after {@link #onStart} * and {@link #onRestoreInstanceState} have been called). Applications will * generally not implement this method; it is intended for system * classes to do final initialization after application code has run. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @param savedInstanceState If the activity is being re-initialized after * previously being shut down then this Bundle contains the data it most * recently supplied in {@link #onSaveInstanceState}. Note: Otherwise it is null. * @see #onCreate */ protected void onPostCreate(Bundle savedInstanceState) { if (!isChild()) { mTitleReady = true; onTitleChanged(getTitle(), getTitleColor()); } mCalled = true; } /** * Called after {@link #onCreate} — or after {@link #onRestart} when * the activity had been stopped, but is now again being displayed to the * user. It will be followed by {@link #onResume}. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onCreate * @see #onStop * @see #onResume */ protected void onStart() { mCalled = true; } /** * Called after {@link #onStop} when the current activity is being * re-displayed to the user (the user has navigated back to it). It will * be followed by {@link #onStart} and then {@link #onResume}. * *

For activities that are using raw {@link Cursor} objects (instead of * creating them through * {@link #managedQuery(android.net.Uri , String[], String, String[], String)}, * this is usually the place * where the cursor should be requeried (because you had deactivated it in * {@link #onStop}. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onStop * @see #onStart * @see #onResume */ protected void onRestart() { mCalled = true; } /** * Called after {@link #onRestoreInstanceState}, {@link #onRestart}, or * {@link #onPause}, for your activity to start interacting with the user. * This is a good place to begin animations, open exclusive-access devices * (such as the camera), etc. * *

Keep in mind that onResume is not the best indicator that your activity * is visible to the user; a system window such as the keyguard may be in * front. Use {@link #onWindowFocusChanged} to know for certain that your * activity is visible to the user (for example, to resume a game). * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onRestoreInstanceState * @see #onRestart * @see #onPostResume * @see #onPause */ protected void onResume() { mCalled = true; } /** * Called when activity resume is complete (after {@link #onResume} has * been called). Applications will generally not implement this method; * it is intended for system classes to do final setup after application * resume code has run. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onResume */ protected void onPostResume() { final Window win = getWindow(); if (win != null) win.makeActive(); mCalled = true; } /** * This is called for activities that set launchMode to "singleTop" in * their package, or if a client used the {@link Intent#FLAG_ACTIVITY_SINGLE_TOP} * flag when calling {@link #startActivity}. In either case, when the * activity is re-launched while at the top of the activity stack instead * of a new instance of the activity being started, onNewIntent() will be * called on the existing instance with the Intent that was used to * re-launch it. * *

An activity will always be paused before receiving a new intent, so * you can count on {@link #onResume} being called after this method. * *

Note that {@link #getIntent} still returns the original Intent. You * can use {@link #setIntent} to update it to this new Intent. * * @param intent The new intent that was started for the activity. * * @see #getIntent * @see #setIntent * @see #onResume */ protected void onNewIntent(Intent intent) { } /** * The hook for {@link ActivityThread} to save the state of this activity. * * Calls {@link #onSaveInstanceState(android.os.Bundle)} * and {@link #saveManagedDialogs(android.os.Bundle)}. * * @param outState The bundle to save the state to. */ final void performSaveInstanceState(Bundle outState) { onSaveInstanceState(outState); saveManagedDialogs(outState); } /** * Called to retrieve per-instance state from an activity before being killed * so that the state can be restored in {@link #onCreate} or * {@link #onRestoreInstanceState} (the {@link Bundle} populated by this method * will be passed to both). * *

This method is called before an activity may be killed so that when it * comes back some time in the future it can restore its state. For example, * if activity B is launched in front of activity A, and at some point activity * A is killed to reclaim resources, activity A will have a chance to save the * current state of its user interface via this method so that when the user * returns to activity A, the state of the user interface can be restored * via {@link #onCreate} or {@link #onRestoreInstanceState}. * *

Do not confuse this method with activity lifecycle callbacks such as * {@link #onPause}, which is always called when an activity is being placed * in the background or on its way to destruction, or {@link #onStop} which * is called before destruction. One example of when {@link #onPause} and * {@link #onStop} is called and not this method is when a user navigates back * from activity B to activity A: there is no need to call {@link #onSaveInstanceState} * on B because that particular instance will never be restored, so the * system avoids calling it. An example when {@link #onPause} is called and * not {@link #onSaveInstanceState} is when activity B is launched in front of activity A: * the system may avoid calling {@link #onSaveInstanceState} on activity A if it isn't * killed during the lifetime of B since the state of the user interface of * A will stay intact. * *

The default implementation takes care of most of the UI per-instance * state for you by calling {@link android.view.View#onSaveInstanceState()} on each * view in the hierarchy that has an id, and by saving the id of the currently * focused view (all of which is restored by the default implementation of * {@link #onRestoreInstanceState}). If you override this method to save additional * information not captured by each individual view, you will likely want to * call through to the default implementation, otherwise be prepared to save * all of the state of each view yourself. * *

If called, this method will occur before {@link #onStop}. There are * no guarantees about whether it will occur before or after {@link #onPause}. * * @param outState Bundle in which to place your saved state. * * @see #onCreate * @see #onRestoreInstanceState * @see #onPause */ protected void onSaveInstanceState(Bundle outState) { outState.putBundle(WINDOW_HIERARCHY_TAG, mWindow.saveHierarchyState()); } /** * Save the state of any managed dialogs. * * @param outState place to store the saved state. */ private void saveManagedDialogs(Bundle outState) { if (mManagedDialogs == null) { return; } final int numDialogs = mManagedDialogs.size(); if (numDialogs == 0) { return; } Bundle dialogState = new Bundle(); int[] ids = new int[mManagedDialogs.size()]; // save each dialog's bundle, gather the ids for (int i = 0; i < numDialogs; i++) { final int key = mManagedDialogs.keyAt(i); ids[i] = key; final Dialog dialog = mManagedDialogs.valueAt(i); dialogState.putBundle(savedDialogKeyFor(key), dialog.onSaveInstanceState()); } dialogState.putIntArray(SAVED_DIALOG_IDS_KEY, ids); outState.putBundle(SAVED_DIALOGS_TAG, dialogState); } /** * Called as part of the activity lifecycle when an activity is going into * the background, but has not (yet) been killed. The counterpart to * {@link #onResume}. * *

When activity B is launched in front of activity A, this callback will * be invoked on A. B will not be created until A's {@link #onPause} returns, * so be sure to not do anything lengthy here. * *

This callback is mostly used for saving any persistent state the * activity is editing, to present a "edit in place" model to the user and * making sure nothing is lost if there are not enough resources to start * the new activity without first killing this one. This is also a good * place to do things like stop animations and other things that consume a * noticeable mount of CPU in order to make the switch to the next activity * as fast as possible, or to close resources that are exclusive access * such as the camera. * *

In situations where the system needs more memory it may kill paused * processes to reclaim resources. Because of this, you should be sure * that all of your state is saved by the time you return from * this function. In general {@link #onSaveInstanceState} is used to save * per-instance state in the activity and this method is used to store * global persistent data (in content providers, files, etc.) * *

After receiving this call you will usually receive a following call * to {@link #onStop} (after the next activity has been resumed and * displayed), however in some cases there will be a direct call back to * {@link #onResume} without going through the stopped state. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onResume * @see #onSaveInstanceState * @see #onStop */ protected void onPause() { mCalled = true; } /** * Called as part of the activity lifecycle when an activity is about to go * into the background as the result of user choice. For example, when the * user presses the Home key, {@link #onUserLeaveHint} will be called, but * when an incoming phone call causes the in-call Activity to be automatically * brought to the foreground, {@link #onUserLeaveHint} will not be called on * the activity being interrupted. In cases when it is invoked, this method * is called right before the activity's {@link #onPause} callback. * *

This callback and {@link #onUserInteraction} are intended to help * activities manage status bar notifications intelligently; specifically, * for helping activities determine the proper time to cancel a notfication. * * @see #onUserInteraction() */ protected void onUserLeaveHint() { } /** * Generate a new thumbnail for this activity. This method is called before * pausing the activity, and should draw into outBitmap the * imagery for the desired thumbnail in the dimensions of that bitmap. It * can use the given canvas, which is configured to draw into the * bitmap, for rendering if desired. * *

The default implementation renders the Screen's current view * hierarchy into the canvas to generate a thumbnail. * *

If you return false, the bitmap will be filled with a default * thumbnail. * * @param outBitmap The bitmap to contain the thumbnail. * @param canvas Can be used to render into the bitmap. * * @return Return true if you have drawn into the bitmap; otherwise after * you return it will be filled with a default thumbnail. * * @see #onCreateDescription * @see #onSaveInstanceState * @see #onPause */ public boolean onCreateThumbnail(Bitmap outBitmap, Canvas canvas) { final View view = mDecor; if (view == null) { return false; } final int vw = view.getWidth(); final int vh = view.getHeight(); final int dw = outBitmap.getWidth(); final int dh = outBitmap.getHeight(); canvas.save(); canvas.scale(((float)dw)/vw, ((float)dh)/vh); view.draw(canvas); canvas.restore(); return true; } /** * Generate a new description for this activity. This method is called * before pausing the activity and can, if desired, return some textual * description of its current state to be displayed to the user. * *

The default implementation returns null, which will cause you to * inherit the description from the previous activity. If all activities * return null, generally the label of the top activity will be used as the * description. * * @return A description of what the user is doing. It should be short and * sweet (only a few words). * * @see #onCreateThumbnail * @see #onSaveInstanceState * @see #onPause */ public CharSequence onCreateDescription() { return null; } /** * Called when you are no longer visible to the user. You will next * receive either {@link #onRestart}, {@link #onDestroy}, or nothing, * depending on later user activity. * *

Note that this method may never be called, in low memory situations * where the system does not have enough memory to keep your activity's * process running after its {@link #onPause} method is called. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onRestart * @see #onResume * @see #onSaveInstanceState * @see #onDestroy */ protected void onStop() { mCalled = true; } /** * Perform any final cleanup before an activity is destroyed. This can * happen either because the activity is finishing (someone called * {@link #finish} on it, or because the system is temporarily destroying * this instance of the activity to save space. You can distinguish * between these two scenarios with the {@link #isFinishing} method. * *

Note: do not count on this method being called as a place for * saving data! For example, if an activity is editing data in a content * provider, those edits should be committed in either {@link #onPause} or * {@link #onSaveInstanceState}, not here. This method is usually implemented to * free resources like threads that are associated with an activity, so * that a destroyed activity does not leave such things around while the * rest of its application is still running. There are situations where * the system will simply kill the activity's hosting process without * calling this method (or any others) in it, so it should not be used to * do things that are intended to remain around after the process goes * away. * *

Derived classes must call through to the super class's * implementation of this method. If they do not, an exception will be * thrown.

* * @see #onPause * @see #onStop * @see #finish * @see #isFinishing */ protected void onDestroy() { mCalled = true; // dismiss any dialogs we are managing. if (mManagedDialogs != null) { final int numDialogs = mManagedDialogs.size(); for (int i = 0; i < numDialogs; i++) { final Dialog dialog = mManagedDialogs.valueAt(i); if (dialog.isShowing()) { dialog.dismiss(); } } } // close any cursors we are managing. int numCursors = mManagedCursors.size(); for (int i = 0; i < numCursors; i++) { ManagedCursor c = mManagedCursors.get(i); if (c != null) { c.mCursor.close(); } } } /** * Called by the system when the device configuration changes while your * activity is running. Note that this will only be called if * you have selected configurations you would like to handle with the * {@link android.R.attr#configChanges} attribute in your manifest. If * any configuration change occurs that is not selected to be reported * by that attribute, then instead of reporting it the system will stop * and restart the activity (to have it launched with the new * configuration). * *

At the time that this function has been called, your Resources * object will have been updated to return resource values matching the * new configuration. * * @param newConfig The new device configuration. */ public void onConfigurationChanged(Configuration newConfig) { mCalled = true; if (mWindow != null) { // Pass the configuration changed event to the window mWindow.onConfigurationChanged(newConfig); } } /** * If this activity is being destroyed because it can not handle a * configuration parameter being changed (and thus its * {@link #onConfigurationChanged(Configuration)} method is * not being called), then you can use this method to discover * the set of changes that have occurred while in the process of being * destroyed. Note that there is no guarantee that these will be * accurate (other changes could have happened at any time), so you should * only use this as an optimization hint. * * @return Returns a bit field of the configuration parameters that are * changing, as defined by the {@link android.content.res.Configuration} * class. */ public int getChangingConfigurations() { return mConfigChangeFlags; } /** * Retrieve the non-configuration instance data that was previously * returned by {@link #onRetainNonConfigurationInstance()}. This will * be available from the initial {@link #onCreate} and * {@link #onStart} calls to the new instance, allowing you to extract * any useful dynamic state from the previous instance. * *

Note that the data you retrieve here should only be used * as an optimization for handling configuration changes. You should always * be able to handle getting a null pointer back, and an activity must * still be able to restore itself to its previous state (through the * normal {@link #onSaveInstanceState(Bundle)} mechanism) even if this * function returns null. * * @return Returns the object previously returned by * {@link #onRetainNonConfigurationInstance()}. */ public Object getLastNonConfigurationInstance() { return mLastNonConfigurationInstance; } /** * Called by the system, as part of destroying an * activity due to a configuration change, when it is known that a new * instance will immediately be created for the new configuration. You * can return any object you like here, including the activity instance * itself, which can later be retrieved by calling * {@link #getLastNonConfigurationInstance()} in the new activity * instance. * *

This function is called purely as an optimization, and you must * not rely on it being called. When it is called, a number of guarantees * will be made to help optimize configuration switching: *

    *
  • The function will be called between {@link #onStop} and * {@link #onDestroy}. *
  • A new instance of the activity will always be immediately * created after this one's {@link #onDestroy()} is called. *
  • The object you return here will always be available from * the {@link #getLastNonConfigurationInstance()} method of the following * activity instance as described there. *
* *

These guarantees are designed so that an activity can use this API * to propagate extensive state from the old to new activity instance, from * loaded bitmaps, to network connections, to evenly actively running * threads. Note that you should not propagate any data that * may change based on the configuration, including any data loaded from * resources such as strings, layouts, or drawables. * * @return Return any Object holding the desired state to propagate to the * next activity instance. */ public Object onRetainNonConfigurationInstance() { return null; } /** * Retrieve the non-configuration instance data that was previously * returned by {@link #onRetainNonConfigurationChildInstances()}. This will * be available from the initial {@link #onCreate} and * {@link #onStart} calls to the new instance, allowing you to extract * any useful dynamic state from the previous instance. * *

Note that the data you retrieve here should only be used * as an optimization for handling configuration changes. You should always * be able to handle getting a null pointer back, and an activity must * still be able to restore itself to its previous state (through the * normal {@link #onSaveInstanceState(Bundle)} mechanism) even if this * function returns null. * * @return Returns the object previously returned by * {@link #onRetainNonConfigurationChildInstances()} */ HashMap getLastNonConfigurationChildInstances() { return mLastNonConfigurationChildInstances; } /** * This method is similar to {@link #onRetainNonConfigurationInstance()} except that * it should return either a mapping from child activity id strings to arbitrary objects, * or null. This method is intended to be used by Activity framework subclasses that control a * set of child activities, such as ActivityGroup. The same guarantees and restrictions apply * as for {@link #onRetainNonConfigurationInstance()}. The default implementation returns null. */ HashMap onRetainNonConfigurationChildInstances() { return null; } public void onLowMemory() { mCalled = true; } /** * Wrapper around * {@link ContentResolver#query(android.net.Uri , String[], String, String[], String)} * that gives the resulting {@link Cursor} to call * {@link #startManagingCursor} so that the activity will manage its * lifecycle for you. * * @param uri The URI of the content provider to query. * @param projection List of columns to return. * @param selection SQL WHERE clause. * @param sortOrder SQL ORDER BY clause. * * @return The Cursor that was returned by query(). * * @see ContentResolver#query(android.net.Uri , String[], String, String[], String) * @see #startManagingCursor * @hide */ public final Cursor managedQuery(Uri uri, String[] projection, String selection, String sortOrder) { Cursor c = getContentResolver().query(uri, projection, selection, null, sortOrder); if (c != null) { startManagingCursor(c); } return c; } /** * Wrapper around * {@link ContentResolver#query(android.net.Uri , String[], String, String[], String)} * that gives the resulting {@link Cursor} to call * {@link #startManagingCursor} so that the activity will manage its * lifecycle for you. * * @param uri The URI of the content provider to query. * @param projection List of columns to return. * @param selection SQL WHERE clause. * @param selectionArgs The arguments to selection, if any ?s are pesent * @param sortOrder SQL ORDER BY clause. * * @return The Cursor that was returned by query(). * * @see ContentResolver#query(android.net.Uri , String[], String, String[], String) * @see #startManagingCursor */ public final Cursor managedQuery(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) { Cursor c = getContentResolver().query(uri, projection, selection, selectionArgs, sortOrder); if (c != null) { startManagingCursor(c); } return c; } /** * Wrapper around {@link Cursor#commitUpdates()} that takes care of noting * that the Cursor needs to be requeried. You can call this method in * {@link #onPause} or {@link #onStop} to have the system call * {@link Cursor#requery} for you if the activity is later resumed. This * allows you to avoid determing when to do the requery yourself (which is * required for the Cursor to see any data changes that were committed with * it). * * @param c The Cursor whose changes are to be committed. * * @see #managedQuery(android.net.Uri , String[], String, String[], String) * @see #startManagingCursor * @see Cursor#commitUpdates() * @see Cursor#requery * @hide */ @Deprecated public void managedCommitUpdates(Cursor c) { synchronized (mManagedCursors) { final int N = mManagedCursors.size(); for (int i=0; iYou should avoid using this method, it has severe negative * consequences on how well the system can manage its resources. A better * approach is to implement an application service that you control with * {@link Context#startService} and {@link Context#stopService}. * * @param isPersistent Control whether the current activity must be * persistent, true if so, false for the normal * behavior. */ public void setPersistent(boolean isPersistent) { if (mParent == null) { try { ActivityManagerNative.getDefault() .setPersistent(mToken, isPersistent); } catch (RemoteException e) { // Empty } } else { throw new RuntimeException("setPersistent() not yet supported for embedded activities"); } } /** * Finds a view that was identified by the id attribute from the XML that * was processed in {@link #onCreate}. * * @return The view if found or null otherwise. */ public View findViewById(int id) { return getWindow().findViewById(id); } /** * Set the activity content from a layout resource. The resource will be * inflated, adding all top-level views to the activity. * * @param layoutResID Resource ID to be inflated. */ public void setContentView(int layoutResID) { getWindow().setContentView(layoutResID); } /** * Set the activity content to an explicit view. This view is placed * directly into the activity's view hierarchy. It can itself be a complex * view hierarhcy. * * @param view The desired content to display. */ public void setContentView(View view) { getWindow().setContentView(view); } /** * Set the activity content to an explicit view. This view is placed * directly into the activity's view hierarchy. It can itself be a complex * view hierarhcy. * * @param view The desired content to display. * @param params Layout parameters for the view. */ public void setContentView(View view, ViewGroup.LayoutParams params) { getWindow().setContentView(view, params); } /** * Add an additional content view to the activity. Added after any existing * ones in the activity -- existing views are NOT removed. * * @param view The desired content to display. * @param params Layout parameters for the view. */ public void addContentView(View view, ViewGroup.LayoutParams params) { getWindow().addContentView(view, params); } /** * Use with {@link #setDefaultKeyMode} to turn off default handling of * keys. * * @see #setDefaultKeyMode */ static public final int DEFAULT_KEYS_DISABLE = 0; /** * Use with {@link #setDefaultKeyMode} to launch the dialer during default * key handling. * * @see #setDefaultKeyMode */ static public final int DEFAULT_KEYS_DIALER = 1; /** * Use with {@link #setDefaultKeyMode} to execute a menu shortcut in * default key handling. * *

That is, the user does not need to hold down the menu key to execute menu shortcuts. * * @see #setDefaultKeyMode */ static public final int DEFAULT_KEYS_SHORTCUT = 2; /** * Use with {@link #setDefaultKeyMode} to specify that unhandled keystrokes * will start an application-defined search. (If the application or activity does not * actually define a search, the the keys will be ignored.) * *

See {@link android.app.SearchManager android.app.SearchManager} for more details. * * @see #setDefaultKeyMode */ static public final int DEFAULT_KEYS_SEARCH_LOCAL = 3; /** * Use with {@link #setDefaultKeyMode} to specify that unhandled keystrokes * will start a global search (typically web search, but some platforms may define alternate * methods for global search) * *

See {@link android.app.SearchManager android.app.SearchManager} for more details. * * @see #setDefaultKeyMode */ static public final int DEFAULT_KEYS_SEARCH_GLOBAL = 4; /** * Select the default key handling for this activity. This controls what * will happen to key events that are not otherwise handled. The default * mode ({@link #DEFAULT_KEYS_DISABLE}) will simply drop them on the * floor. Other modes allow you to launch the dialer * ({@link #DEFAULT_KEYS_DIALER}), execute a shortcut in your options * menu without requiring the menu key be held down * ({@link #DEFAULT_KEYS_SHORTCUT}), or launch a search ({@link #DEFAULT_KEYS_SEARCH_LOCAL} * and {@link #DEFAULT_KEYS_SEARCH_GLOBAL}). * *

Note that the mode selected here does not impact the default * handling of system keys, such as the "back" and "menu" keys, and your * activity and its views always get a first chance to receive and handle * all application keys. * * @param mode The desired default key mode constant. * * @see #DEFAULT_KEYS_DISABLE * @see #DEFAULT_KEYS_DIALER * @see #DEFAULT_KEYS_SHORTCUT * @see #DEFAULT_KEYS_SEARCH_LOCAL * @see #DEFAULT_KEYS_SEARCH_GLOBAL * @see #onKeyDown */ public final void setDefaultKeyMode(int mode) { mDefaultKeyMode = mode; // Some modes use a SpannableStringBuilder to track & dispatch input events // This list must remain in sync with the switch in onKeyDown() switch (mode) { case DEFAULT_KEYS_DISABLE: case DEFAULT_KEYS_SHORTCUT: mDefaultKeySsb = null; // not used in these modes break; case DEFAULT_KEYS_DIALER: case DEFAULT_KEYS_SEARCH_LOCAL: case DEFAULT_KEYS_SEARCH_GLOBAL: mDefaultKeySsb = new SpannableStringBuilder(); Selection.setSelection(mDefaultKeySsb,0); break; default: throw new IllegalArgumentException(); } } /** * Called when a key was pressed down and not handled by any of the views * inside of the activity. So, for example, key presses while the cursor * is inside a TextView will not trigger the event (unless it is a navigation * to another object) because TextView handles its own key presses. * *

If the focused view didn't want this event, this method is called. * *

The default implementation handles KEYCODE_BACK to stop the activity * and go back, and other default key handling if configured with {@link #setDefaultKeyMode}. * * @return Return true to prevent this event from being propagated * further, or false to indicate that you have not handled * this event and it should continue to be propagated. * @see #onKeyUp * @see android.view.KeyEvent */ public boolean onKeyDown(int keyCode, KeyEvent event) { if (keyCode == KeyEvent.KEYCODE_BACK && event.getRepeatCount() == 0) { finish(); return true; } if (mDefaultKeyMode == DEFAULT_KEYS_DISABLE) { return false; } else if (mDefaultKeyMode == DEFAULT_KEYS_SHORTCUT) { return getWindow().performPanelShortcut(Window.FEATURE_OPTIONS_PANEL, keyCode, event, Menu.FLAG_ALWAYS_PERFORM_CLOSE); } else { // Common code for DEFAULT_KEYS_DIALER & DEFAULT_KEYS_SEARCH_* boolean clearSpannable = false; boolean handled; if ((event.getRepeatCount() != 0) || event.isSystem()) { clearSpannable = true; handled = false; } else { handled = TextKeyListener.getInstance().onKeyDown(null, mDefaultKeySsb, keyCode, event); if (handled && mDefaultKeySsb.length() > 0) { // something useable has been typed - dispatch it now. final String str = mDefaultKeySsb.toString(); clearSpannable = true; switch (mDefaultKeyMode) { case DEFAULT_KEYS_DIALER: Intent intent = new Intent(Intent.ACTION_DIAL, Uri.parse("tel:" + str)); intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); startActivity(intent); break; case DEFAULT_KEYS_SEARCH_LOCAL: startSearch(str, false, null, false); break; case DEFAULT_KEYS_SEARCH_GLOBAL: startSearch(str, false, null, true); break; } } } if (clearSpannable) { mDefaultKeySsb.clear(); mDefaultKeySsb.clearSpans(); Selection.setSelection(mDefaultKeySsb,0); } return handled; } } /** * Called when a key was released and not handled by any of the views * inside of the activity. So, for example, key presses while the cursor * is inside a TextView will not trigger the event (unless it is a navigation * to another object) because TextView handles its own key presses. * * @return Return true to prevent this event from being propagated * further, or false to indicate that you have not handled * this event and it should continue to be propagated. * @see #onKeyDown * @see KeyEvent */ public boolean onKeyUp(int keyCode, KeyEvent event) { return false; } /** * Default implementation of {@link KeyEvent.Callback#onKeyMultiple(int, int, KeyEvent) * KeyEvent.Callback.onKeyMultiple()}: always returns false (doesn't handle * the event). */ public boolean onKeyMultiple(int keyCode, int repeatCount, KeyEvent event) { return false; } /** * Called when a touch screen event was not handled by any of the views * under it. This is most useful to process touch events that happen * outside of your window bounds, where there is no view to receive it. * * @param event The touch screen event being processed. * * @return Return true if you have consumed the event, false if you haven't. * The default implementation always returns false. */ public boolean onTouchEvent(MotionEvent event) { return false; } /** * Called when the trackball was moved and not handled by any of the * views inside of the activity. So, for example, if the trackball moves * while focus is on a button, you will receive a call here because * buttons do not normally do anything with trackball events. The call * here happens before trackball movements are converted to * DPAD key events, which then get sent back to the view hierarchy, and * will be processed at the point for things like focus navigation. * * @param event The trackball event being processed. * * @return Return true if you have consumed the event, false if you haven't. * The default implementation always returns false. */ public boolean onTrackballEvent(MotionEvent event) { return false; } /** * Called whenever a key, touch, or trackball event is dispatched to the * activity. Implement this method if you wish to know that the user has * interacted with the device in some way while your activity is running. * This callback and {@link #onUserLeaveHint} are intended to help * activities manage status bar notifications intelligently; specifically, * for helping activities determine the proper time to cancel a notfication. * *

All calls to your activity's {@link #onUserLeaveHint} callback will * be accompanied by calls to {@link #onUserInteraction}. This * ensures that your activity will be told of relevant user activity such * as pulling down the notification pane and touching an item there. * *

Note that this callback will be invoked for the touch down action * that begins a touch gesture, but may not be invoked for the touch-moved * and touch-up actions that follow. * * @see #onUserLeaveHint() */ public void onUserInteraction() { } public void onWindowAttributesChanged(WindowManager.LayoutParams params) { // Update window manager if: we have a view, that view is // attached to its parent (which will be a RootView), and // this activity is not embedded. if (mParent == null) { View decor = mDecor; if (decor != null && decor.getParent() != null) { getWindowManager().updateViewLayout(decor, params); } } } public void onContentChanged() { } /** * Called when the current {@link Window} of the activity gains or loses * focus. This is the best indicator of whether this activity is visible * to the user. * *

Note that this provides information what global focus state, which * is managed independently of activity lifecycles. As such, while focus * changes will generally have some relation to lifecycle changes (an * activity that is stopped will not generally get window focus), you * should not rely on any particular order between the callbacks here and * those in the other lifecycle methods such as {@link #onResume}. * *

As a general rule, however, a resumed activity will have window * focus... unless it has displayed other dialogs or popups that take * input focus, in which case the activity itself will not have focus * when the other windows have it. Likewise, the system may display * system-level windows (such as the status bar notification panel or * a system alert) which will temporarily take window input focus without * pausing the foreground activity. * * @param hasFocus Whether the window of this activity has focus. * * @see #hasWindowFocus() * @see #onResume */ public void onWindowFocusChanged(boolean hasFocus) { } /** * Returns true if this activity's main window currently has window focus. * Note that this is not the same as the view itself having focus. * * @return True if this activity's main window currently has window focus. * * @see #onWindowAttributesChanged(android.view.WindowManager.LayoutParams) */ public boolean hasWindowFocus() { Window w = getWindow(); if (w != null) { View d = w.getDecorView(); if (d != null) { return d.hasWindowFocus(); } } return false; } /** * Called to process key events. You can override this to intercept all * key events before they are dispatched to the window. Be sure to call * this implementation for key events that should be handled normally. * * @param event The key event. * * @return boolean Return true if this event was consumed. */ public boolean dispatchKeyEvent(KeyEvent event) { onUserInteraction(); if (getWindow().superDispatchKeyEvent(event)) { return true; } return event.dispatch(this); } /** * Called to process touch screen events. You can override this to * intercept all touch screen events before they are dispatched to the * window. Be sure to call this implementation for touch screen events * that should be handled normally. * * @param ev The touch screen event. * * @return boolean Return true if this event was consumed. */ public boolean dispatchTouchEvent(MotionEvent ev) { if (ev.getAction() == MotionEvent.ACTION_DOWN) { onUserInteraction(); } if (getWindow().superDispatchTouchEvent(ev)) { return true; } return onTouchEvent(ev); } /** * Called to process trackball events. You can override this to * intercept all trackball events before they are dispatched to the * window. Be sure to call this implementation for trackball events * that should be handled normally. * * @param ev The trackball event. * * @return boolean Return true if this event was consumed. */ public boolean dispatchTrackballEvent(MotionEvent ev) { onUserInteraction(); if (getWindow().superDispatchTrackballEvent(ev)) { return true; } return onTrackballEvent(ev); } public boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event) { event.setClassName(getClass().getName()); event.setPackageName(getPackageName()); LayoutParams params = getWindow().getAttributes(); boolean isFullScreen = (params.width == LayoutParams.FILL_PARENT) && (params.height == LayoutParams.FILL_PARENT); event.setFullScreen(isFullScreen); CharSequence title = getTitle(); if (!TextUtils.isEmpty(title)) { event.getText().add(title); } return true; } /** * Default implementation of * {@link android.view.Window.Callback#onCreatePanelView} * for activities. This * simply returns null so that all panel sub-windows will have the default * menu behavior. */ public View onCreatePanelView(int featureId) { return null; } /** * Default implementation of * {@link android.view.Window.Callback#onCreatePanelMenu} * for activities. This calls through to the new * {@link #onCreateOptionsMenu} method for the * {@link android.view.Window#FEATURE_OPTIONS_PANEL} panel, * so that subclasses of Activity don't need to deal with feature codes. */ public boolean onCreatePanelMenu(int featureId, Menu menu) { if (featureId == Window.FEATURE_OPTIONS_PANEL) { return onCreateOptionsMenu(menu); } return false; } /** * Default implementation of * {@link android.view.Window.Callback#onPreparePanel} * for activities. This * calls through to the new {@link #onPrepareOptionsMenu} method for the * {@link android.view.Window#FEATURE_OPTIONS_PANEL} * panel, so that subclasses of * Activity don't need to deal with feature codes. */ public boolean onPreparePanel(int featureId, View view, Menu menu) { if (featureId == Window.FEATURE_OPTIONS_PANEL && menu != null) { boolean goforit = onPrepareOptionsMenu(menu); return goforit && menu.hasVisibleItems(); } return true; } /** * {@inheritDoc} * * @return The default implementation returns true. */ public boolean onMenuOpened(int featureId, Menu menu) { return true; } /** * Default implementation of * {@link android.view.Window.Callback#onMenuItemSelected} * for activities. This calls through to the new * {@link #onOptionsItemSelected} method for the * {@link android.view.Window#FEATURE_OPTIONS_PANEL} * panel, so that subclasses of * Activity don't need to deal with feature codes. */ public boolean onMenuItemSelected(int featureId, MenuItem item) { switch (featureId) { case Window.FEATURE_OPTIONS_PANEL: // Put event logging here so it gets called even if subclass // doesn't call through to superclass's implmeentation of each // of these methods below EventLog.writeEvent(50000, 0, item.getTitleCondensed()); return onOptionsItemSelected(item); case Window.FEATURE_CONTEXT_MENU: EventLog.writeEvent(50000, 1, item.getTitleCondensed()); return onContextItemSelected(item); default: return false; } } /** * Default implementation of * {@link android.view.Window.Callback#onPanelClosed(int, Menu)} for * activities. This calls through to {@link #onOptionsMenuClosed(Menu)} * method for the {@link android.view.Window#FEATURE_OPTIONS_PANEL} panel, * so that subclasses of Activity don't need to deal with feature codes. * For context menus ({@link Window#FEATURE_CONTEXT_MENU}), the * {@link #onContextMenuClosed(Menu)} will be called. */ public void onPanelClosed(int featureId, Menu menu) { switch (featureId) { case Window.FEATURE_OPTIONS_PANEL: onOptionsMenuClosed(menu); break; case Window.FEATURE_CONTEXT_MENU: onContextMenuClosed(menu); break; } } /** * Initialize the contents of the Activity's standard options menu. You * should place your menu items in to menu. * *

This is only called once, the first time the options menu is * displayed. To update the menu every time it is displayed, see * {@link #onPrepareOptionsMenu}. * *

The default implementation populates the menu with standard system * menu items. These are placed in the {@link Menu#CATEGORY_SYSTEM} group so that * they will be correctly ordered with application-defined menu items. * Deriving classes should always call through to the base implementation. * *

You can safely hold on to menu (and any items created * from it), making modifications to it as desired, until the next * time onCreateOptionsMenu() is called. * *

When you add items to the menu, you can implement the Activity's * {@link #onOptionsItemSelected} method to handle them there. * * @param menu The options menu in which you place your items. * * @return You must return true for the menu to be displayed; * if you return false it will not be shown. * * @see #onPrepareOptionsMenu * @see #onOptionsItemSelected */ public boolean onCreateOptionsMenu(Menu menu) { if (mParent != null) { return mParent.onCreateOptionsMenu(menu); } return true; } /** * Prepare the Screen's standard options menu to be displayed. This is * called right before the menu is shown, every time it is shown. You can * use this method to efficiently enable/disable items or otherwise * dynamically modify the contents. * *

The default implementation updates the system menu items based on the * activity's state. Deriving classes should always call through to the * base class implementation. * * @param menu The options menu as last shown or first initialized by * onCreateOptionsMenu(). * * @return You must return true for the menu to be displayed; * if you return false it will not be shown. * * @see #onCreateOptionsMenu */ public boolean onPrepareOptionsMenu(Menu menu) { if (mParent != null) { return mParent.onPrepareOptionsMenu(menu); } return true; } /** * This hook is called whenever an item in your options menu is selected. * The default implementation simply returns false to have the normal * processing happen (calling the item's Runnable or sending a message to * its Handler as appropriate). You can use this method for any items * for which you would like to do processing without those other * facilities. * *

Derived classes should call through to the base class for it to * perform the default menu handling. * * @param item The menu item that was selected. * * @return boolean Return false to allow normal menu processing to * proceed, true to consume it here. * * @see #onCreateOptionsMenu */ public boolean onOptionsItemSelected(MenuItem item) { if (mParent != null) { return mParent.onOptionsItemSelected(item); } return false; } /** * This hook is called whenever the options menu is being closed (either by the user canceling * the menu with the back/menu button, or when an item is selected). * * @param menu The options menu as last shown or first initialized by * onCreateOptionsMenu(). */ public void onOptionsMenuClosed(Menu menu) { if (mParent != null) { mParent.onOptionsMenuClosed(menu); } } /** * Programmatically opens the options menu. If the options menu is already * open, this method does nothing. */ public void openOptionsMenu() { mWindow.openPanel(Window.FEATURE_OPTIONS_PANEL, null); } /** * Progammatically closes the options menu. If the options menu is already * closed, this method does nothing. */ public void closeOptionsMenu() { mWindow.closePanel(Window.FEATURE_OPTIONS_PANEL); } /** * Called when a context menu for the {@code view} is about to be shown. * Unlike {@link #onCreateOptionsMenu(Menu)}, this will be called every * time the context menu is about to be shown and should be populated for * the view (or item inside the view for {@link AdapterView} subclasses, * this can be found in the {@code menuInfo})). *

* Use {@link #onContextItemSelected(android.view.MenuItem)} to know when an * item has been selected. *

* It is not safe to hold onto the context menu after this method returns. * {@inheritDoc} */ public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo) { } /** * Registers a context menu to be shown for the given view (multiple views * can show the context menu). This method will set the * {@link OnCreateContextMenuListener} on the view to this activity, so * {@link #onCreateContextMenu(ContextMenu, View, ContextMenuInfo)} will be * called when it is time to show the context menu. * * @see #unregisterForContextMenu(View) * @param view The view that should show a context menu. */ public void registerForContextMenu(View view) { view.setOnCreateContextMenuListener(this); } /** * Prevents a context menu to be shown for the given view. This method will remove the * {@link OnCreateContextMenuListener} on the view. * * @see #registerForContextMenu(View) * @param view The view that should stop showing a context menu. */ public void unregisterForContextMenu(View view) { view.setOnCreateContextMenuListener(null); } /** * Programmatically opens the context menu for a particular {@code view}. * The {@code view} should have been added via * {@link #registerForContextMenu(View)}. * * @param view The view to show the context menu for. */ public void openContextMenu(View view) { view.showContextMenu(); } /** * Programmatically closes the most recently opened context menu, if showing. */ public void closeContextMenu() { mWindow.closePanel(Window.FEATURE_CONTEXT_MENU); } /** * This hook is called whenever an item in a context menu is selected. The * default implementation simply returns false to have the normal processing * happen (calling the item's Runnable or sending a message to its Handler * as appropriate). You can use this method for any items for which you * would like to do processing without those other facilities. *

* Use {@link MenuItem#getMenuInfo()} to get extra information set by the * View that added this menu item. *

* Derived classes should call through to the base class for it to perform * the default menu handling. * * @param item The context menu item that was selected. * @return boolean Return false to allow normal context menu processing to * proceed, true to consume it here. */ public boolean onContextItemSelected(MenuItem item) { if (mParent != null) { return mParent.onContextItemSelected(item); } return false; } /** * This hook is called whenever the context menu is being closed (either by * the user canceling the menu with the back/menu button, or when an item is * selected). * * @param menu The context menu that is being closed. */ public void onContextMenuClosed(Menu menu) { if (mParent != null) { mParent.onContextMenuClosed(menu); } } /** * Callback for creating dialogs that are managed (saved and restored) for you * by the activity. * * If you use {@link #showDialog(int)}, the activity will call through to * this method the first time, and hang onto it thereafter. Any dialog * that is created by this method will automatically be saved and restored * for you, including whether it is showing. * * If you would like the activity to manage the saving and restoring dialogs * for you, you should override this method and handle any ids that are * passed to {@link #showDialog}. * * If you would like an opportunity to prepare your dialog before it is shown, * override {@link #onPrepareDialog(int, Dialog)}. * * @param id The id of the dialog. * @return The dialog * * @see #onPrepareDialog(int, Dialog) * @see #showDialog(int) * @see #dismissDialog(int) * @see #removeDialog(int) */ protected Dialog onCreateDialog(int id) { return null; } /** * Provides an opportunity to prepare a managed dialog before it is being * shown. *

* Override this if you need to update a managed dialog based on the state * of the application each time it is shown. For example, a time picker * dialog might want to be updated with the current time. You should call * through to the superclass's implementation. The default implementation * will set this Activity as the owner activity on the Dialog. * * @param id The id of the managed dialog. * @param dialog The dialog. * @see #onCreateDialog(int) * @see #showDialog(int) * @see #dismissDialog(int) * @see #removeDialog(int) */ protected void onPrepareDialog(int id, Dialog dialog) { dialog.setOwnerActivity(this); } /** * Show a dialog managed by this activity. A call to {@link #onCreateDialog(int)} * will be made with the same id the first time this is called for a given * id. From thereafter, the dialog will be automatically saved and restored. * * Each time a dialog is shown, {@link #onPrepareDialog(int, Dialog)} will * be made to provide an opportunity to do any timely preparation. * * @param id The id of the managed dialog. * * @see Dialog * @see #onCreateDialog(int) * @see #onPrepareDialog(int, Dialog) * @see #dismissDialog(int) * @see #removeDialog(int) */ public final void showDialog(int id) { if (mManagedDialogs == null) { mManagedDialogs = new SparseArray

(); } Dialog dialog = mManagedDialogs.get(id); if (dialog == null) { dialog = createDialog(id, null); mManagedDialogs.put(id, dialog); } onPrepareDialog(id, dialog); dialog.show(); } /** * Dismiss a dialog that was previously shown via {@link #showDialog(int)}. * * @param id The id of the managed dialog. * * @throws IllegalArgumentException if the id was not previously shown via * {@link #showDialog(int)}. * * @see #onCreateDialog(int) * @see #onPrepareDialog(int, Dialog) * @see #showDialog(int) * @see #removeDialog(int) */ public final void dismissDialog(int id) { if (mManagedDialogs == null) { throw missingDialog(id); } final Dialog dialog = mManagedDialogs.get(id); if (dialog == null) { throw missingDialog(id); } dialog.dismiss(); } /** * Creates an exception to throw if a user passed in a dialog id that is * unexpected. */ private IllegalArgumentException missingDialog(int id) { return new IllegalArgumentException("no dialog with id " + id + " was ever " + "shown via Activity#showDialog"); } /** * Removes any internal references to a dialog managed by this Activity. * If the dialog is showing, it will dismiss it as part of the clean up. * * This can be useful if you know that you will never show a dialog again and * want to avoid the overhead of saving and restoring it in the future. * * @param id The id of the managed dialog. * * @see #onCreateDialog(int) * @see #onPrepareDialog(int, Dialog) * @see #showDialog(int) * @see #dismissDialog(int) */ public final void removeDialog(int id) { if (mManagedDialogs == null) { return; } final Dialog dialog = mManagedDialogs.get(id); if (dialog == null) { return; } dialog.dismiss(); mManagedDialogs.remove(id); } /** * This hook is called when the user signals the desire to start a search. * *

You can use this function as a simple way to launch the search UI, in response to a * menu item, search button, or other widgets within your activity. Unless overidden, * calling this function is the same as calling: *

The default implementation simply calls * {@link #startSearch startSearch(null, false, null, false)}, launching a local search. * *

You can override this function to force global search, e.g. in response to a dedicated * search key, or to block search entirely (by simply returning false). * * @return Returns true if search launched, false if activity blocks it * * @see android.app.SearchManager */ public boolean onSearchRequested() { startSearch(null, false, null, false); return true; } /** * This hook is called to launch the search UI. * *

It is typically called from onSearchRequested(), either directly from * Activity.onSearchRequested() or from an overridden version in any given * Activity. If your goal is simply to activate search, it is preferred to call * onSearchRequested(), which may have been overriden elsewhere in your Activity. If your goal * is to inject specific data such as context data, it is preferred to override * onSearchRequested(), so that any callers to it will benefit from the override. * * @param initialQuery Any non-null non-empty string will be inserted as * pre-entered text in the search query box. * @param selectInitialQuery If true, the intial query will be preselected, which means that * any further typing will replace it. This is useful for cases where an entire pre-formed * query is being inserted. If false, the selection point will be placed at the end of the * inserted query. This is useful when the inserted query is text that the user entered, * and the user would expect to be able to keep typing. This parameter is only meaningful * if initialQuery is a non-empty string. * @param appSearchData An application can insert application-specific * context here, in order to improve quality or specificity of its own * searches. This data will be returned with SEARCH intent(s). Null if * no extra data is required. * @param globalSearch If false, this will only launch the search that has been specifically * defined by the application (which is usually defined as a local search). If no default * search is defined in the current application or activity, global search will be launched. * If true, this will always launch a platform-global (e.g. web-based) search instead. * * @see android.app.SearchManager * @see #onSearchRequested */ public void startSearch(String initialQuery, boolean selectInitialQuery, Bundle appSearchData, boolean globalSearch) { ensureSearchManager(); mSearchManager.startSearch(initialQuery, selectInitialQuery, getComponentName(), appSearchData, globalSearch); } /** * Similar to {@link #startSearch}, but actually fires off the search query after invoking * the search dialog. Made available for testing purposes. * * @param query The query to trigger. If empty, the request will be ignored. * @param appSearchData An application can insert application-specific * context here, in order to improve quality or specificity of its own * searches. This data will be returned with SEARCH intent(s). Null if * no extra data is required. * @param globalSearch If false, this will only launch the search that has been specifically * defined by the application (which is usually defined as a local search). If no default * search is defined in the current application or activity, no search will be launched. * If true, this will always launch a platform-global (e.g. web-based) search instead. */ public void triggerSearch(String query, Bundle appSearchData, boolean globalSearch) { ensureSearchManager(); mSearchManager.triggerSearch(query, getComponentName(), appSearchData, globalSearch); } /** * Request that key events come to this activity. Use this if your * activity has no views with focus, but the activity still wants * a chance to process key events. * * @see android.view.Window#takeKeyEvents */ public void takeKeyEvents(boolean get) { getWindow().takeKeyEvents(get); } /** * Enable extended window features. This is a convenience for calling * {@link android.view.Window#requestFeature getWindow().requestFeature()}. * * @param featureId The desired feature as defined in * {@link android.view.Window}. * @return Returns true if the requested feature is supported and now * enabled. * * @see android.view.Window#requestFeature */ public final boolean requestWindowFeature(int featureId) { return getWindow().requestFeature(featureId); } /** * Convenience for calling * {@link android.view.Window#setFeatureDrawableResource}. */ public final void setFeatureDrawableResource(int featureId, int resId) { getWindow().setFeatureDrawableResource(featureId, resId); } /** * Convenience for calling * {@link android.view.Window#setFeatureDrawableUri}. */ public final void setFeatureDrawableUri(int featureId, Uri uri) { getWindow().setFeatureDrawableUri(featureId, uri); } /** * Convenience for calling * {@link android.view.Window#setFeatureDrawable(int, Drawable)}. */ public final void setFeatureDrawable(int featureId, Drawable drawable) { getWindow().setFeatureDrawable(featureId, drawable); } /** * Convenience for calling * {@link android.view.Window#setFeatureDrawableAlpha}. */ public final void setFeatureDrawableAlpha(int featureId, int alpha) { getWindow().setFeatureDrawableAlpha(featureId, alpha); } /** * Convenience for calling * {@link android.view.Window#getLayoutInflater}. */ public LayoutInflater getLayoutInflater() { return getWindow().getLayoutInflater(); } /** * Returns a {@link MenuInflater} with this context. */ public MenuInflater getMenuInflater() { return new MenuInflater(this); } @Override protected void onApplyThemeResource(Resources.Theme theme, int resid, boolean first) { if (mParent == null) { super.onApplyThemeResource(theme, resid, first); } else { try { theme.setTo(mParent.getTheme()); } catch (Exception e) { // Empty } theme.applyStyle(resid, false); } } /** * Launch an activity for which you would like a result when it finished. * When this activity exits, your * onActivityResult() method will be called with the given requestCode. * Using a negative requestCode is the same as calling * {@link #startActivity} (the activity is not launched as a sub-activity). * *

Note that this method should only be used with Intent protocols * that are defined to return a result. In other protocols (such as * {@link Intent#ACTION_MAIN} or {@link Intent#ACTION_VIEW}), you may * not get the result when you expect. For example, if the activity you * are launching uses the singleTask launch mode, it will not run in your * task and thus you will immediately receive a cancel result. * *

As a special case, if you call startActivityForResult() with a requestCode * >= 0 during the initial onCreate(Bundle savedInstanceState)/onResume() of your * activity, then your window will not be displayed until a result is * returned back from the started activity. This is to avoid visible * flickering when redirecting to another activity. * *

This method throws {@link android.content.ActivityNotFoundException} * if there was no Activity found to run the given Intent. * * @param intent The intent to start. * @param requestCode If >= 0, this code will be returned in * onActivityResult() when the activity exits. * * @throws android.content.ActivityNotFoundException * * @see #startActivity */ public void startActivityForResult(Intent intent, int requestCode) { if (mParent == null) { Instrumentation.ActivityResult ar = mInstrumentation.execStartActivity( this, mMainThread.getApplicationThread(), mToken, this, intent, requestCode); if (ar != null) { mMainThread.sendActivityResult( mToken, mEmbeddedID, requestCode, ar.getResultCode(), ar.getResultData()); } if (requestCode >= 0) { // If this start is requesting a result, we can avoid making // the activity visible until the result is received. Setting // this code during onCreate(Bundle savedInstanceState) or onResume() will keep the // activity hidden during this time, to avoid flickering. // This can only be done when a result is requested because // that guarantees we will get information back when the // activity is finished, no matter what happens to it. mStartedActivity = true; } } else { mParent.startActivityFromChild(this, intent, requestCode); } } /** * Launch a new activity. You will not receive any information about when * the activity exits. This implementation overrides the base version, * providing information about * the activity performing the launch. Because of this additional * information, the {@link Intent#FLAG_ACTIVITY_NEW_TASK} launch flag is not * required; if not specified, the new activity will be added to the * task of the caller. * *

This method throws {@link android.content.ActivityNotFoundException} * if there was no Activity found to run the given Intent. * * @param intent The intent to start. * * @throws android.content.ActivityNotFoundException * * @see #startActivityForResult */ @Override public void startActivity(Intent intent) { startActivityForResult(intent, -1); } /** * A special variation to launch an activity only if a new activity * instance is needed to handle the given Intent. In other words, this is * just like {@link #startActivityForResult(Intent, int)} except: if you are * using the {@link Intent#FLAG_ACTIVITY_SINGLE_TOP} flag, or * singleTask or singleTop * {@link android.R.styleable#AndroidManifestActivity_launchMode launchMode}, * and the activity * that handles intent is the same as your currently running * activity, then a new instance is not needed. In this case, instead of * the normal behavior of calling {@link #onNewIntent} this function will * return and you can handle the Intent yourself. * *

This function can only be called from a top-level activity; if it is * called from a child activity, a runtime exception will be thrown. * * @param intent The intent to start. * @param requestCode If >= 0, this code will be returned in * onActivityResult() when the activity exits, as described in * {@link #startActivityForResult}. * * @return If a new activity was launched then true is returned; otherwise * false is returned and you must handle the Intent yourself. * * @see #startActivity * @see #startActivityForResult */ public boolean startActivityIfNeeded(Intent intent, int requestCode) { if (mParent == null) { int result = IActivityManager.START_RETURN_INTENT_TO_CALLER; try { result = ActivityManagerNative.getDefault() .startActivity(mMainThread.getApplicationThread(), intent, intent.resolveTypeIfNeeded( getContentResolver()), null, 0, mToken, mEmbeddedID, requestCode, true, false); } catch (RemoteException e) { // Empty } Instrumentation.checkStartActivityResult(result, intent); if (requestCode >= 0) { // If this start is requesting a result, we can avoid making // the activity visible until the result is received. Setting // this code during onCreate(Bundle savedInstanceState) or onResume() will keep the // activity hidden during this time, to avoid flickering. // This can only be done when a result is requested because // that guarantees we will get information back when the // activity is finished, no matter what happens to it. mStartedActivity = true; } return result != IActivityManager.START_RETURN_INTENT_TO_CALLER; } throw new UnsupportedOperationException( "startActivityIfNeeded can only be called from a top-level activity"); } /** * Special version of starting an activity, for use when you are replacing * other activity components. You can use this to hand the Intent off * to the next Activity that can handle it. You typically call this in * {@link #onCreate} with the Intent returned by {@link #getIntent}. * * @param intent The intent to dispatch to the next activity. For * correct behavior, this must be the same as the Intent that started * your own activity; the only changes you can make are to the extras * inside of it. * * @return Returns a boolean indicating whether there was another Activity * to start: true if there was a next activity to start, false if there * wasn't. In general, if true is returned you will then want to call * finish() on yourself. */ public boolean startNextMatchingActivity(Intent intent) { if (mParent == null) { try { return ActivityManagerNative.getDefault() .startNextMatchingActivity(mToken, intent); } catch (RemoteException e) { // Empty } return false; } throw new UnsupportedOperationException( "startNextMatchingActivity can only be called from a top-level activity"); } /** * This is called when a child activity of this one calls its * {@link #startActivity} or {@link #startActivityForResult} method. * *

This method throws {@link android.content.ActivityNotFoundException} * if there was no Activity found to run the given Intent. * * @param child The activity making the call. * @param intent The intent to start. * @param requestCode Reply request code. < 0 if reply is not requested. * * @throws android.content.ActivityNotFoundException * * @see #startActivity * @see #startActivityForResult */ public void startActivityFromChild(Activity child, Intent intent, int requestCode) { Instrumentation.ActivityResult ar = mInstrumentation.execStartActivity( this, mMainThread.getApplicationThread(), mToken, child, intent, requestCode); if (ar != null) { mMainThread.sendActivityResult( mToken, child.mEmbeddedID, requestCode, ar.getResultCode(), ar.getResultData()); } } /** * Call this to set the result that your activity will return to its * caller. * * @param resultCode The result code to propagate back to the originating * activity, often RESULT_CANCELED or RESULT_OK * * @see #RESULT_CANCELED * @see #RESULT_OK * @see #RESULT_FIRST_USER * @see #setResult(int, Intent) */ public final void setResult(int resultCode) { synchronized (this) { mResultCode = resultCode; mResultData = null; } } /** * Call this to set the result that your activity will return to its * caller. * * @param resultCode The result code to propagate back to the originating * activity, often RESULT_CANCELED or RESULT_OK * @param data The data to propagate back to the originating activity. * * @see #RESULT_CANCELED * @see #RESULT_OK * @see #RESULT_FIRST_USER * @see #setResult(int) */ public final void setResult(int resultCode, Intent data) { synchronized (this) { mResultCode = resultCode; mResultData = data; } } /** * Return the name of the package that invoked this activity. This is who * the data in {@link #setResult setResult()} will be sent to. You can * use this information to validate that the recipient is allowed to * receive the data. * *

Note: if the calling activity is not expecting a result (that is it * did not use the {@link #startActivityForResult} * form that includes a request code), then the calling package will be * null. * * @return The package of the activity that will receive your * reply, or null if none. */ public String getCallingPackage() { try { return ActivityManagerNative.getDefault().getCallingPackage(mToken); } catch (RemoteException e) { return null; } } /** * Return the name of the activity that invoked this activity. This is * who the data in {@link #setResult setResult()} will be sent to. You * can use this information to validate that the recipient is allowed to * receive the data. * *

Note: if the calling activity is not expecting a result (that is it * did not use the {@link #startActivityForResult} * form that includes a request code), then the calling package will be * null. * * @return String The full name of the activity that will receive your * reply, or null if none. */ public ComponentName getCallingActivity() { try { return ActivityManagerNative.getDefault().getCallingActivity(mToken); } catch (RemoteException e) { return null; } } /** * Control whether this activity's main window is visible. This is intended * only for the special case of an activity that is not going to show a * UI itself, but can't just finish prior to onResume() because it needs * to wait for a service binding or such. Setting this to false allows * you to prevent your UI from being shown during that time. * *

The default value for this is taken from the * {@link android.R.attr#windowNoDisplay} attribute of the activity's theme. */ public void setVisible(boolean visible) { if (mVisibleFromClient != visible) { mVisibleFromClient = visible; if (mVisibleFromServer) { if (visible) makeVisible(); else mDecor.setVisibility(View.INVISIBLE); } } } void makeVisible() { if (!mWindowAdded) { ViewManager wm = getWindowManager(); wm.addView(mDecor, getWindow().getAttributes()); mWindowAdded = true; } mDecor.setVisibility(View.VISIBLE); } /** * Check to see whether this activity is in the process of finishing, * either because you called {@link #finish} on it or someone else * has requested that it finished. This is often used in * {@link #onPause} to determine whether the activity is simply pausing or * completely finishing. * * @return If the activity is finishing, returns true; else returns false. * * @see #finish */ public boolean isFinishing() { return mFinished; } /** * Call this when your activity is done and should be closed. The * ActivityResult is propagated back to whoever launched you via * onActivityResult(). */ public void finish() { if (mParent == null) { int resultCode; Intent resultData; synchronized (this) { resultCode = mResultCode; resultData = mResultData; } if (Config.LOGV) Log.v(TAG, "Finishing self: token=" + mToken); try { if (ActivityManagerNative.getDefault() .finishActivity(mToken, resultCode, resultData)) { mFinished = true; } } catch (RemoteException e) { // Empty } } else { mParent.finishFromChild(this); } } /** * This is called when a child activity of this one calls its * {@link #finish} method. The default implementation simply calls * finish() on this activity (the parent), finishing the entire group. * * @param child The activity making the call. * * @see #finish */ public void finishFromChild(Activity child) { finish(); } /** * Force finish another activity that you had previously started with * {@link #startActivityForResult}. * * @param requestCode The request code of the activity that you had * given to startActivityForResult(). If there are multiple * activities started with this request code, they * will all be finished. */ public void finishActivity(int requestCode) { if (mParent == null) { try { ActivityManagerNative.getDefault() .finishSubActivity(mToken, mEmbeddedID, requestCode); } catch (RemoteException e) { // Empty } } else { mParent.finishActivityFromChild(this, requestCode); } } /** * This is called when a child activity of this one calls its * finishActivity(). * * @param child The activity making the call. * @param requestCode Request code that had been used to start the * activity. */ public void finishActivityFromChild(Activity child, int requestCode) { try { ActivityManagerNative.getDefault() .finishSubActivity(mToken, child.mEmbeddedID, requestCode); } catch (RemoteException e) { // Empty } } /** * Called when an activity you launched exits, giving you the requestCode * you started it with, the resultCode it returned, and any additional * data from it. The resultCode will be * {@link #RESULT_CANCELED} if the activity explicitly returned that, * didn't return any result, or crashed during its operation. * *

You will receive this call immediately before onResume() when your * activity is re-starting. * * @param requestCode The integer request code originally supplied to * startActivityForResult(), allowing you to identify who this * result came from. * @param resultCode The integer result code returned by the child activity * through its setResult(). * @param data An Intent, which can return result data to the caller * (various data can be attached to Intent "extras"). * * @see #startActivityForResult * @see #createPendingResult * @see #setResult(int) */ protected void onActivityResult(int requestCode, int resultCode, Intent data) { } /** * Create a new PendingIntent object which you can hand to others * for them to use to send result data back to your * {@link #onActivityResult} callback. The created object will be either * one-shot (becoming invalid after a result is sent back) or multiple * (allowing any number of results to be sent through it). * * @param requestCode Private request code for the sender that will be * associated with the result data when it is returned. The sender can not * modify this value, allowing you to identify incoming results. * @param data Default data to supply in the result, which may be modified * by the sender. * @param flags May be {@link PendingIntent#FLAG_ONE_SHOT PendingIntent.FLAG_ONE_SHOT}, * {@link PendingIntent#FLAG_NO_CREATE PendingIntent.FLAG_NO_CREATE}, * {@link PendingIntent#FLAG_CANCEL_CURRENT PendingIntent.FLAG_CANCEL_CURRENT}, * {@link PendingIntent#FLAG_UPDATE_CURRENT PendingIntent.FLAG_UPDATE_CURRENT}, * or any of the flags as supported by * {@link Intent#fillIn Intent.fillIn()} to control which unspecified parts * of the intent that can be supplied when the actual send happens. * * @return Returns an existing or new PendingIntent matching the given * parameters. May return null only if * {@link PendingIntent#FLAG_NO_CREATE PendingIntent.FLAG_NO_CREATE} has been * supplied. * * @see PendingIntent */ public PendingIntent createPendingResult(int requestCode, Intent data, int flags) { String packageName = getPackageName(); try { IIntentSender target = ActivityManagerNative.getDefault().getIntentSender( IActivityManager.INTENT_SENDER_ACTIVITY_RESULT, packageName, mParent == null ? mToken : mParent.mToken, mEmbeddedID, requestCode, data, null, flags); return target != null ? new PendingIntent(target) : null; } catch (RemoteException e) { // Empty } return null; } /** * Change the desired orientation of this activity. If the activity * is currently in the foreground or otherwise impacting the screen * orientation, the screen will immediately be changed (possibly causing * the activity to be restarted). Otherwise, this will be used the next * time the activity is visible. * * @param requestedOrientation An orientation constant as used in * {@link ActivityInfo#screenOrientation ActivityInfo.screenOrientation}. */ public void setRequestedOrientation(int requestedOrientation) { if (mParent == null) { try { ActivityManagerNative.getDefault().setRequestedOrientation( mToken, requestedOrientation); } catch (RemoteException e) { // Empty } } else { mParent.setRequestedOrientation(requestedOrientation); } } /** * Return the current requested orientation of the activity. This will * either be the orientation requested in its component's manifest, or * the last requested orientation given to * {@link #setRequestedOrientation(int)}. * * @return Returns an orientation constant as used in * {@link ActivityInfo#screenOrientation ActivityInfo.screenOrientation}. */ public int getRequestedOrientation() { if (mParent == null) { try { return ActivityManagerNative.getDefault() .getRequestedOrientation(mToken); } catch (RemoteException e) { // Empty } } else { return mParent.getRequestedOrientation(); } return ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED; } /** * Return the identifier of the task this activity is in. This identifier * will remain the same for the lifetime of the activity. * * @return Task identifier, an opaque integer. */ public int getTaskId() { try { return ActivityManagerNative.getDefault() .getTaskForActivity(mToken, false); } catch (RemoteException e) { return -1; } } /** * Return whether this activity is the root of a task. The root is the * first activity in a task. * * @return True if this is the root activity, else false. */ public boolean isTaskRoot() { try { return ActivityManagerNative.getDefault() .getTaskForActivity(mToken, true) >= 0; } catch (RemoteException e) { return false; } } /** * Move the task containing this activity to the back of the activity * stack. The activity's order within the task is unchanged. * * @param nonRoot If false then this only works if the activity is the root * of a task; if true it will work for any activity in * a task. * * @return If the task was moved (or it was already at the * back) true is returned, else false. */ public boolean moveTaskToBack(boolean nonRoot) { try { return ActivityManagerNative.getDefault().moveActivityTaskToBack( mToken, nonRoot); } catch (RemoteException e) { // Empty } return false; } /** * Returns class name for this activity with the package prefix removed. * This is the default name used to read and write settings. * * @return The local class name. */ public String getLocalClassName() { final String pkg = getPackageName(); final String cls = mComponent.getClassName(); int packageLen = pkg.length(); if (!cls.startsWith(pkg) || cls.length() <= packageLen || cls.charAt(packageLen) != '.') { return cls; } return cls.substring(packageLen+1); } /** * Returns complete component name of this activity. * * @return Returns the complete component name for this activity */ public ComponentName getComponentName() { return mComponent; } /** * Retrieve a {@link SharedPreferences} object for accessing preferences * that are private to this activity. This simply calls the underlying * {@link #getSharedPreferences(String, int)} method by passing in this activity's * class name as the preferences name. * * @param mode Operating mode. Use {@link #MODE_PRIVATE} for the default * operation, {@link #MODE_WORLD_READABLE} and * {@link #MODE_WORLD_WRITEABLE} to control permissions. * * @return Returns the single SharedPreferences instance that can be used * to retrieve and modify the preference values. */ public SharedPreferences getPreferences(int mode) { return getSharedPreferences(getLocalClassName(), mode); } private void ensureSearchManager() { if (mSearchManager != null) { return; } // uses super.getSystemService() since this.getSystemService() looks at the // mSearchManager field. mSearchManager = (SearchManager) super.getSystemService(Context.SEARCH_SERVICE); int ident = mIdent; if (ident == 0) { if (mParent != null) ident = mParent.mIdent; if (ident == 0) { throw new IllegalArgumentException("no ident"); } } mSearchManager.setIdent(ident, getComponentName()); } @Override public Object getSystemService(String name) { if (getBaseContext() == null) { throw new IllegalStateException( "System services not available to Activities before onCreate()"); } if (WINDOW_SERVICE.equals(name)) { return mWindowManager; } else if (SEARCH_SERVICE.equals(name)) { ensureSearchManager(); return mSearchManager; } return super.getSystemService(name); } /** * Change the title associated with this activity. If this is a * top-level activity, the title for its window will change. If it * is an embedded activity, the parent can do whatever it wants * with it. */ public void setTitle(CharSequence title) { mTitle = title; onTitleChanged(title, mTitleColor); if (mParent != null) { mParent.onChildTitleChanged(this, title); } } /** * Change the title associated with this activity. If this is a * top-level activity, the title for its window will change. If it * is an embedded activity, the parent can do whatever it wants * with it. */ public void setTitle(int titleId) { setTitle(getText(titleId)); } public void setTitleColor(int textColor) { mTitleColor = textColor; onTitleChanged(mTitle, textColor); } public final CharSequence getTitle() { return mTitle; } public final int getTitleColor() { return mTitleColor; } protected void onTitleChanged(CharSequence title, int color) { if (mTitleReady) { final Window win = getWindow(); if (win != null) { win.setTitle(title); if (color != 0) { win.setTitleColor(color); } } } } protected void onChildTitleChanged(Activity childActivity, CharSequence title) { } /** * Sets the visibility of the progress bar in the title. *

* In order for the progress bar to be shown, the feature must be requested * via {@link #requestWindowFeature(int)}. * * @param visible Whether to show the progress bars in the title. */ public final void setProgressBarVisibility(boolean visible) { getWindow().setFeatureInt(Window.FEATURE_PROGRESS, visible ? Window.PROGRESS_VISIBILITY_ON : Window.PROGRESS_VISIBILITY_OFF); } /** * Sets the visibility of the indeterminate progress bar in the title. *

* In order for the progress bar to be shown, the feature must be requested * via {@link #requestWindowFeature(int)}. * * @param visible Whether to show the progress bars in the title. */ public final void setProgressBarIndeterminateVisibility(boolean visible) { getWindow().setFeatureInt(Window.FEATURE_INDETERMINATE_PROGRESS, visible ? Window.PROGRESS_VISIBILITY_ON : Window.PROGRESS_VISIBILITY_OFF); } /** * Sets whether the horizontal progress bar in the title should be indeterminate (the circular * is always indeterminate). *

* In order for the progress bar to be shown, the feature must be requested * via {@link #requestWindowFeature(int)}. * * @param indeterminate Whether the horizontal progress bar should be indeterminate. */ public final void setProgressBarIndeterminate(boolean indeterminate) { getWindow().setFeatureInt(Window.FEATURE_PROGRESS, indeterminate ? Window.PROGRESS_INDETERMINATE_ON : Window.PROGRESS_INDETERMINATE_OFF); } /** * Sets the progress for the progress bars in the title. *

* In order for the progress bar to be shown, the feature must be requested * via {@link #requestWindowFeature(int)}. * * @param progress The progress for the progress bar. Valid ranges are from * 0 to 10000 (both inclusive). If 10000 is given, the progress * bar will be completely filled and will fade out. */ public final void setProgress(int progress) { getWindow().setFeatureInt(Window.FEATURE_PROGRESS, progress + Window.PROGRESS_START); } /** * Sets the secondary progress for the progress bar in the title. This * progress is drawn between the primary progress (set via * {@link #setProgress(int)} and the background. It can be ideal for media * scenarios such as showing the buffering progress while the default * progress shows the play progress. *

* In order for the progress bar to be shown, the feature must be requested * via {@link #requestWindowFeature(int)}. * * @param secondaryProgress The secondary progress for the progress bar. Valid ranges are from * 0 to 10000 (both inclusive). */ public final void setSecondaryProgress(int secondaryProgress) { getWindow().setFeatureInt(Window.FEATURE_PROGRESS, secondaryProgress + Window.PROGRESS_SECONDARY_START); } /** * Suggests an audio stream whose volume should be changed by the hardware * volume controls. *

* The suggested audio stream will be tied to the window of this Activity. * If the Activity is switched, the stream set here is no longer the * suggested stream. The client does not need to save and restore the old * suggested stream value in onPause and onResume. * * @param streamType The type of the audio stream whose volume should be * changed by the hardware volume controls. It is not guaranteed that * the hardware volume controls will always change this stream's * volume (for example, if a call is in progress, its stream's volume * may be changed instead). To reset back to the default, use * {@link AudioManager#USE_DEFAULT_STREAM_TYPE}. */ public final void setVolumeControlStream(int streamType) { getWindow().setVolumeControlStream(streamType); } /** * Gets the suggested audio stream whose volume should be changed by the * harwdare volume controls. * * @return The suggested audio stream type whose volume should be changed by * the hardware volume controls. * @see #setVolumeControlStream(int) */ public final int getVolumeControlStream() { return getWindow().getVolumeControlStream(); } /** * Runs the specified action on the UI thread. If the current thread is the UI * thread, then the action is executed immediately. If the current thread is * not the UI thread, the action is posted to the event queue of the UI thread. * * @param action the action to run on the UI thread */ public final void runOnUiThread(Runnable action) { if (Thread.currentThread() != mUiThread) { mHandler.post(action); } else { action.run(); } } /** * Stub implementation of {@link android.view.LayoutInflater.Factory#onCreateView} used when * inflating with the LayoutInflater returned by {@link #getSystemService}. This * implementation simply returns null for all view names. * * @see android.view.LayoutInflater#createView * @see android.view.Window#getLayoutInflater */ public View onCreateView(String name, Context context, AttributeSet attrs) { return null; } // ------------------ Internal API ------------------ final void setParent(Activity parent) { mParent = parent; } final void attach(Context context, ActivityThread aThread, Instrumentation instr, IBinder token, Application application, Intent intent, ActivityInfo info, CharSequence title, Activity parent, String id, Object lastNonConfigurationInstance, Configuration config) { attach(context, aThread, instr, token, 0, application, intent, info, title, parent, id, lastNonConfigurationInstance, null, config); } final void attach(Context context, ActivityThread aThread, Instrumentation instr, IBinder token, int ident, Application application, Intent intent, ActivityInfo info, CharSequence title, Activity parent, String id, Object lastNonConfigurationInstance, HashMap lastNonConfigurationChildInstances, Configuration config) { attachBaseContext(context); mWindow = PolicyManager.makeNewWindow(this); mWindow.setCallback(this); if (info.softInputMode != WindowManager.LayoutParams.SOFT_INPUT_STATE_UNSPECIFIED) { mWindow.setSoftInputMode(info.softInputMode); } mUiThread = Thread.currentThread(); mMainThread = aThread; mInstrumentation = instr; mToken = token; mIdent = ident; mApplication = application; mIntent = intent; mComponent = intent.getComponent(); mActivityInfo = info; mTitle = title; mParent = parent; mEmbeddedID = id; mLastNonConfigurationInstance = lastNonConfigurationInstance; mLastNonConfigurationChildInstances = lastNonConfigurationChildInstances; mWindow.setWindowManager(null, mToken, mComponent.flattenToString()); if (mParent != null) { mWindow.setContainer(mParent.getWindow()); } mWindowManager = mWindow.getWindowManager(); mCurrentConfig = config; } final IBinder getActivityToken() { return mParent != null ? mParent.getActivityToken() : mToken; } final void performStart() { mCalled = false; mInstrumentation.callActivityOnStart(this); if (!mCalled) { throw new SuperNotCalledException( "Activity " + mComponent.toShortString() + " did not call through to super.onStart()"); } } final void performRestart() { final int N = mManagedCursors.size(); for (int i=0; i