Added in API level 11
Deprecated in API level 28

DialogFragment


open class DialogFragment : Fragment, DialogInterface.OnCancelListener, DialogInterface.OnDismissListener
kotlin.Any
   ↳ android.app.Fragment
   ↳ android.app.DialogFragment

A fragment that displays a dialog window, floating on top of its activity's window. This fragment contains a Dialog object, which it displays as appropriate based on the fragment's state. Control of the dialog (deciding when to show, hide, dismiss it) should be done through the API here, not with direct calls on the dialog.

Implementations should override this class and implement onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle) to supply the content of the dialog. Alternatively, they can override onCreateDialog(android.os.Bundle) to create an entirely custom dialog, such as an AlertDialog, with its own content.

Topics covered here:

  1. Lifecycle
  2. Basic Dialog
  3. Alert Dialog
  4. Selecting Between Dialog or Embedding

Lifecycle

DialogFragment does various things to keep the fragment's lifecycle driving it, instead of the Dialog. Note that dialogs are generally autonomous entities -- they are their own window, receiving their own input events, and often deciding on their own when to disappear (by receiving a back key event or the user clicking on a button).

DialogFragment needs to ensure that what is happening with the Fragment and Dialog states remains consistent. To do this, it watches for dismiss events from the dialog and takes care of removing its own state when they happen. This means you should use show(android.app.FragmentManager,java.lang.String) or show(android.app.FragmentTransaction,java.lang.String) to add an instance of DialogFragment to your UI, as these keep track of how DialogFragment should remove itself when the dialog is dismissed.

Basic Dialog

The simplest use of DialogFragment is as a floating container for the fragment's view hierarchy. A simple implementation may look like this:

An example showDialog() method on the Activity could be:

This removes any currently shown dialog, creates a new DialogFragment with an argument, and shows it as a new state on the back stack. When the transaction is popped, the current DialogFragment and its Dialog will be destroyed, and the previous one (if any) re-shown. Note that in this case DialogFragment will take care of popping the transaction of the Dialog is dismissed separately from it.

Alert Dialog

Instead of (or in addition to) implementing onCreateView to generate the view hierarchy inside of a dialog, you may implement onCreateDialog(android.os.Bundle) to create your own custom Dialog object.

This is most useful for creating an AlertDialog, allowing you to display standard alerts to the user that are managed by a fragment. A simple example implementation of this is:

The activity creating this fragment may have the following methods to show the dialog and receive results from it:

Note that in this case the fragment is not placed on the back stack, it is just added as an indefinitely running fragment. Because dialogs normally are modal, this will still operate as a back stack, since the dialog will capture user input until it is dismissed. When it is dismissed, DialogFragment will take care of removing itself from its fragment manager.

Selecting Between Dialog or Embedding

A DialogFragment can still optionally be used as a normal fragment, if desired. This is useful if you have a fragment that in some cases should be shown as a dialog and others embedded in a larger UI. This behavior will normally be automatically selected for you based on how you are using the fragment, but can be customized with setShowsDialog(boolean).

For example, here is a simple dialog fragment:

An instance of this fragment can be created and shown as a dialog:

It can also be added as content in a view hierarchy:

Summary

Constants
static Int

Style for setStyle(int,int): a basic, normal dialog.

static Int

Style for setStyle(int,int): don't draw any frame at all; the view hierarchy returned by onCreateView is entirely responsible for drawing the dialog.

static Int

Style for setStyle(int,int): like STYLE_NO_FRAME, but also disables all input to the dialog.

static Int

Style for setStyle(int,int): don't include a title area.

Inherited constants
Public constructors

Public methods
open Unit

Dismiss the fragment and its dialog.

open Unit

Version of dismiss() that uses FragmentTransaction.commitAllowingStateLoss().

open Unit
dump(prefix: String!, fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)

open Dialog!

open Boolean

Return the current value of setShowsDialog(boolean).

open Int

open Boolean

Return the current value of setCancelable(boolean).

open Unit
onActivityCreated(savedInstanceState: Bundle?)

open Unit
onAttach(context: Context!)

open Unit

open Unit
onCreate(savedInstanceState: Bundle?)

open Dialog!
onCreateDialog(savedInstanceState: Bundle!)

Override to build your own custom Dialog container.

open Unit

Remove dialog.

open Unit

open Unit

open Unit

open Unit

open Unit

open Unit
setCancelable(cancelable: Boolean)

