java.lang.Object
   ↳ android.app.Dialog
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Base class for Dialogs.

Note: Activities provide a facility to manage the creation, saving and restoring of dialogs. See onCreateDialog(int), onPrepareDialog(int, Dialog), showDialog(int), and dismissDialog(int). If these methods are used, getOwnerActivity() will return the Activity that managed this dialog.

Often you will want to have a Dialog display on top of the current input method, because there is no reason for it to accept text. You can do this by setting the WindowManager.LayoutParams.FLAG_ALT_FOCUSABLE_IM window flag (assuming your Dialog takes input focus, as it the default) with the following code:

     getWindow().setFlags(WindowManager.LayoutParams.FLAG_ALT_FOCUSABLE_IM,
             WindowManager.LayoutParams.FLAG_ALT_FOCUSABLE_IM);
 

Summary

[Expand]
Inherited Constants
From interface android.content.DialogInterface
Public Constructors
Dialog(Context context)
Create a Dialog window that uses the default dialog frame style.
Dialog(Context context, int theme)
Create a Dialog window that uses a custom dialog style.
Protected Constructors
Dialog(Context context, boolean cancelable, DialogInterface.OnCancelListener cancelListener)
Public Methods
void addContentView(View view, ViewGroup.LayoutParams params)
Add an additional content view to the screen.
void cancel()
Cancel the dialog.
void closeOptionsMenu()
void dismiss()
Dismiss this dialog, removing it from the screen.
boolean dispatchKeyEvent(KeyEvent event)
Called to process key events.
boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event)
Called to process population of AccessibilityEvents.
boolean dispatchTouchEvent(MotionEvent ev)
Called to process touch screen events.
boolean dispatchTrackballEvent(MotionEvent ev)
Called to process trackball events.
View findViewById(int id)
Finds a view that was identified by the id attribute from the XML that was processed in onStart().
final Context getContext()
Retrieve the Context this Dialog is running in.
View getCurrentFocus()
Call getCurrentFocus() on the Window if this Activity to return the currently focused view.
LayoutInflater getLayoutInflater()
final Activity getOwnerActivity()
Returns the Activity that owns this Dialog.
final int getVolumeControlStream()
Window getWindow()
Retrieve the current Window for the activity.
void hide()
Hide the dialog, but do not dismiss it.
boolean isShowing()
void onAttachedToWindow()
Called when the window has been attached to the window manager.
void onBackPressed()
Called when the dialog has detected the user's press of the back key.
void onContentChanged()
This hook is called whenever the content view of the screen changes (due to a call to Window.setContentView or Window.addContentView).
boolean onContextItemSelected(MenuItem item)
void onContextMenuClosed(Menu menu)
void onCreateContextMenu(ContextMenu menu, View v, ContextMenu.ContextMenuInfo menuInfo)
Called when the context menu for this view is being built.
boolean onCreateOptionsMenu(Menu menu)
It is usually safe to proxy this call to the owner activity's onCreateOptionsMenu(Menu) if the client desires the same menu for this Dialog.
boolean onCreatePanelMenu(int featureId, Menu menu)
Initialize the contents of the menu for panel 'featureId'.
View onCreatePanelView(int featureId)
Instantiate the view to display in the panel for 'featureId'.
void onDetachedFromWindow()
Called when the window has been attached to the window manager.
boolean onKeyDown(int keyCode, KeyEvent event)
A key was pressed down.
boolean onKeyLongPress(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyLongPress(): always returns false (doesn't handle the event).
boolean onKeyMultiple(int keyCode, int repeatCount, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyMultiple(): always returns false (doesn't handle the event).
boolean onKeyUp(int keyCode, KeyEvent event)
A key was released.
boolean onMenuItemSelected(int featureId, MenuItem item)
Called when a panel's menu item has been selected by the user.
boolean onMenuOpened(int featureId, Menu menu)
Called when a panel's menu is opened by the user.
boolean onOptionsItemSelected(MenuItem item)
void onOptionsMenuClosed(Menu menu)
void onPanelClosed(int featureId, Menu menu)
Called when a panel is being closed.
boolean onPrepareOptionsMenu(Menu menu)
It is usually safe to proxy this call to the owner activity's onPrepareOptionsMenu(Menu) if the client desires the same menu for this Dialog.
boolean onPreparePanel(int featureId, View view, Menu menu)
Prepare a panel to be displayed.
void onRestoreInstanceState(Bundle savedInstanceState)
Restore the state of the dialog from a previously saved bundle.
Bundle onSaveInstanceState()
Saves the state of the dialog into a bundle.
boolean onSearchRequested()
This hook is called when the user signals the desire to start a search.
boolean onTouchEvent(MotionEvent event)
Called when a touch screen event was not handled by any of the views under it.
boolean onTrackballEvent(MotionEvent event)
Called when the trackball was moved and not handled by any of the views inside of the activity.
void onWindowAttributesChanged(WindowManager.LayoutParams params)
This is called whenever the current window attributes change.
void onWindowFocusChanged(boolean hasFocus)
This hook is called whenever the window focus changes.
void openContextMenu(View view)
void openOptionsMenu()
void registerForContextMenu(View view)
final boolean requestWindowFeature(int featureId)
Enable extended window features.
void setCancelMessage(Message msg)
Set a message to be sent when the dialog is canceled.
void setCancelable(boolean flag)
Sets whether this dialog is cancelable with the BACK key.
void setCanceledOnTouchOutside(boolean cancel)
Sets whether this dialog is canceled when touched outside the window's bounds.
void setContentView(View view, ViewGroup.LayoutParams params)
Set the screen content to an explicit view.
void setContentView(View view)
Set the screen content to an explicit view.
void setContentView(int layoutResID)
Set the screen content from a layout resource.
void setDismissMessage(Message msg)
Set a message to be sent when the dialog is dismissed.
final void setFeatureDrawable(int featureId, Drawable drawable)
Convenience for calling setFeatureDrawable(int, Drawable).
final void setFeatureDrawableAlpha(int featureId, int alpha)
Convenience for calling setFeatureDrawableAlpha(int, int).
final void setFeatureDrawableResource(int featureId, int resId)
Convenience for calling setFeatureDrawableResource(int, int).
final void setFeatureDrawableUri(int featureId, Uri uri)
Convenience for calling setFeatureDrawableUri(int, Uri).
void setOnCancelListener(DialogInterface.OnCancelListener listener)
Set a listener to be invoked when the dialog is canceled.
void setOnDismissListener(DialogInterface.OnDismissListener listener)
Set a listener to be invoked when the dialog is dismissed.
void setOnKeyListener(DialogInterface.OnKeyListener onKeyListener)
Sets the callback that will be called if a key is dispatched to the dialog.
final void setOwnerActivity(Activity activity)
Sets the Activity that owns this dialog.
void setTitle(int titleId)
Set the title text for this dialog's window.
void setTitle(CharSequence title)
Set the title text for this dialog's window.
final void setVolumeControlStream(int streamType)
By default, this will use the owner Activity's suggested stream type.
void show()
Start the dialog and display it on screen.
void takeKeyEvents(boolean get)
Request that key events come to this dialog.
void unregisterForContextMenu(View view)
Protected Methods
void onCreate(Bundle savedInstanceState)
Similar to onCreate(Bundle), you should initialized your dialog in this method, including calling setContentView(View).
void onStart()
Called when the dialog is starting.
void onStop()
Called to tell you that you're stopping.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.content.DialogInterface
From interface android.view.KeyEvent.Callback
From interface android.view.View.OnCreateContextMenuListener
From interface android.view.Window.Callback

Public Constructors

public Dialog (Context context)

Since: API Level 1

Create a Dialog window that uses the default dialog frame style.

Parameters
context The Context the Dialog is to run it. In particular, it uses the window manager and theme in this context to present its UI.

public Dialog (Context context, int theme)

Since: API Level 1

Create a Dialog window that uses a custom dialog style.

Parameters
context The Context in which the Dialog should run. In particular, it uses the window manager and theme from this context to present its UI.
theme A style resource describing the theme to use for the window. See Style and Theme Resources for more information about defining and using styles. This theme is applied on top of the current theme in context. If 0, the default dialog theme will be used.

Protected Constructors

protected Dialog (Context context, boolean cancelable, DialogInterface.OnCancelListener cancelListener)

Since: API Level 1

Public Methods

public void addContentView (View view, ViewGroup.LayoutParams params)

Since: API Level 1

Add an additional content view to the screen. Added after any existing ones in the screen -- existing views are NOT removed.

Parameters
view The desired content to display.
params Layout parameters for the view.

public void cancel ()

Since: API Level 1

Cancel the dialog. This is essentially the same as calling dismiss(), but it will also call your DialogInterface.OnCancelListener (if registered).

public void closeOptionsMenu ()

Since: API Level 1

public void dismiss ()

Since: API Level 1

Dismiss this dialog, removing it from the screen. This method can be invoked safely from any thread. Note that you should not override this method to do cleanup when the dialog is dismissed, instead implement that in onStop().

public boolean dispatchKeyEvent (KeyEvent event)

Since: API Level 1

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.

Parameters
event The key event.
Returns
  • boolean Return true if this event was consumed.

public boolean dispatchPopulateAccessibilityEvent (AccessibilityEvent event)

Since: API Level 4

Called to process population of AccessibilityEvents.

Parameters
event The event.
Returns
  • boolean Return true if event population was completed.

public boolean dispatchTouchEvent (MotionEvent ev)

Since: API Level 1

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.

Parameters
ev The touch screen event.
Returns
  • boolean Return true if this event was consumed.

public boolean dispatchTrackballEvent (MotionEvent ev)

Since: API Level 1

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.

Parameters
ev The trackball event.
Returns
  • boolean Return true if this event was consumed.

public View findViewById (int id)

Since: API Level 1

Finds a view that was identified by the id attribute from the XML that was processed in onStart().

Parameters
id the identifier of the view to find
Returns
  • The view if found or null otherwise.

public final Context getContext ()

Since: API Level 1

Retrieve the Context this Dialog is running in.

Returns
  • Context The Context that was supplied to the constructor.

public View getCurrentFocus ()

Since: API Level 1

Call getCurrentFocus() on the Window if this Activity to return the currently focused view.

Returns
  • View The current View with focus or null.

public LayoutInflater getLayoutInflater ()

Since: API Level 1

public final Activity getOwnerActivity ()

Since: API Level 1

Returns the Activity that owns this Dialog. For example, if showDialog(int) is used to show this Dialog, that Activity will be the owner (by default). Depending on how this dialog was created, this may return null.

Returns
  • The Activity that owns this Dialog.

public final int getVolumeControlStream ()

Since: API Level 1

public Window getWindow ()

Since: API Level 1

Retrieve the current Window for the activity. This can be used to directly access parts of the Window API that are not available through Activity/Screen.

Returns
  • Window The current window, or null if the activity is not visual.

public void hide ()

Since: API Level 1

Hide the dialog, but do not dismiss it.

public boolean isShowing ()

Since: API Level 1

Returns
  • Whether the dialog is currently showing.

public void onAttachedToWindow ()

Since: API Level 5

Called when the window has been attached to the window manager. See View.onAttachedToWindow() for more information.

public void onBackPressed ()

Since: API Level 5

Called when the dialog has detected the user's press of the back key. The default implementation simply cancels the dialog (only if it is cancelable), but you can override this to do whatever you want.

public void onContentChanged ()

Since: API Level 1

This hook is called whenever the content view of the screen changes (due to a call to Window.setContentView or Window.addContentView).

public boolean onContextItemSelected (MenuItem item)

Since: API Level 1

public void onContextMenuClosed (Menu menu)

Since: API Level 1

public void onCreateContextMenu (ContextMenu menu, View v, ContextMenu.ContextMenuInfo menuInfo)

Since: API Level 1

Called when the context menu for this view is being built. It is not safe to hold onto the menu after this method returns.

Parameters
menu The context menu that is being built
v The view for which the context menu is being built
menuInfo Extra information about the item for which the context menu should be shown. This information will vary depending on the class of v.

public boolean onCreateOptionsMenu (Menu menu)

Since: API Level 1

It is usually safe to proxy this call to the owner activity's onCreateOptionsMenu(Menu) if the client desires the same menu for this Dialog.

public boolean onCreatePanelMenu (int featureId, Menu menu)

Since: API Level 1

Initialize the contents of the menu for panel 'featureId'. This is called if onCreatePanelView() returns null, giving you a standard menu in which you can place your items. It is only called once for the panel, the first time it is shown.

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

Parameters
featureId The panel being created.
menu The menu inside the panel.
Returns
  • boolean You must return true for the panel to be displayed; if you return false it will not be shown.

public View onCreatePanelView (int featureId)

Since: API Level 1

Instantiate the view to display in the panel for 'featureId'. You can return null, in which case the default content (typically a menu) will be created for you.

Parameters
featureId Which panel is being created.
Returns
  • view The top-level view to place in the panel.

public void onDetachedFromWindow ()

Since: API Level 5

Called when the window has been attached to the window manager. See View.onDetachedFromWindow() for more information.

public boolean onKeyDown (int keyCode, KeyEvent event)

Since: API Level 1

A key was pressed down.

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

The default implementation consumed the KEYCODE_BACK to later handle it in onKeyUp(int, KeyEvent).

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyLongPress (int keyCode, KeyEvent event)

Since: API Level 5

Default implementation of KeyEvent.Callback.onKeyLongPress(): always returns false (doesn't handle the event).

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyMultiple (int keyCode, int repeatCount, KeyEvent event)

Since: API Level 1

Default implementation of KeyEvent.Callback.onKeyMultiple(): always returns false (doesn't handle the event).

Parameters
keyCode The value in event.getKeyCode().
repeatCount Number of pairs as returned by event.getRepeatCount().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyUp (int keyCode, KeyEvent event)

Since: API Level 1

A key was released.

The default implementation handles KEYCODE_BACK to close the dialog.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onMenuItemSelected (int featureId, MenuItem item)

Since: API Level 1

Called when a panel's menu item has been selected by the user.

Parameters
featureId The panel that the menu is in.
item The menu item that was selected.
Returns
  • boolean Return true to finish processing of selection, or false to perform the normal menu handling (calling its Runnable or sending a Message to its target Handler).

public boolean onMenuOpened (int featureId, Menu menu)

Since: API Level 1

Called when a panel's menu is opened by the user. This may also be called when the menu is changing from one type to another (for example, from the icon menu to the expanded menu).

Parameters
featureId The panel that the menu is in.
menu The menu that is opened.
Returns
  • Return true to allow the menu to open, or false to prevent the menu from opening.

public boolean onOptionsItemSelected (MenuItem item)

Since: API Level 1

public void onOptionsMenuClosed (Menu menu)

Since: API Level 1

public void onPanelClosed (int featureId, Menu menu)

Since: API Level 1

Called when a panel is being closed. If another logical subsequent panel is being opened (and this panel is being closed to make room for the subsequent panel), this method will NOT be called.

Parameters
featureId The panel that is being displayed.
menu If onCreatePanelView() returned null, this is the Menu being displayed in the panel.

public boolean onPrepareOptionsMenu (Menu menu)

Since: API Level 1

It is usually safe to proxy this call to the owner activity's onPrepareOptionsMenu(Menu) if the client desires the same menu for this Dialog.

public boolean onPreparePanel (int featureId, View view, Menu menu)

Since: API Level 1

Prepare a panel to be displayed. This is called right before the panel window is shown, every time it is shown.

Parameters
featureId The panel that is being displayed.
view The View that was returned by onCreatePanelView().
menu If onCreatePanelView() returned null, this is the Menu being displayed in the panel.
Returns
  • boolean You must return true for the panel to be displayed; if you return false it will not be shown.

public void onRestoreInstanceState (Bundle savedInstanceState)

Since: API Level 1

Restore the state of the dialog from a previously saved bundle. The default implementation restores the state of the dialog's view hierarchy that was saved in the default implementation of onSaveInstanceState(), so be sure to call through to super when overriding unless you want to do all restoring of state yourself.

Parameters
savedInstanceState The state of the dialog previously saved by onSaveInstanceState().

public Bundle onSaveInstanceState ()

Since: API Level 1

Saves the state of the dialog into a bundle. The default implementation saves the state of its view hierarchy, so you'll likely want to call through to super if you override this to save additional state.

Returns
  • A bundle with the state of the dialog.

public boolean onSearchRequested ()

Since: API Level 1

This hook is called when the user signals the desire to start a search.

Returns
  • true if search launched, false if activity refuses (blocks)

public boolean onTouchEvent (MotionEvent event)

Since: API Level 1

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.

Parameters
event The touch screen event being processed.
Returns
  • Return true if you have consumed the event, false if you haven't. The default implementation will cancel the dialog when a touch happens outside of the window bounds.

public boolean onTrackballEvent (MotionEvent event)

Since: API Level 1

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.

Parameters
event The trackball event being processed.
Returns
  • Return true if you have consumed the event, false if you haven't. The default implementation always returns false.

public void onWindowAttributesChanged (WindowManager.LayoutParams params)

Since: API Level 1

This is called whenever the current window attributes change.

public void onWindowFocusChanged (boolean hasFocus)

Since: API Level 1

This hook is called whenever the window focus changes. See View.onWindowFocusChanged(boolean) for more information.

Parameters
hasFocus Whether the window now has focus.

public void openContextMenu (View view)

Since: API Level 1

public void openOptionsMenu ()

Since: API Level 1

public void registerForContextMenu (View view)

Since: API Level 1

public final boolean requestWindowFeature (int featureId)

Since: API Level 1

Enable extended window features. This is a convenience for calling getWindow().requestFeature().

Parameters
featureId The desired feature as defined in Window.
Returns
  • Returns true if the requested feature is supported and now enabled.

public void setCancelMessage (Message msg)

Since: API Level 1

Set a message to be sent when the dialog is canceled.

Parameters
msg The msg to send when the dialog is canceled.

public void setCancelable (boolean flag)

Since: API Level 1

Sets whether this dialog is cancelable with the BACK key.

public void setCanceledOnTouchOutside (boolean cancel)

Since: API Level 1

Sets whether this dialog is canceled when touched outside the window's bounds. If setting to true, the dialog is set to be cancelable if not already set.

Parameters
cancel Whether the dialog should be canceled when touched outside the window.

public void setContentView (View view, ViewGroup.LayoutParams params)

Since: API Level 1

Set the screen content to an explicit view. This view is placed directly into the screen's view hierarchy. It can itself be a complex view hierarhcy.

Parameters
view The desired content to display.
params Layout parameters for the view.

public void setContentView (View view)

Since: API Level 1

Set the screen content to an explicit view. This view is placed directly into the screen's view hierarchy. It can itself be a complex view hierarhcy.

Parameters
view The desired content to display.

public void setContentView (int layoutResID)

Since: API Level 1

Set the screen content from a layout resource. The resource will be inflated, adding all top-level views to the screen.

Parameters
layoutResID Resource ID to be inflated.

public void setDismissMessage (Message msg)

Since: API Level 1

Set a message to be sent when the dialog is dismissed.

Parameters
msg The msg to send when the dialog is dismissed.

public final void setFeatureDrawable (int featureId, Drawable drawable)

Since: API Level 1

Convenience for calling setFeatureDrawable(int, Drawable).

public final void setFeatureDrawableAlpha (int featureId, int alpha)

Since: API Level 1

Convenience for calling setFeatureDrawableAlpha(int, int).

public final void setFeatureDrawableResource (int featureId, int resId)

Since: API Level 1

Convenience for calling setFeatureDrawableResource(int, int).

public final void setFeatureDrawableUri (int featureId, Uri uri)

Since: API Level 1

Convenience for calling setFeatureDrawableUri(int, Uri).

public void setOnCancelListener (DialogInterface.OnCancelListener listener)

Since: API Level 1

Set a listener to be invoked when the dialog is canceled.

This will only be invoked when the dialog is canceled, if the creator needs to know when it is dismissed in general, use setOnDismissListener(DialogInterface.OnDismissListener).

Parameters
listener The DialogInterface.OnCancelListener to use.

public void setOnDismissListener (DialogInterface.OnDismissListener listener)

Since: API Level 1

Set a listener to be invoked when the dialog is dismissed.

Parameters
listener The DialogInterface.OnDismissListener to use.

public void setOnKeyListener (DialogInterface.OnKeyListener onKeyListener)

Since: API Level 1

Sets the callback that will be called if a key is dispatched to the dialog.

public final void setOwnerActivity (Activity activity)

Since: API Level 1

Sets the Activity that owns this dialog. An example use: This Dialog will use the suggested volume control stream of the Activity.

Parameters
activity The Activity that owns this dialog.

public void setTitle (int titleId)

Since: API Level 1

Set the title text for this dialog's window. The text is retrieved from the resources with the supplied identifier.

Parameters
titleId the title's text resource identifier

public void setTitle (CharSequence title)

Since: API Level 1

Set the title text for this dialog's window.

Parameters
title The new text to display in the title.

public final void setVolumeControlStream (int streamType)

Since: API Level 1

By default, this will use the owner Activity's suggested stream type.

public void show ()

Since: API Level 1

Start the dialog and display it on screen. The window is placed in the application layer and opaque. Note that you should not override this method to do initialization when the dialog is shown, instead implement that in onStart().

public void takeKeyEvents (boolean get)

Since: API Level 1

Request that key events come to this dialog. Use this if your dialog has no views with focus, but the dialog still wants a chance to process key events.

Parameters
get true if the dialog should receive key events, false otherwise

public void unregisterForContextMenu (View view)

Since: API Level 1

Protected Methods

protected void onCreate (Bundle savedInstanceState)

Since: API Level 1

Similar to onCreate(Bundle), you should initialized your dialog in this method, including calling setContentView(View).

Parameters
savedInstanceState If this dialog is being reinitalized after a the hosting activity was previously shut down, holds the result from the most recent call to onSaveInstanceState(), or null if this is the first time.

protected void onStart ()

Since: API Level 1

Called when the dialog is starting.

protected void onStop ()

Since: API Level 1

Called to tell you that you're stopping.