Home | History | Annotate | Download | only in app
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.app;
     18 
     19 import android.content.Context;
     20 import android.content.DialogInterface;
     21 import android.os.Bundle;
     22 import android.view.LayoutInflater;
     23 import android.view.View;
     24 import android.view.ViewGroup;
     25 import android.view.Window;
     26 import android.view.WindowManager;
     27 
     28 import java.io.FileDescriptor;
     29 import java.io.PrintWriter;
     30 
     31 /**
     32  * A fragment that displays a dialog window, floating on top of its
     33  * activity's window.  This fragment contains a Dialog object, which it
     34  * displays as appropriate based on the fragment's state.  Control of
     35  * the dialog (deciding when to show, hide, dismiss it) should be done through
     36  * the API here, not with direct calls on the dialog.
     37  *
     38  * <p>Implementations should override this class and implement
     39  * {@link #onCreateView(LayoutInflater, ViewGroup, Bundle)} to supply the
     40  * content of the dialog.  Alternatively, they can override
     41  * {@link #onCreateDialog(Bundle)} to create an entirely custom dialog, such
     42  * as an AlertDialog, with its own content.
     43  *
     44  * <p>Topics covered here:
     45  * <ol>
     46  * <li><a href="#Lifecycle">Lifecycle</a>
     47  * <li><a href="#BasicDialog">Basic Dialog</a>
     48  * <li><a href="#AlertDialog">Alert Dialog</a>
     49  * <li><a href="#DialogOrEmbed">Selecting Between Dialog or Embedding</a>
     50  * </ol>
     51  *
     52  * <a name="Lifecycle"></a>
     53  * <h3>Lifecycle</h3>
     54  *
     55  * <p>DialogFragment does various things to keep the fragment's lifecycle
     56  * driving it, instead of the Dialog.  Note that dialogs are generally
     57  * autonomous entities -- they are their own window, receiving their own
     58  * input events, and often deciding on their own when to disappear (by
     59  * receiving a back key event or the user clicking on a button).
     60  *
     61  * <p>DialogFragment needs to ensure that what is happening with the Fragment
     62  * and Dialog states remains consistent.  To do this, it watches for dismiss
     63  * events from the dialog and takes care of removing its own state when they
     64  * happen.  This means you should use {@link #show(FragmentManager, String)}
     65  * or {@link #show(FragmentTransaction, String)} to add an instance of
     66  * DialogFragment to your UI, as these keep track of how DialogFragment should
     67  * remove itself when the dialog is dismissed.
     68  *
     69  * <a name="BasicDialog"></a>
     70  * <h3>Basic Dialog</h3>
     71  *
     72  * <p>The simplest use of DialogFragment is as a floating container for the
     73  * fragment's view hierarchy.  A simple implementation may look like this:
     74  *
     75  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentDialog.java
     76  *      dialog}
     77  *
     78  * <p>An example showDialog() method on the Activity could be:
     79  *
     80  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentDialog.java
     81  *      add_dialog}
     82  *
     83  * <p>This removes any currently shown dialog, creates a new DialogFragment
     84  * with an argument, and shows it as a new state on the back stack.  When the
     85  * transaction is popped, the current DialogFragment and its Dialog will be
     86  * destroyed, and the previous one (if any) re-shown.  Note that in this case
     87  * DialogFragment will take care of popping the transaction of the Dialog
     88  * is dismissed separately from it.
     89  *
     90  * <a name="AlertDialog"></a>
     91  * <h3>Alert Dialog</h3>
     92  *
     93  * <p>Instead of (or in addition to) implementing {@link #onCreateView} to
     94  * generate the view hierarchy inside of a dialog, you may implement
     95  * {@link #onCreateDialog(Bundle)} to create your own custom Dialog object.
     96  *
     97  * <p>This is most useful for creating an {@link AlertDialog}, allowing you
     98  * to display standard alerts to the user that are managed by a fragment.
     99  * A simple example implementation of this is:
    100  *
    101  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentAlertDialog.java
    102  *      dialog}
    103  *
    104  * <p>The activity creating this fragment may have the following methods to
    105  * show the dialog and receive results from it:
    106  *
    107  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentAlertDialog.java
    108  *      activity}
    109  *
    110  * <p>Note that in this case the fragment is not placed on the back stack, it
    111  * is just added as an indefinitely running fragment.  Because dialogs normally
    112  * are modal, this will still operate as a back stack, since the dialog will
    113  * capture user input until it is dismissed.  When it is dismissed, DialogFragment
    114  * will take care of removing itself from its fragment manager.
    115  *
    116  * <a name="DialogOrEmbed"></a>
    117  * <h3>Selecting Between Dialog or Embedding</h3>
    118  *
    119  * <p>A DialogFragment can still optionally be used as a normal fragment, if
    120  * desired.  This is useful if you have a fragment that in some cases should
    121  * be shown as a dialog and others embedded in a larger UI.  This behavior
    122  * will normally be automatically selected for you based on how you are using
    123  * the fragment, but can be customized with {@link #setShowsDialog(boolean)}.
    124  *
    125  * <p>For example, here is a simple dialog fragment:
    126  *
    127  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentDialogOrActivity.java
    128  *      dialog}
    129  *
    130  * <p>An instance of this fragment can be created and shown as a dialog:
    131  *
    132  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentDialogOrActivity.java
    133  *      show_dialog}
    134  *
    135  * <p>It can also be added as content in a view hierarchy:
    136  *
    137  * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentDialogOrActivity.java
    138  *      embed}
    139  */
    140 public class DialogFragment extends Fragment
    141         implements DialogInterface.OnCancelListener, DialogInterface.OnDismissListener {
    142 
    143     /**
    144      * Style for {@link #setStyle(int, int)}: a basic,
    145      * normal dialog.
    146      */
    147     public static final int STYLE_NORMAL = 0;
    148 
    149     /**
    150      * Style for {@link #setStyle(int, int)}: don't include
    151      * a title area.
    152      */
    153     public static final int STYLE_NO_TITLE = 1;
    154 
    155     /**
    156      * Style for {@link #setStyle(int, int)}: don't draw
    157      * any frame at all; the view hierarchy returned by {@link #onCreateView}
    158      * is entirely responsible for drawing the dialog.
    159      */
    160     public static final int STYLE_NO_FRAME = 2;
    161 
    162     /**
    163      * Style for {@link #setStyle(int, int)}: like
    164      * {@link #STYLE_NO_FRAME}, but also disables all input to the dialog.
    165      * The user can not touch it, and its window will not receive input focus.
    166      */
    167     public static final int STYLE_NO_INPUT = 3;
    168 
    169     private static final String SAVED_DIALOG_STATE_TAG = "android:savedDialogState";
    170     private static final String SAVED_STYLE = "android:style";
    171     private static final String SAVED_THEME = "android:theme";
    172     private static final String SAVED_CANCELABLE = "android:cancelable";
    173     private static final String SAVED_SHOWS_DIALOG = "android:showsDialog";
    174     private static final String SAVED_BACK_STACK_ID = "android:backStackId";
    175 
    176     int mStyle = STYLE_NORMAL;
    177     int mTheme = 0;
    178     boolean mCancelable = true;
    179     boolean mShowsDialog = true;
    180     int mBackStackId = -1;
    181 
    182     Dialog mDialog;
    183     boolean mViewDestroyed;
    184     boolean mDismissed;
    185     boolean mShownByMe;
    186 
    187     public DialogFragment() {
    188     }
    189 
    190     /**
    191      * Call to customize the basic appearance and behavior of the
    192      * fragment's dialog.  This can be used for some common dialog behaviors,
    193      * taking care of selecting flags, theme, and other options for you.  The
    194      * same effect can be achieve by manually setting Dialog and Window
    195      * attributes yourself.  Calling this after the fragment's Dialog is
    196      * created will have no effect.
    197      *
    198      * @param style Selects a standard style: may be {@link #STYLE_NORMAL},
    199      * {@link #STYLE_NO_TITLE}, {@link #STYLE_NO_FRAME}, or
    200      * {@link #STYLE_NO_INPUT}.
    201      * @param theme Optional custom theme.  If 0, an appropriate theme (based
    202      * on the style) will be selected for you.
    203      */
    204     public void setStyle(int style, int theme) {
    205         mStyle = style;
    206         if (mStyle == STYLE_NO_FRAME || mStyle == STYLE_NO_INPUT) {
    207             mTheme = com.android.internal.R.style.Theme_DeviceDefault_Dialog_NoFrame;
    208         }
    209         if (theme != 0) {
    210             mTheme = theme;
    211         }
    212     }
    213 
    214     /**
    215      * Display the dialog, adding the fragment to the given FragmentManager.  This
    216      * is a convenience for explicitly creating a transaction, adding the
    217      * fragment to it with the given tag, and committing it.  This does
    218      * <em>not</em> add the transaction to the back stack.  When the fragment
    219      * is dismissed, a new transaction will be executed to remove it from
    220      * the activity.
    221      * @param manager The FragmentManager this fragment will be added to.
    222      * @param tag The tag for this fragment, as per
    223      * {@link FragmentTransaction#add(Fragment, String) FragmentTransaction.add}.
    224      */
    225     public void show(FragmentManager manager, String tag) {
    226         mDismissed = false;
    227         mShownByMe = true;
    228         FragmentTransaction ft = manager.beginTransaction();
    229         ft.add(this, tag);
    230         ft.commit();
    231     }
    232 
    233     /**
    234      * Display the dialog, adding the fragment using an existing transaction
    235      * and then committing the transaction.
    236      * @param transaction An existing transaction in which to add the fragment.
    237      * @param tag The tag for this fragment, as per
    238      * {@link FragmentTransaction#add(Fragment, String) FragmentTransaction.add}.
    239      * @return Returns the identifier of the committed transaction, as per
    240      * {@link FragmentTransaction#commit() FragmentTransaction.commit()}.
    241      */
    242     public int show(FragmentTransaction transaction, String tag) {
    243         mDismissed = false;
    244         mShownByMe = true;
    245         transaction.add(this, tag);
    246         mViewDestroyed = false;
    247         mBackStackId = transaction.commit();
    248         return mBackStackId;
    249     }
    250 
    251     /**
    252      * Dismiss the fragment and its dialog.  If the fragment was added to the
    253      * back stack, all back stack state up to and including this entry will
    254      * be popped.  Otherwise, a new transaction will be committed to remove
    255      * the fragment.
    256      */
    257     public void dismiss() {
    258         dismissInternal(false);
    259     }
    260 
    261     /**
    262      * Version of {@link #dismiss()} that uses
    263      * {@link FragmentTransaction#commitAllowingStateLoss()
    264      * FragmentTransaction.commitAllowingStateLoss()}.  See linked
    265      * documentation for further details.
    266      */
    267     public void dismissAllowingStateLoss() {
    268         dismissInternal(true);
    269     }
    270 
    271     void dismissInternal(boolean allowStateLoss) {
    272         if (mDismissed) {
    273             return;
    274         }
    275         mDismissed = true;
    276         mShownByMe = false;
    277         if (mDialog != null) {
    278             mDialog.dismiss();
    279             mDialog = null;
    280         }
    281         mViewDestroyed = true;
    282         if (mBackStackId >= 0) {
    283             getFragmentManager().popBackStack(mBackStackId,
    284                     FragmentManager.POP_BACK_STACK_INCLUSIVE);
    285             mBackStackId = -1;
    286         } else {
    287             FragmentTransaction ft = getFragmentManager().beginTransaction();
    288             ft.remove(this);
    289             if (allowStateLoss) {
    290                 ft.commitAllowingStateLoss();
    291             } else {
    292                 ft.commit();
    293             }
    294         }
    295     }
    296 
    297     public Dialog getDialog() {
    298         return mDialog;
    299     }
    300 
    301     public int getTheme() {
    302         return mTheme;
    303     }
    304 
    305     /**
    306      * Control whether the shown Dialog is cancelable.  Use this instead of
    307      * directly calling {@link Dialog#setCancelable(boolean)
    308      * Dialog.setCancelable(boolean)}, because DialogFragment needs to change
    309      * its behavior based on this.
    310      *
    311      * @param cancelable If true, the dialog is cancelable.  The default
    312      * is true.
    313      */
    314     public void setCancelable(boolean cancelable) {
    315         mCancelable = cancelable;
    316         if (mDialog != null) mDialog.setCancelable(cancelable);
    317     }
    318 
    319     /**
    320      * Return the current value of {@link #setCancelable(boolean)}.
    321      */
    322     public boolean isCancelable() {
    323         return mCancelable;
    324     }
    325 
    326     /**
    327      * Controls whether this fragment should be shown in a dialog.  If not
    328      * set, no Dialog will be created in {@link #onActivityCreated(Bundle)},
    329      * and the fragment's view hierarchy will thus not be added to it.  This
    330      * allows you to instead use it as a normal fragment (embedded inside of
    331      * its activity).
    332      *
    333      * <p>This is normally set for you based on whether the fragment is
    334      * associated with a container view ID passed to
    335      * {@link FragmentTransaction#add(int, Fragment) FragmentTransaction.add(int, Fragment)}.
    336      * If the fragment was added with a container, setShowsDialog will be
    337      * initialized to false; otherwise, it will be true.
    338      *
    339      * @param showsDialog If true, the fragment will be displayed in a Dialog.
    340      * If false, no Dialog will be created and the fragment's view hierarchly
    341      * left undisturbed.
    342      */
    343     public void setShowsDialog(boolean showsDialog) {
    344         mShowsDialog = showsDialog;
    345     }
    346 
    347     /**
    348      * Return the current value of {@link #setShowsDialog(boolean)}.
    349      */
    350     public boolean getShowsDialog() {
    351         return mShowsDialog;
    352     }
    353 
    354     @Override
    355     public void onAttach(Activity activity) {
    356         super.onAttach(activity);
    357         if (!mShownByMe) {
    358             // If not explicitly shown through our API, take this as an
    359             // indication that the dialog is no longer dismissed.
    360             mDismissed = false;
    361         }
    362     }
    363 
    364     @Override
    365     public void onDetach() {
    366         super.onDetach();
    367         if (!mShownByMe && !mDismissed) {
    368             // The fragment was not shown by a direct call here, it is not
    369             // dismissed, and now it is being detached...  well, okay, thou
    370             // art now dismissed.  Have fun.
    371             mDismissed = true;
    372         }
    373     }
    374 
    375     @Override
    376     public void onCreate(Bundle savedInstanceState) {
    377         super.onCreate(savedInstanceState);
    378 
    379         mShowsDialog = mContainerId == 0;
    380 
    381         if (savedInstanceState != null) {
    382             mStyle = savedInstanceState.getInt(SAVED_STYLE, STYLE_NORMAL);
    383             mTheme = savedInstanceState.getInt(SAVED_THEME, 0);
    384             mCancelable = savedInstanceState.getBoolean(SAVED_CANCELABLE, true);
    385             mShowsDialog = savedInstanceState.getBoolean(SAVED_SHOWS_DIALOG, mShowsDialog);
    386             mBackStackId = savedInstanceState.getInt(SAVED_BACK_STACK_ID, -1);
    387         }
    388 
    389     }
    390 
    391     /** @hide */
    392     @Override
    393     public LayoutInflater getLayoutInflater(Bundle savedInstanceState) {
    394         if (!mShowsDialog) {
    395             return super.getLayoutInflater(savedInstanceState);
    396         }
    397 
    398         mDialog = onCreateDialog(savedInstanceState);
    399         switch (mStyle) {
    400             case STYLE_NO_INPUT:
    401                 mDialog.getWindow().addFlags(
    402                         WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE |
    403                         WindowManager.LayoutParams.FLAG_NOT_TOUCHABLE);
    404                 // fall through...
    405             case STYLE_NO_FRAME:
    406             case STYLE_NO_TITLE:
    407                 mDialog.requestWindowFeature(Window.FEATURE_NO_TITLE);
    408         }
    409         if (mDialog != null) {
    410             return (LayoutInflater)mDialog.getContext().getSystemService(
    411                     Context.LAYOUT_INFLATER_SERVICE);
    412         }
    413         return (LayoutInflater)mActivity.getSystemService(
    414                 Context.LAYOUT_INFLATER_SERVICE);
    415     }
    416 
    417     /**
    418      * Override to build your own custom Dialog container.  This is typically
    419      * used to show an AlertDialog instead of a generic Dialog; when doing so,
    420      * {@link #onCreateView(LayoutInflater, ViewGroup, Bundle)} does not need
    421      * to be implemented since the AlertDialog takes care of its own content.
    422      *
    423      * <p>This method will be called after {@link #onCreate(Bundle)} and
    424      * before {@link #onCreateView(LayoutInflater, ViewGroup, Bundle)}.  The
    425      * default implementation simply instantiates and returns a {@link Dialog}
    426      * class.
    427      *
    428      * <p><em>Note: DialogFragment own the {@link Dialog#setOnCancelListener
    429      * Dialog.setOnCancelListener} and {@link Dialog#setOnDismissListener
    430      * Dialog.setOnDismissListener} callbacks.  You must not set them yourself.</em>
    431      * To find out about these events, override {@link #onCancel(DialogInterface)}
    432      * and {@link #onDismiss(DialogInterface)}.</p>
    433      *
    434      * @param savedInstanceState The last saved instance state of the Fragment,
    435      * or null if this is a freshly created Fragment.
    436      *
    437      * @return Return a new Dialog instance to be displayed by the Fragment.
    438      */
    439     public Dialog onCreateDialog(Bundle savedInstanceState) {
    440         return new Dialog(getActivity(), getTheme());
    441     }
    442 
    443     public void onCancel(DialogInterface dialog) {
    444     }
    445 
    446     public void onDismiss(DialogInterface dialog) {
    447         if (!mViewDestroyed) {
    448             // Note: we need to use allowStateLoss, because the dialog
    449             // dispatches this asynchronously so we can receive the call
    450             // after the activity is paused.  Worst case, when the user comes
    451             // back to the activity they see the dialog again.
    452             dismissInternal(true);
    453         }
    454     }
    455 
    456     @Override
    457     public void onActivityCreated(Bundle savedInstanceState) {
    458         super.onActivityCreated(savedInstanceState);
    459 
    460         if (!mShowsDialog) {
    461             return;
    462         }
    463 
    464         View view = getView();
    465         if (view != null) {
    466             if (view.getParent() != null) {
    467                 throw new IllegalStateException("DialogFragment can not be attached to a container view");
    468             }
    469             mDialog.setContentView(view);
    470         }
    471         mDialog.setOwnerActivity(getActivity());
    472         mDialog.setCancelable(mCancelable);
    473         if (!mDialog.takeCancelAndDismissListeners("DialogFragment", this, this)) {
    474             throw new IllegalStateException(
    475                     "You can not set Dialog's OnCancelListener or OnDismissListener");
    476         }
    477         if (savedInstanceState != null) {
    478             Bundle dialogState = savedInstanceState.getBundle(SAVED_DIALOG_STATE_TAG);
    479             if (dialogState != null) {
    480                 mDialog.onRestoreInstanceState(dialogState);
    481             }
    482         }
    483     }
    484 
    485     @Override
    486     public void onStart() {
    487         super.onStart();
    488         if (mDialog != null) {
    489             mViewDestroyed = false;
    490             mDialog.show();
    491         }
    492     }
    493 
    494     @Override
    495     public void onSaveInstanceState(Bundle outState) {
    496         super.onSaveInstanceState(outState);
    497         if (mDialog != null) {
    498             Bundle dialogState = mDialog.onSaveInstanceState();
    499             if (dialogState != null) {
    500                 outState.putBundle(SAVED_DIALOG_STATE_TAG, dialogState);
    501             }
    502         }
    503         if (mStyle != STYLE_NORMAL) {
    504             outState.putInt(SAVED_STYLE, mStyle);
    505         }
    506         if (mTheme != 0) {
    507             outState.putInt(SAVED_THEME, mTheme);
    508         }
    509         if (!mCancelable) {
    510             outState.putBoolean(SAVED_CANCELABLE, mCancelable);
    511         }
    512         if (!mShowsDialog) {
    513             outState.putBoolean(SAVED_SHOWS_DIALOG, mShowsDialog);
    514         }
    515         if (mBackStackId != -1) {
    516             outState.putInt(SAVED_BACK_STACK_ID, mBackStackId);
    517         }
    518     }
    519 
    520     @Override
    521     public void onStop() {
    522         super.onStop();
    523         if (mDialog != null) {
    524             mDialog.hide();
    525         }
    526     }
    527 
    528     /**
    529      * Remove dialog.
    530      */
    531     @Override
    532     public void onDestroyView() {
    533         super.onDestroyView();
    534         if (mDialog != null) {
    535             // Set removed here because this dismissal is just to hide
    536             // the dialog -- we don't want this to cause the fragment to
    537             // actually be removed.
    538             mViewDestroyed = true;
    539             mDialog.dismiss();
    540             mDialog = null;
    541         }
    542     }
    543 
    544     @Override
    545     public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) {
    546         super.dump(prefix, fd, writer, args);
    547         writer.print(prefix); writer.println("DialogFragment:");
    548         writer.print(prefix); writer.print("  mStyle="); writer.print(mStyle);
    549                 writer.print(" mTheme=0x"); writer.println(Integer.toHexString(mTheme));
    550         writer.print(prefix); writer.print("  mCancelable="); writer.print(mCancelable);
    551                 writer.print(" mShowsDialog="); writer.print(mShowsDialog);
    552                 writer.print(" mBackStackId="); writer.println(mBackStackId);
    553         writer.print(prefix); writer.print("  mDialog="); writer.println(mDialog);
    554         writer.print(prefix); writer.print("  mViewDestroyed="); writer.print(mViewDestroyed);
    555                 writer.print(" mDismissed="); writer.print(mDismissed);
    556                 writer.print(" mShownByMe="); writer.println(mShownByMe);
    557     }
    558 }
    559