Control whether the shown Dialog is cancelable.

open Unit
setShowsDialog(showsDialog: Boolean)

Controls whether this fragment should be shown in a dialog.

open Unit
setStyle(style: Int, theme: Int)

Call to customize the basic appearance and behavior of the fragment's dialog.

open Unit
show(manager: FragmentManager!, tag: String!)

Display the dialog, adding the fragment to the given FragmentManager.

open Int
show(transaction: FragmentTransaction!, tag: String!)

Display the dialog, adding the fragment using an existing transaction and then committing the transaction.

Inherited functions

Constants

STYLE_NORMAL

Added in API level 11
static val STYLE_NORMAL: Int

Deprecated: Deprecated in Java.

Style for setStyle(int,int): a basic, normal dialog.

Value: 0

STYLE_NO_FRAME

Added in API level 11
static val STYLE_NO_FRAME: Int

Deprecated: Deprecated in Java.

Style for setStyle(int,int): don't draw any frame at all; the view hierarchy returned by onCreateView is entirely responsible for drawing the dialog.

Value: 2

STYLE_NO_INPUT

Added in API level 11
static val STYLE_NO_INPUT: Int

Deprecated: Deprecated in Java.

Style for setStyle(int,int): like STYLE_NO_FRAME, but also disables all input to the dialog. The user can not touch it, and its window will not receive input focus.

Value: 3

STYLE_NO_TITLE

Added in API level 11
static val STYLE_NO_TITLE: Int

Deprecated: Deprecated in Java.

Style for setStyle(int,int): don't include a title area.

Value: 1

Public constructors

DialogFragment

Added in API level 11
DialogFragment()

Public methods

dismiss

Added in API level 11
open fun dismiss(): Unit

Deprecated: Deprecated in Java.

Dismiss the fragment and its dialog. If the fragment was added to the back stack, all back stack state up to and including this entry will be popped. Otherwise, a new transaction will be committed to remove the fragment.

dismissAllowingStateLoss

Added in API level 12
Deprecated in API level 28
open fun dismissAllowingStateLoss(): Unit

Deprecated: Deprecated in Java.

Version of dismiss() that uses FragmentTransaction.commitAllowingStateLoss(). See linked documentation for further details.

dump

Added in API level 11
open fun dump(
    prefix: String!,
    fd: FileDescriptor!,
    writer: PrintWriter!,
    args: Array<String!>!
): Unit

Deprecated: Deprecated in Java.

Parameters
prefix String!: Text to print at the front of each line.
fd FileDescriptor!: The raw file descriptor that the dump is being sent to.
writer PrintWriter!: The PrintWriter to which you should dump your state. This will be closed for you after you return.
args Array<String!>!: additional arguments to the dump request.

getDialog

Added in API level 11
open fun getDialog(): Dialog!

Deprecated: Deprecated in Java.

getShowsDialog

Added in API level 11
open fun getShowsDialog(): Boolean

Deprecated: Deprecated in Java.

Return the current value of setShowsDialog(boolean).

getTheme

Added in API level 11
open fun getTheme(): Int

Deprecated: Deprecated in Java.

isCancelable

Added in API level 11
open fun isCancelable(): Boolean

Deprecated: Deprecated in Java.

Return the current value of setCancelable(boolean).

onActivityCreated

Added in API level 11
open fun onActivityCreated(savedInstanceState: Bundle?): Unit

Deprecated: Deprecated in Java.

Parameters
savedInstanceState Bundle?: If the fragment is being re-created from a previous saved state, this is the state. This value may be null.

onAttach

Added in API level 23
Deprecated in API level 28
open fun onAttach(context: Context!): Unit

Deprecated: Deprecated in Java.

onCancel

Added in API level 11
open fun onCancel(dialog: DialogInterface!): Unit

Deprecated: Deprecated in Java.

Parameters
dialog DialogInterface!: the dialog that was canceled will be passed into the method

onCreate

Added in API level 11
open fun onCreate(savedInstanceState: Bundle?): Unit

Deprecated: Deprecated in Java.

Parameters
savedInstanceState Bundle?: If the fragment is being re-created from a previous saved state, this is the state. This value may be null.

onCreateDialog

Added in API level 11
open fun onCreateDialog(savedInstanceState: Bundle!): Dialog!

Deprecated: Deprecated in Java.

