diff options
author | Scott Main <> | 2009-04-26 15:51:58 -0700 |
---|---|---|
committer | The Android Open Source Project <initial-contribution@android.com> | 2009-04-26 15:51:58 -0700 |
commit | ce878bef710c6d1e6881949c82b1293fb8435715 (patch) | |
tree | 04b5ca4f6c0f77f7f24f1a1dbe17f229597cbc6f | |
parent | b8b3645a9799c38ad68549316ebbf7a4849f2e0c (diff) | |
download | frameworks_base-ce878bef710c6d1e6881949c82b1293fb8435715.zip frameworks_base-ce878bef710c6d1e6881949c82b1293fb8435715.tar.gz frameworks_base-ce878bef710c6d1e6881949c82b1293fb8435715.tar.bz2 |
AI 147804: add new doc about Dialogs
BUG=1800118
Automated import of CL 147804
-rw-r--r-- | docs/html/guide/topics/ui/dialogs.jd | 650 | ||||
-rwxr-xr-x | docs/html/images/dialog_buttons.png | bin | 0 -> 3701 bytes | |||
-rwxr-xr-x | docs/html/images/dialog_custom.png | bin | 0 -> 4018 bytes | |||
-rwxr-xr-x | docs/html/images/dialog_list.png | bin | 0 -> 3830 bytes | |||
-rwxr-xr-x | docs/html/images/dialog_progress_bar.png | bin | 0 -> 2562 bytes | |||
-rwxr-xr-x | docs/html/images/dialog_progress_spinning.png | bin | 0 -> 2648 bytes | |||
-rwxr-xr-x | docs/html/images/dialog_singlechoicelist.png | bin | 0 -> 5071 bytes |
7 files changed, 650 insertions, 0 deletions
diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd new file mode 100644 index 0000000..c0c0b1b --- /dev/null +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -0,0 +1,650 @@ +page.title=Creating Dialogs +parent.title=User Interface +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Key classes</h2> + <ol> + <li>{@link android.app.Dialog}</li> + </ol> + <h2>In this document</h2> + <ol> + <li><a href="#ShowingADialog">Showing a Dialog</a></li> + <li><a href="#DismissingADialog">Dismissing a Dialog</a></li> + <li><a href="#AlertDialog">Creating an AlertDialog</a> + <ol> + <li><a href="#AddingButtons">Adding buttons</a></li> + <li><a href="#AddingAList">Adding a list</a></li> + </ol> + </li> + <li><a href="#ProgressDialog">Creating a ProgressDialog</a> + <ol> + <li><a href="#ShowingAProgressBar">Showing a progress bar</a></li> + </ol> + </li> + <li><a href="#CustomDialog">Creating a Custom Dialog</a></li> + </ol> + </div> +</div> + +<p>A dialog is usually a small window that appears in front of the current Activity. +The underlying Activity loses focus and the dialog accepts all user interaction. +Dialogs are normally used +for notifications and short activities that directly relate to the application in progress.</p> + +<p>The Android API supports the following types of {@link android.app.Dialog} objects:</p> +<dl> + <dt>{@link android.app.AlertDialog}</dt> + <dd>A dialog that can manage zero, one, two, or three buttons, and/or a list of + selectable items that can include checkboxes or radio buttons. The AlertDialog + is capable of constructing most dialog user interfaces and is the suggested dialog type. + See <a href="#AlertDialog">Creating an AlertDialog</a> below.</dd> + <dt>{@link android.app.ProgressDialog}</dt> + <dd>A dialog that displays a progress wheel or progress bar. Because it's an extension of + the AlertDialog, it also supports buttons. + See <a href="#ProgressDialog">Creating a ProgressDialog</a> below.</dd> + <dt>{@link android.app.DatePickerDialog}</dt> + <dd>A dialog that allows the user to select a date. See the + <a href="{@docRoot}guide/tutorials/views/hello-datepicker.html">Hello DatePicker</a> tutorial.</dd> + <dt>{@link android.app.TimePickerDialog}</dt> + <dd>A dialog that allows the user to select a time. See the + <a href="{@docRoot}guide/tutorials/views/hello-timepicker.html">Hello TimePicker</a> tutorial.</dd> +</dl> + +<p>If you would like to customize your own dialog, you can extend the +base {@link android.app.Dialog} object or any of the subclasses listed above and define a new layout. +See the section on <a href="#CustomDialog">Creating a Custom Dialog</a> below.</p> + + +<h2 id="ShowingADialog">Showing a Dialog</h2> + +<p>A dialog is always created and displayed as a part of an {@link android.app.Activity}. +You should normally create dialogs from within your Activity's +{@link android.app.Activity#onCreateDialog(int)} callback method. +When you use this callback, the Android system automatically manages the state of +each dialog and hooks them to the Activity, effectively making it the "owner" of each dialog. +As such, each dialog inherits certain properties from the Activity. For example, when a dialog +is open, the Menu key reveals the options menu defined for the Activity and the volume +keys modify the audio stream used by the Activity.</p> + +<p class="note"><strong>Note:</strong> If you decide to create a dialog outside of the +<code>onCreateDialog()</code> method, it will not be attached to an Activity. You can, however, +attach it to an Activity with {@link android.app.Dialog#setOwnerActivity(Activity)}.</p> + +<p>When you want to show a dialog, call +{@link android.app.Activity#showDialog(int)} and pass it an integer that uniquely identifies the +dialog that you want to display.</p> + +<p>When a dialog is requested for the first time, Android calls +{@link android.app.Activity#onCreateDialog(int)} from your Activity, which is +where you should instantiate the {@link android.app.Dialog}. This callback method +is passed the same ID that you passed to {@link android.app.Activity#showDialog(int)}. +After you create the Dialog, return the object at the end of the method.</p> + +<p>Before the dialog is displayed, Android also calls the optional callback method +{@link android.app.Activity#onPrepareDialog(int,Dialog)}. Define this method if you want to change +any properties of the dialog each time it is opened. This method is called +every time a dialog is opened, whereas {@link android.app.Activity#onCreateDialog(int)} is only +called the very first time a dialog is opened. If you don't define +{@link android.app.Activity#onPrepareDialog(int,Dialog) onPrepareDialog()}, then the dialog will +remain the same as it was the previous time it was opened. This method is also passed the dialog's +ID, along with the Dialog object you created in {@link android.app.Activity#onCreateDialog(int) +onCreateDialog()}.</p> + +<p>The best way to define the {@link android.app.Activity#onCreateDialog(int)} and +{@link android.app.Activity#onPrepareDialog(int,Dialog)} callback methods is with a +<em>switch</em> statement that checks the <var>id</var> parameter that's passed into the method. +Each <em>case</em> should check for a unique dialog ID and then create and define the respective Dialog. +For example, imagine a game that uses two different dialogs: one to indicate that the game +has paused and another to indicate that the game is over. First, define an integer ID for +each dialog:</p> +<pre> +static final int DIALOG_PAUSED_ID = 0; +static final int DIALOG_GAMEOVER_ID = 1; +</pre> + +<p>Then, define the {@link android.app.Activity#onCreateDialog(int)} callback with a +switch case for each ID:</p> +<pre> +protected Dialog onCreateDialog(int id) { + Dialog dialog; + switch(id) { + case DIALOG_PAUSED_ID: + // do the work to define the pause Dialog + break; + case DIALOG_GAMEOVER_ID: + // do the work to define the game over Dialog + break; + default: + dialog = null; + } + return dialog; +} +</pre> + +<p class="note"><strong>Note:</strong> In this example, there's no code inside +the case statements because the procedure for defining your Dialog is outside the scope +of this section. See the section below about <a href="#AlertDialog">Creating an AlertDialog</a>, +offers code suitable for this example.</p> + +<p>When it's time to show one of the dialogs, call {@link android.app.Activity#showDialog(int)} +with the ID of a dialog:</p> +<pre> +showDialog(DIALOG_PAUSED_ID); +</pre> + + +<h2 id="DismissingADialog">Dismissing a Dialog</h2> + +<p>When you're ready to close your dialog, you can dismiss it by calling +{@link android.app.Dialog#dismiss()} on the Dialog object. +If necessary, you can also call {@link android.app.Activity#dismissDialog(int)} from the +Activity, which effectively calls {@link android.app.Dialog#dismiss()} on the +Dialog for you.</p> + +<p>If you are using {@link android.app.Activity#onCreateDialog(int)} to manage the state +of your dialogs (as discussed in the previous section), then every time your dialog is +dismissed, the state of the Dialog +object is retained by the Activity. If you decide that you will no longer need this object or +it's important that the state is cleared, then you should call +{@link android.app.Activity#removeDialog(int)}. This will remove any internal references +to the object and if the dialog is showing, it will dismiss it.</p> + +<h3>Using dismiss listeners</h3> + +<p>If you'd like your applcation to perform some procedures the moment that a dialog is dismissed, +then you should attach an on-dismiss listener to your Dialog.</p> + +<p>First define the {@link android.content.DialogInterface.OnDismissListener} interface. +This interface has just one method, +{@link android.content.DialogInterface.OnDismissListener#onDismiss(DialogInterface)}, which +will be called when the dialog is dismissed. +Then simply pass your OnDismissListener implementation to +{@link android.app.Dialog#setOnDismissListener(DialogInterface.OnDismissListener) +setOnDismissListener()}.</p> + +<p>However, note that dialogs can also be "cancelled." This is a special case that indicates +the dialog was explicitly cancelled by the user. This will occur if the user presses the +"back" button to close the dialog, or if the dialog explicitly calls {@link android.app.Dialog#cancel()} +(perhaps from a "Cancel" button in the dialog). When a dialog is cancelled, +the OnDismissListener will still be notified, but if you'd like to be informed that the dialog +was explicitly cancelled (and not dismissed normally), then you should register +an {@link android.content.DialogInterface.OnCancelListener} with +{@link android.app.Dialog#setOnCancelListener(DialogInterface.OnCancelListener) +setOnCancelListener()}.</p> + + +<h2 id="AlertDialog">Creating an AlertDialog</h2> + +<p>An {@link android.app.AlertDialog} is an extension of the {@link android.app.Dialog} +class. It is capable of constructing most dialog user interfaces and is the suggested dialog type. +You should use it for dialogs that use any of the following features:</p> +<ul> + <li>A title</li> + <li>A text message</li> + <li>One, two, or three buttons</li> + <li>A list of selectable items (with optional checkboxes or radio buttons)</li> +</ul> + +<p>To create an AlertDialog, use the {@link android.app.AlertDialog.Builder} subclass. +Get a Builder with {@link android.app.AlertDialog.Builder#AlertDialog.Builder(Context)} and +then use the class's public methods to define all of the +AlertDialog properties. After you're done with the Builder, retrieve the +AlertDialog object with {@link android.app.AlertDialog.Builder#create()}.</p> + +<p>The following topics show how to define various properties of the AlertDialog using the +AlertDialog.Builder class. If you use any of the following sample code inside your +{@link android.app.Activity#onCreateDialog(int) onCreateDialog()} callback method, +you can return the resulting Dialog object to display the dialog.</p> + + +<h3 id="AddingButtons">Adding buttons</h3> + +<img src="{@docRoot}images/dialog_buttons.png" alt="" style="float:right" /> + +<p>To create an AlertDialog with side-by-side buttons like the one shown in the screenshot to the right, +use the <code>set...Button()</code> methods:</p> + +<pre> +AlertDialog.Builder builder = new AlertDialog.Builder(this); +builder.setMessage("Are you sure you want to exit?") + .setCancelable(false) + .setPositiveButton("Yes", new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + MyActivity.this.finish(); + } + }) + .setNegativeButton("No", new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + dialog.cancel(); + } + }); +AlertDialog alert = builder.create(); +</pre> + +<p>First, add a message for the dialog with +{@link android.app.AlertDialog.Builder#setMessage(CharSequence)}. Then, begin +method-chaining and set the dialog +to be <em>not cancelable</em> (so the user cannot close the dialog with the back button) +with {@link android.app.AlertDialog.Builder#setCancelable(boolean)}. For each button, +use one of the <code>set...Button()</code> methods, such as +{@link android.app.AlertDialog.Builder#setPositiveButton(CharSequence,DialogInterface.OnClickListener) +setPositiveButton()}, that accepts the name for the button and a +{@link android.content.DialogInterface.OnClickListener} that defines the action to take +when the user selects the button.</p> + +<p class="note"><strong>Note:</strong> You can only add one of each button type to the +AlertDialog. That is, you cannot have more than one "positive" button. This limits the number +of possible buttons to three: positive, neutral, and negative. These names are technically irrelevant to the +actual functionality of your buttons, but should help you keep track of which one does what.</p> + + +<h3 id="AddingAList">Adding a list</h3> + +<img src="{@docRoot}images/dialog_list.png" alt="" style="float:right" /> + +<p>To create an AlertDialog with a list of selectable items like the one shown to the right, +use the <code>setItems()</code> method:</p> + +<pre> +final CharSequence[] items = {"Red", "Green", "Blue"}; + +AlertDialog.Builder builder = new AlertDialog.Builder(this); +builder.setTitle("Pick a color"); +builder.setItems(items, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int item) { + Toast.makeText(getApplicationContext(), items[item], Toast.LENGTH_SHORT).show(); + } +}); +AlertDialog alert = builder.create(); +</pre> + +<p>First, add a title to the dialog with +{@link android.app.AlertDialog.Builder#setTitle(CharSequence)}. +Then, add a list of selectable items with +{@link android.app.AlertDialog.Builder#setItems(CharSequence[],DialogInterface.OnClickListener) +setItems()}, which accepts the array of items to display and a +{@link android.content.DialogInterface.OnClickListener} that defines the action to take +when the user selects an item.</p> + + +<h4>Adding checkboxes and radio buttons</h4> + +<img src="{@docRoot}images/dialog_singlechoicelist.png" alt="" style="float:right" /> + +<p>To create a list of multiple-choice items (checkboxes) or +single-choice items (radio buttons) inside the dialog, use the +{@link android.app.AlertDialog.Builder#setMultiChoiceItems(Cursor,String,String, +DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()} and +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +setSingleChoiceItems()} methods, respectively. +If you create one of these selectable lists in the +{@link android.app.Activity#onCreateDialog(int) onCreateDialog()} callback method, +Android manages the state of the list for you. As long as the Activity is active, +the dialog remembers the items that were previously selected, but when the user exits the +Activity, the selection is lost. + +<p class="note"><strong>Note:</strong> To save the selection when the user leaves or +pauses the Activity, you must properly save and restore the setting throughout +the <a href="{@docRoot}guide/topics/fundamentals.html#lcycles">Activity Lifecycle</a>. +To permanently save the selections, even when the Activity process is completely shutdown, +you need to save the settings +with one of the <a href="{@docRoot}guide/topics/data/data-storage.html">Data +Storage</a> techniques.</p> + +<p>To create an AlertDialog with a list of single-choice items like the one shown to the right, +use the same code from the previous example, but replace the <code>setItems()</code> method with +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +setSingleChoiceItems()}:</p> + +<pre> +final CharSequence[] items = {"Red", "Green", "Blue"}; + +AlertDialog.Builder builder = new AlertDialog.Builder(this); +builder.setTitle("Pick a color"); +builder.setSingleChoiceItems(items, -1, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int item) { + Toast.makeText(getApplicationContext(), items[item], Toast.LENGTH_SHORT).show(); + } +}); +AlertDialog alert = builder.create(); +</pre> + +<p>The second parameter in the +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(CharSequence[],int,DialogInterface.OnClickListener) +setSingleChoiceItems()} method is an integer value for the <var>checkedItem</var>, which indicates the +zero-based list position of the default selected item. Use "-1" to indicate that no item should be +selected by default.</p> + + +<h2 id="ProgressDialog">Creating a ProgressDialog</h2> + +<img src="{@docRoot}images/dialog_progress_spinning.png" alt="" style="float:right" /> + +<p>A {@link android.app.ProgressDialog} is an extension of the {@link android.app.AlertDialog} +class that can display a progress animation in the form of a spinning wheel, for a task with +progress that's undefined, or a progress bar, for a task that has a defined progression. +The dialog can also provide buttons, such as one to cancel a download.</p> + +<p>Opening a progress dialog can be as simple as calling +{@link android.app.ProgressDialog#show(Context,CharSequence,CharSequence) +ProgressDialog.show()}. For example, the progress dialog shown to the right can be +easily achieved without managing the dialog through the +{@link android.app.Activity#onCreateDialog(int)} callback, +as shown here:</p> + +<pre> +ProgressDialog dialog = ProgressDialog.show(MyActivity.this, "", + "Loading. Please wait...", true); +</pre> + +<p>The first parameter is the application {@link android.content.Context}, +the second is a title for the dialog (left empty), the third is the message, +and the last parameter is whether the progress +is indeterminate (this is only relevant when creating a progress bar, which is +discussed in the next section). +</p> + +<p>The default style of a progress dialog is the spinning wheel. +If you want to create a progress bar that shows the loading progress with granularity, +some more code is required, as discussed in the next section.</p> + + +<h3 id="ShowingAProgressBar">Showing a progress bar</h3> + +<img src="/images/dialog_progress_bar.png" alt="" style="float:right" /> + +<p>To show the progression with an animated progress bar:</p> + +<ol> + <li>Initialize the + ProgressDialog with the class constructor, + {@link android.app.ProgressDialog#ProgressDialog(Context)}.</li> + <li>Set the progress style to "STYLE_HORIZONTAL" with + {@link android.app.ProgressDialog#setProgressStyle(int)} and + set any other properties, such as the message.</li> + <li>When you're ready to show the dialog, call + {@link android.app.Dialog#show()} or return the ProgressDialog from the + {@link android.app.Activity#onCreateDialog(int)} callback.</li> + <li>You can increment the amount of progress displayed + in the bar by calling either {@link android.app.ProgressDialog#setProgress(int)} with a value for + the total percentage completed so far or {@link android.app.ProgressDialog#incrementProgressBy(int)} + with an incremental value to add to the total percentage completed so far.</li> +</ol> + +<p>For example, your setup might look like this:</p> +<pre> +ProgressDialog progressDialog; +progressDialog = new ProgressDialog(mContext); +progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL); +progressDialog.setMessage("Loading..."); +progressDialog.setCancelable(false); +</pre> + +<p>The setup is simple. Most of the code needed to create a progress dialog is actually +involved in the process that updates it. You might find that it's +necessary to create a second thread in your application for this work and then report the progress +back to the Activity's UI thread with a {@link android.os.Handler} object. +If you're not familiar with using additional +threads with a Handler, see the example Activity below that uses a second thread to +increment a progress dialog managed by the Activity.</p> + +<script type="text/javascript"> +function toggleDiv(link) { + var toggleable = $(link).parent(); + if (toggleable.hasClass("closed")) { + $(".toggleme", toggleable).slideDown("fast"); + toggleable.removeClass("closed"); + toggleable.addClass("open"); + $(".toggle-img", toggleable).attr("title", "hide").attr("src", "/assets/images/triangle-opened.png"); + } else { + $(".toggleme", toggleable).slideUp("fast"); + toggleable.removeClass("open"); + toggleable.addClass("closed"); + $(".toggle-img", toggleable).attr("title", "show").attr("src", "/assets/images/triangle-closed.png"); + } + return false; +} +</script> +<style> +.toggleme { + padding:0 0 1px 0; +} +.toggleable a { + text-decoration:none; +} +.toggleable.closed .toggleme { + display:none; +} +#jd-content .toggle-img { + margin:0; +} +</style> + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="/assets/images/triangle-closed.png" class="toggle-img" /> + <strong>Example ProgressDialog with a second thread</strong></a> + <div class="toggleme"> + <p>This example uses a second thread to track the progress of a process (which actually just +counts up to 100). The thread sends a {@link android.os.Message} back to the main +Activity through a {@link android.os.Handler} each time progress is made. The main Activity then updates the +ProgressDialog.</p> + +<pre> +package com.example.progressdialog; + +import android.app.Activity; +import android.app.Dialog; +import android.app.ProgressDialog; +import android.os.Bundle; +import android.os.Handler; +import android.os.Message; +import android.view.View; +import android.view.View.OnClickListener; +import android.widget.Button; + +public class NotificationTest extends Activity { + static final int PROGRESS_DIALOG = 0; + Button button; + ProgressThread progressThread; + ProgressDialog progressDialog; + + /** Called when the activity is first created. */ + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + // Setup the button that starts the progress dialog + button = (Button) findViewById(R.id.progressDialog); + button.setOnClickListener(new OnClickListener(){ + public void onClick(View v) { + showDialog(PROGRESS_DIALOG); + } + }); + } + + protected Dialog onCreateDialog(int id) { + switch(id) { + case PROGRESS_DIALOG: + progressDialog = new ProgressDialog(NotificationTest.this); + progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL); + progressDialog.setMessage("Loading..."); + progressThread = new ProgressThread(handler); + progressThread.start(); + return progressDialog; + default: + return null; + } + } + + // Define the Handler that receives messages from the thread and update the progress + final Handler handler = new Handler() { + public void handleMessage(Message msg) { + int total = msg.getData().getInt("total"); + progressDialog.setProgress(total); + if (total >= 100){ + dismissDialog(PROGRESS_DIALOG); + progressThread.setState(ProgressThread.STATE_DONE); + } + } + }; + + /** Nested class that performs progress calculations (counting) */ + private class ProgressThread extends Thread { + Handler mHandler; + final static int STATE_DONE = 0; + final static int STATE_RUNNING = 1; + int mState; + int total; + + ProgressThread(Handler h) { + mHandler = h; + } + + public void run() { + mState = STATE_RUNNING; + total = 0; + while (mState == STATE_RUNNING) { + try { + Thread.sleep(100); + } catch (InterruptedException e) { + Log.e("ERROR", "Thread Interrupted"); + } + Message msg = mHandler.obtainMessage(); + Bundle b = new Bundle(); + b.putInt("total", total); + msg.setData(b); + mHandler.sendMessage(msg); + total++; + } + } + + /* sets the current state for the thread, + * used to stop the thread */ + public void setState(int state) { + mState = state; + } + } +} +</pre> + </div> <!-- end toggleme --> +</div> <!-- end toggleable --> + + + +<h2 id="CustomDialog">Creating a Custom Dialog</h2> + +<img src="{@docRoot}images/dialog_custom.png" alt="" style="float:right" /> + +<p>If you want a customized design for a dialog, you can create your own layout +for the dialog window with layout and widget elements. +After you've defined your layout, pass the root View object or +layout resource ID to {@link android.app.Dialog#setContentView(View)}.</p> + +<p>For example, to create the dialog shown to the right:</p> + +<ol> + <li>Create an XML layout saved as <code>custom_dialog.xml</code>: +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/layout_root" + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="10dp" + > + <ImageView android:id="@+id/image" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_marginRight="10dp" + /> + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:textColor="#FFF" + /> +</LinearLayout> +</pre> + + <p>This XML defines an {@link android.widget.ImageView} and a {@link android.widget.TextView} + inside a {@link android.widget.LinearLayout}.</p> + <li>Set the above layout as the dialog's content view and define the content + for the ImageView and TextView elements:</p> +<pre> +Context mContext = getApplicationContext(); +Dialog dialog = new Dialog(mContext); + +dialog.setContentView(R.layout.custom_dialog); +dialog.setTitle("Custom Dialog"); + +TextView text = (TextView) dialog.findViewById(R.id.text); +text.setText("Hello, this is a custom dialog!"); +ImageView image = (ImageView) dialog.findViewById(R.id.image); +image.setImageResource(R.drawable.android); +</pre> + + <p>After you instantiate the Dialog, set your custom layout as the dialog's content view with + {@link android.app.Dialog#setContentView(int)}, passing it the layout resource ID. + Now that the Dialog has a defined layout, you can capture View objects from the layout with + {@link android.app.Dialog#findViewById(int)} and modify their content.</p> + </li> + + <li>That's it. You can now show the dialog as described in + <a href="#ShowingADialog">Showing A Dialog</a>.</li> +</ol> + +<p>A dialog made with the base Dialog class must have a title. If you don't call +{@link android.app.Dialog#setTitle(CharSequence) setTitle()}, then the space used for the title +remains empty, but still visible. If you don't want +a title at all, then you should create your custom dialog using the +{@link android.app.AlertDialog} class. However, because an AlertDialog is created easiest with +the {@link android.app.AlertDialog.Builder} class, you do not have access to the +{@link android.app.Dialog#setContentView(int)} method used above. Instead, you must use +{@link android.app.AlertDialog.Builder#setView(View)}. This method accepts a {@link android.view.View} object, +so you need to inflate the layout's root View object from +XML.</p> + +<p>To inflate the XML layout, retrieve the {@link android.view.LayoutInflater} with +{@link android.app.Activity#getLayoutInflater()} +(or {@link android.content.Context#getSystemService(String) getSystemService()}), +and then call +{@link android.view.LayoutInflater#inflate(int, ViewGroup)}, where the first parameter +is the layout resource ID and the second is the ID of the root View. At this point, you can use +the inflated layout to find View objects in the layout and define the content for the +ImageView and TextView elements. Then instantiate the AlertDialog.Builder and set the +inflated layout for the dialog with {@link android.app.AlertDialog.Builder#setView(View)}.</p> + +<p>Here's an example, creating a custom layout in an AlertDialog:</p> + +<pre> +AlertDialog.Builder builder; +AlertDialog alertDialog; + +Context mContext = getApplicationContext(); +LayoutInflater inflater = (LayoutInflater) mContext.getSystemService(LAYOUT_INFLATER); +View layout = inflater.inflate(R.layout.custom_dialog, + (ViewGroup) findViewById(R.id.layout_root)); + +TextView text = (TextView) layout.findViewById(R.id.text); +text.setText("Hello, this is a custom dialog!"); +ImageView image = (ImageView) layout.findViewById(R.id.image); +image.setImageResource(R.drawable.android); + +builder = new AlertDialog.Builder(mContext); +builder.setView(layout); +alertDialog = builder.create(); +</pre> + +<p>Using an AlertDialog for your custom layout lets you +take advantage of built-in AlertDialog features like managed buttons, +selectable lists, a title, an icon and so on.</p> + +<p>For more information, refer to the reference documentation for the +{@link android.app.Dialog} and {@link android.app.AlertDialog.Builder} +classes.</p> + + + diff --git a/docs/html/images/dialog_buttons.png b/docs/html/images/dialog_buttons.png Binary files differnew file mode 100755 index 0000000..81aaec4 --- /dev/null +++ b/docs/html/images/dialog_buttons.png diff --git a/docs/html/images/dialog_custom.png b/docs/html/images/dialog_custom.png Binary files differnew file mode 100755 index 0000000..b2523fd --- /dev/null +++ b/docs/html/images/dialog_custom.png diff --git a/docs/html/images/dialog_list.png b/docs/html/images/dialog_list.png Binary files differnew file mode 100755 index 0000000..f2736bf --- /dev/null +++ b/docs/html/images/dialog_list.png diff --git a/docs/html/images/dialog_progress_bar.png b/docs/html/images/dialog_progress_bar.png Binary files differnew file mode 100755 index 0000000..3e74419 --- /dev/null +++ b/docs/html/images/dialog_progress_bar.png diff --git a/docs/html/images/dialog_progress_spinning.png b/docs/html/images/dialog_progress_spinning.png Binary files differnew file mode 100755 index 0000000..501f4802 --- /dev/null +++ b/docs/html/images/dialog_progress_spinning.png diff --git a/docs/html/images/dialog_singlechoicelist.png b/docs/html/images/dialog_singlechoicelist.png Binary files differnew file mode 100755 index 0000000..90629f0 --- /dev/null +++ b/docs/html/images/dialog_singlechoicelist.png |