Override to build your own custom Dialog container. This is typically used to show an AlertDialog instead of a generic Dialog; when doing so, onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle) does not need to be implemented since the AlertDialog takes care of its own content.

This method will be called after onCreate(android.os.Bundle) and before onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle). The default implementation simply instantiates and returns a Dialog class.

Note: DialogFragment own the Dialog.setOnCancelListener and Dialog.setOnDismissListener callbacks. You must not set them yourself. To find out about these events, override onCancel(android.content.DialogInterface) and onDismiss(android.content.DialogInterface).

Parameters
savedInstanceState Bundle!: The last saved instance state of the Fragment, or null if this is a freshly created Fragment.
Return
Dialog! Return a new Dialog instance to be displayed by the Fragment.

onDestroyView

Added in API level 11
open fun onDestroyView(): Unit

Deprecated: Deprecated in Java.

Remove dialog.

onDetach

Added in API level 11
open fun onDetach(): Unit

Deprecated: Deprecated in Java.

onDismiss

Added in API level 11
open fun onDismiss(dialog: DialogInterface!): Unit

Deprecated: Deprecated in Java.

Parameters
dialog DialogInterface!: the dialog that was dismissed will be passed into the method

onSaveInstanceState

Added in API level 11
open fun onSaveInstanceState(outState: Bundle!): Unit

Deprecated: Deprecated in Java.

Parameters
outState Bundle!: Bundle in which to place your saved state.

onStart

Added in API level 11
open fun onStart(): Unit

Deprecated: Deprecated in Java.

onStop

Added in API level 11
open fun onStop(): Unit

Deprecated: Deprecated in Java.

setCancelable

Added in API level 11
open fun setCancelable(cancelable: Boolean): Unit

Deprecated: Deprecated in Java.

Control whether the shown Dialog is cancelable. Use this instead of directly calling Dialog.setCancelable(boolean), because DialogFragment needs to change its behavior based on this.

Parameters
cancelable Boolean: If true, the dialog is cancelable. The default is true.

setShowsDialog

Added in API level 11
open fun setShowsDialog(showsDialog: Boolean): Unit

Deprecated: Deprecated in Java.

Controls whether this fragment should be shown in a dialog. If not set, no Dialog will be created in onActivityCreated(android.os.Bundle), and the fragment's view hierarchy will thus not be added to it. This allows you to instead use it as a normal fragment (embedded inside of its activity).

This is normally set for you based on whether the fragment is associated with a container view ID passed to FragmentTransaction.add(int, Fragment). If the fragment was added with a container, setShowsDialog will be initialized to false; otherwise, it will be true.

Parameters
showsDialog Boolean: If true, the fragment will be displayed in a Dialog. If false, no Dialog will be created and the fragment's view hierarchly left undisturbed.

setStyle

Added in API level 11
open fun setStyle(
    style: Int,
    theme: Int
): Unit

Deprecated: Deprecated in Java.

Call to customize the basic appearance and behavior of the fragment's dialog. This can be used for some common dialog behaviors, taking care of selecting flags, theme, and other options for you. The same effect can be achieve by manually setting Dialog and Window attributes yourself. Calling this after the fragment's Dialog is created will have no effect.

Parameters
style Int: Selects a standard style: may be STYLE_NORMAL, STYLE_NO_TITLE, STYLE_NO_FRAME, or STYLE_NO_INPUT.
theme Int: Optional custom theme. If 0, an appropriate theme (based on the style) will be selected for you.

show

Added in API level 11
open fun show(
    manager: FragmentManager!,
    tag: String!
): Unit

Deprecated: Deprecated in Java.

Display the dialog, adding the fragment to the given FragmentManager. This is a convenience for explicitly creating a transaction, adding the fragment to it with the given tag, and committing it. This does not add the transaction to the back stack. When the fragment is dismissed, a new transaction will be executed to remove it from the activity.

Parameters
manager FragmentManager!: The FragmentManager this fragment will be added to.
tag String!: The tag for this fragment, as per FragmentTransaction.add.

show

Added in API level 11
open fun show(
    transaction: FragmentTransaction!,
    tag: String!
): Int

Deprecated: Deprecated in Java.

Display the dialog, adding the fragment using an existing transaction and then committing the transaction.

Parameters
transaction FragmentTransaction!: An existing transaction in which to add the fragment.
tag String!: The tag for this fragment, as per FragmentTransaction.add.
Return
Int Returns the identifier of the committed transaction, as per FragmentTransaction.commit().