The AlertDialog class takes care of automatically setting * {@link WindowManager.LayoutParams#FLAG_ALT_FOCUSABLE_IM * WindowManager.LayoutParams.FLAG_ALT_FOCUSABLE_IM} for you based on whether @@ -70,31 +72,46 @@ public class AlertDialog extends Dialog implements DialogInterface { /** * Special theme constant for {@link #AlertDialog(Context, int)}: use * the traditional (pre-Holo) alert dialog theme. + * + * @deprecated Use {@link android.R.style#Theme_Material_Dialog_Alert}. */ + @Deprecated public static final int THEME_TRADITIONAL = 1; - + /** * Special theme constant for {@link #AlertDialog(Context, int)}: use * the holographic alert theme with a dark background. + * + * @deprecated Use {@link android.R.style#Theme_Material_Dialog_Alert}. */ + @Deprecated public static final int THEME_HOLO_DARK = 2; - + /** * Special theme constant for {@link #AlertDialog(Context, int)}: use * the holographic alert theme with a light background. + * + * @deprecated Use {@link android.R.style#Theme_Material_Light_Dialog_Alert}. */ + @Deprecated public static final int THEME_HOLO_LIGHT = 3; /** * Special theme constant for {@link #AlertDialog(Context, int)}: use * the device's default alert theme with a dark background. + * + * @deprecated Use {@link android.R.style#Theme_DeviceDefault_Dialog_Alert}. */ + @Deprecated public static final int THEME_DEVICE_DEFAULT_DARK = 4; /** * Special theme constant for {@link #AlertDialog(Context, int)}: use * the device's default alert theme with a light background. + * + * @deprecated Use {@link android.R.style#Theme_DeviceDefault_Light_Dialog_Alert}. */ + @Deprecated public static final int THEME_DEVICE_DEFAULT_LIGHT = 5; /** @@ -108,55 +125,92 @@ public class AlertDialog extends Dialog implements DialogInterface { * @hide */ public static final int LAYOUT_HINT_SIDE = 1; - + + /** + * Creates an alert dialog that uses the default alert dialog theme. + *
+ * The default alert dialog theme is defined by + * {@link android.R.attr#alertDialogTheme} within the parent + * {@code context}'s theme. + * + * @param context the parent context + */ protected AlertDialog(Context context) { - this(context, resolveDialogTheme(context, 0), true); + this(context, 0); } /** - * Construct an AlertDialog that uses an explicit theme. The actual style - * that an AlertDialog uses is a private implementation, however you can - * here supply either the name of an attribute in the theme from which - * to get the dialog's style (such as {@link android.R.attr#alertDialogTheme} - * or one of the constants {@link #THEME_TRADITIONAL}, - * {@link #THEME_HOLO_DARK}, or {@link #THEME_HOLO_LIGHT}. + * Creates an alert dialog that uses the default alert dialog theme and a + * custom cancel listener. + *
+ * This is functionally identical to: + *
+ * AlertDialog dialog = new AlertDialog(context); + * alertDialog.setCancelable(cancelable); + * alertDialog.setOnCancelListener(cancelListener); + *+ *
+ * The default alert dialog theme is defined by + * {@link android.R.attr#alertDialogTheme} within the parent + * {@code context}'s theme. + * + * @param context the parent context */ - protected AlertDialog(Context context, @AttrRes int theme) { - this(context, theme, true); + protected AlertDialog(Context context, boolean cancelable, OnCancelListener cancelListener) { + this(context, 0); + + setCancelable(cancelable); + setOnCancelListener(cancelListener); } - AlertDialog(Context context, int theme, boolean createThemeContextWrapper) { - super(context, resolveDialogTheme(context, theme), createThemeContextWrapper); + /** + * Creates an alert dialog that uses an explicit theme resource. + *
+ * The specified theme resource ({@code themeResId}) is applied on top of + * the parent {@code context}'s theme. It may be specified as a style + * resource containing a fully-populated theme, such as + * {@link android.R.style#Theme_Material_Dialog}, to replace all attributes + * in the parent {@code context}'s theme including primary and accent + * colors. + *
+ * To preserve attributes such as primary and accent colors, the + * {@code themeResId} may instead be specified as an overlay theme such as + * {@link android.R.style#ThemeOverlay_Material_Dialog}. This will override + * only the window attributes necessary to style the alert window as a + * dialog. + *
+ * Alternatively, the {@code themeResId} may be specified as {@code 0} to + * use the parent {@code context}'s resolved value for + * {@link android.R.attr#alertDialogTheme}. + * + * @param context the parent context + * @param themeResId the resource ID of the theme against which to inflate + * this dialog, or {@code 0} to use the parent + * {@code context}'s default alert dialog theme + */ + protected AlertDialog(Context context, @AttrRes int themeResId) { + super(context, resolveDialogTheme(context, themeResId)); mWindow.alwaysReadCloseOnTouchAttr(); mAlert = new AlertController(getContext(), this, getWindow()); } - protected AlertDialog(Context context, boolean cancelable, OnCancelListener cancelListener) { - super(context, resolveDialogTheme(context, 0)); - mWindow.alwaysReadCloseOnTouchAttr(); - setCancelable(cancelable); - setOnCancelListener(cancelListener); - mAlert = new AlertController(context, this, getWindow()); - } - - static int resolveDialogTheme(Context context, int resid) { - if (resid == THEME_TRADITIONAL) { - return com.android.internal.R.style.Theme_Dialog_Alert; - } else if (resid == THEME_HOLO_DARK) { - return com.android.internal.R.style.Theme_Holo_Dialog_Alert; - } else if (resid == THEME_HOLO_LIGHT) { - return com.android.internal.R.style.Theme_Holo_Light_Dialog_Alert; - } else if (resid == THEME_DEVICE_DEFAULT_DARK) { - return com.android.internal.R.style.Theme_DeviceDefault_Dialog_Alert; - } else if (resid == THEME_DEVICE_DEFAULT_LIGHT) { - return com.android.internal.R.style.Theme_DeviceDefault_Light_Dialog_Alert; - } else if (resid >= 0x01000000) { // start of real resource IDs. - return resid; + static int resolveDialogTheme(Context context, int themeResId) { + if (themeResId == THEME_TRADITIONAL) { + return R.style.Theme_Dialog_Alert; + } else if (themeResId == THEME_HOLO_DARK) { + return R.style.Theme_Holo_Dialog_Alert; + } else if (themeResId == THEME_HOLO_LIGHT) { + return R.style.Theme_Holo_Light_Dialog_Alert; + } else if (themeResId == THEME_DEVICE_DEFAULT_DARK) { + return R.style.Theme_DeviceDefault_Dialog_Alert; + } else if (themeResId == THEME_DEVICE_DEFAULT_LIGHT) { + return R.style.Theme_DeviceDefault_Light_Dialog_Alert; + } else if (themeResId >= 0x01000000) { // start of real resource IDs. + return themeResId; } else { - TypedValue outValue = new TypedValue(); - context.getTheme().resolveAttribute(com.android.internal.R.attr.alertDialogTheme, - outValue, true); + final TypedValue outValue = new TypedValue(); + context.getTheme().resolveAttribute(R.attr.alertDialogTheme, outValue, true); return outValue.resourceId; } } @@ -177,13 +231,13 @@ public class AlertDialog extends Dialog implements DialogInterface { /** * Gets the list view used in the dialog. - * + * * @return The {@link ListView} from the dialog. */ public ListView getListView() { return mAlert.getListView(); } - + @Override public void setTitle(CharSequence title) { super.setTitle(title); @@ -196,7 +250,7 @@ public class AlertDialog extends Dialog implements DialogInterface { public void setCustomTitle(View customTitleView) { mAlert.setCustomTitle(customTitleView); } - + public void setMessage(CharSequence message) { mAlert.setMessage(message); } @@ -207,9 +261,9 @@ public class AlertDialog extends Dialog implements DialogInterface { public void setView(View view) { mAlert.setView(view); } - + /** - * Set the view to display in that dialog, specifying the spacing to appear around that + * Set the view to display in that dialog, specifying the spacing to appear around that * view. * * @param view The view to show in the content area of the dialog @@ -233,7 +287,7 @@ public class AlertDialog extends Dialog implements DialogInterface { /** * Set a message to be sent when a button is pressed. - * + * * @param whichButton Which button to set the message for, can be one of * {@link DialogInterface#BUTTON_POSITIVE}, * {@link DialogInterface#BUTTON_NEGATIVE}, or @@ -244,10 +298,10 @@ public class AlertDialog extends Dialog implements DialogInterface { public void setButton(int whichButton, CharSequence text, Message msg) { mAlert.setButton(whichButton, text, null, msg); } - + /** * Set a listener to be invoked when the positive button of the dialog is pressed. - * + * * @param whichButton Which button to set the listener on, can be one of * {@link DialogInterface#BUTTON_POSITIVE}, * {@link DialogInterface#BUTTON_NEGATIVE}, or @@ -267,7 +321,7 @@ public class AlertDialog extends Dialog implements DialogInterface { public void setButton(CharSequence text, Message msg) { setButton(BUTTON_POSITIVE, text, msg); } - + /** * @deprecated Use {@link #setButton(int, CharSequence, Message)} with * {@link DialogInterface#BUTTON_NEGATIVE}. @@ -288,7 +342,7 @@ public class AlertDialog extends Dialog implements DialogInterface { /** * Set a listener to be invoked when button 1 of the dialog is pressed. - * + * * @param text The text to display in button 1. * @param listener The {@link DialogInterface.OnClickListener} to use. * @deprecated Use @@ -334,7 +388,7 @@ public class AlertDialog extends Dialog implements DialogInterface { public void setIcon(@DrawableRes int resId) { mAlert.setIcon(resId); } - + public void setIcon(Drawable icon) { mAlert.setIcon(icon); } @@ -353,7 +407,7 @@ public class AlertDialog extends Dialog implements DialogInterface { public void setInverseBackgroundForced(boolean forceInverseBackground) { mAlert.setInverseBackgroundForced(forceInverseBackground); } - + @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); @@ -371,35 +425,57 @@ public class AlertDialog extends Dialog implements DialogInterface { if (mAlert.onKeyUp(keyCode, event)) return true; return super.onKeyUp(keyCode, event); } - + public static class Builder { private final AlertController.AlertParams P; - private int mTheme; - + private int mThemeResId; + /** - * Constructor using a context for this builder and the {@link AlertDialog} it creates. + * Creates a builder for an alert dialog that uses the default alert + * dialog theme. + *
+ * The default alert dialog theme is defined by + * {@link android.R.attr#alertDialogTheme} within the parent + * {@code context}'s theme. + * + * @param context the parent context */ public Builder(Context context) { this(context, resolveDialogTheme(context, 0)); } /** - * Constructor using a context and theme for this builder and - * the {@link AlertDialog} it creates. The actual theme - * that an AlertDialog uses is a private implementation, however you can - * here supply either the name of an attribute in the theme from which - * to get the dialog's style (such as {@link android.R.attr#alertDialogTheme} - * or one of the constants - * {@link AlertDialog#THEME_TRADITIONAL AlertDialog.THEME_TRADITIONAL}, - * {@link AlertDialog#THEME_HOLO_DARK AlertDialog.THEME_HOLO_DARK}, or - * {@link AlertDialog#THEME_HOLO_LIGHT AlertDialog.THEME_HOLO_LIGHT}. + * Creates a builder for an alert dialog that uses an explicit theme + * resource. + *
+ * The specified theme resource ({@code themeResId}) is applied on top + * of the parent {@code context}'s theme. It may be specified as a + * style resource containing a fully-populated theme, such as + * {@link android.R.style#Theme_Material_Dialog}, to replace all + * attributes in the parent {@code context}'s theme including primary + * and accent colors. + *
+ * To preserve attributes such as primary and accent colors, the + * {@code themeResId} may instead be specified as an overlay theme such + * as {@link android.R.style#ThemeOverlay_Material_Dialog}. This will + * override only the window attributes necessary to style the alert + * window as a dialog. + *
+ * Alternatively, the {@code themeResId} may be specified as {@code 0} + * to use the parent {@code context}'s resolved value for + * {@link android.R.attr#alertDialogTheme}. + * + * @param context the parent context + * @param themeResId the resource ID of the theme against which to inflate + * this dialog, or {@code 0} to use the parent + * {@code context}'s default alert dialog theme */ - public Builder(Context context, int theme) { + public Builder(Context context, int themeResId) { P = new AlertController.AlertParams(new ContextThemeWrapper( - context, resolveDialogTheme(context, theme))); - mTheme = theme; + context, resolveDialogTheme(context, themeResId))); + mThemeResId = themeResId; } - + /** * Returns a {@link Context} with the appropriate theme for dialogs created by this Builder. * Applications should use this Context for obtaining LayoutInflaters for inflating views @@ -421,7 +497,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mTitle = P.mContext.getText(titleId); return this; } - + /** * Set the title displayed in the {@link Dialog}. * @@ -431,23 +507,28 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mTitle = title; return this; } - + /** - * Set the title using the custom view {@code customTitleView}. The - * methods {@link #setTitle(int)} and {@link #setIcon(int)} should be - * sufficient for most titles, but this is provided if the title needs - * more customization. Using this will replace the title and icon set - * via the other methods. - * - * @param customTitleView The custom view to use as the title. + * Set the title using the custom view {@code customTitleView}. + *
+ * The methods {@link #setTitle(int)} and {@link #setIcon(int)} should + * be sufficient for most titles, but this is provided if the title + * needs more customization. Using this will replace the title and icon + * set via the other methods. + *
+ * Note: To ensure consistent styling, the custom view + * should be inflated or constructed using the alert dialog's themed + * context obtained via {@link #getContext()}. * - * @return This Builder object to allow for chaining of calls to set methods + * @param customTitleView the custom view to use as the title + * @return this Builder object to allow for chaining of calls to set + * methods */ public Builder setCustomTitle(View customTitleView) { P.mCustomTitleView = customTitleView; return this; } - + /** * Set the message to display using the given resource id. * @@ -457,7 +538,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mMessage = P.mContext.getText(messageId); return this; } - + /** * Set the message to display. * @@ -467,7 +548,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mMessage = message; return this; } - + /** * Set the resource id of the {@link Drawable} to be used in the title. *
@@ -479,11 +560,16 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIconId = iconId; return this; } - + /** * Set the {@link Drawable} to be used in the title. - * - * @return This Builder object to allow for chaining of calls to set methods + *
+ * Note: To ensure consistent styling, the drawable + * should be inflated or constructed using the alert dialog's themed + * context obtained via {@link #getContext()}. + * + * @return this Builder object to allow for chaining of calls to set + * methods */ public Builder setIcon(Drawable icon) { P.mIcon = icon; @@ -518,7 +604,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mPositiveButtonListener = listener; return this; } - + /** * Set a listener to be invoked when the positive button of the dialog is pressed. * @param text The text to display in the positive button @@ -531,7 +617,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mPositiveButtonListener = listener; return this; } - + /** * Set a listener to be invoked when the negative button of the dialog is pressed. * @param textId The resource id of the text to display in the negative button @@ -544,7 +630,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mNegativeButtonListener = listener; return this; } - + /** * Set a listener to be invoked when the negative button of the dialog is pressed. * @param text The text to display in the negative button @@ -557,7 +643,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mNegativeButtonListener = listener; return this; } - + /** * Set a listener to be invoked when the neutral button of the dialog is pressed. * @param textId The resource id of the text to display in the neutral button @@ -570,7 +656,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mNeutralButtonListener = listener; return this; } - + /** * Set a listener to be invoked when the neutral button of the dialog is pressed. * @param text The text to display in the neutral button @@ -583,7 +669,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mNeutralButtonListener = listener; return this; } - + /** * Sets whether the dialog is cancelable or not. Default is true. * @@ -593,7 +679,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mCancelable = cancelable; return this; } - + /** * Sets the callback that will be called if the dialog is canceled. * @@ -611,7 +697,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mOnCancelListener = onCancelListener; return this; } - + /** * Sets the callback that will be called when the dialog is dismissed for any reason. * @@ -631,7 +717,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mOnKeyListener = onKeyListener; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, you will be notified of the * selected item via the supplied listener. This should be an array type i.e. R.array.foo @@ -643,7 +729,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mOnClickListener = listener; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, you will be notified of the * selected item via the supplied listener. @@ -655,12 +741,12 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mOnClickListener = listener; return this; } - + /** * Set a list of items, which are supplied by the given {@link ListAdapter}, to be * displayed in the dialog as the content, you will be notified of the * selected item via the supplied listener. - * + * * @param adapter The {@link ListAdapter} to supply the list of items * @param listener The listener that will be called when an item is clicked. * @@ -671,12 +757,12 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mOnClickListener = listener; return this; } - + /** * Set a list of items, which are supplied by the given {@link Cursor}, to be * displayed in the dialog as the content, you will be notified of the * selected item via the supplied listener. - * + * * @param cursor The {@link Cursor} to supply the list of items * @param listener The listener that will be called when an item is clicked. * @param labelColumn The column name on the cursor containing the string to display @@ -691,7 +777,7 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mOnClickListener = listener; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, * you will be notified of the selected item via the supplied listener. @@ -699,7 +785,7 @@ public class AlertDialog extends Dialog implements DialogInterface { * a check mark displayed to the right of the text for each checked * item. Clicking on an item in the list will not dismiss the dialog. * Clicking on a button will dismiss the dialog. - * + * * @param itemsId the resource id of an array i.e. R.array.foo * @param checkedItems specifies which items are checked. It should be null in which case no * items are checked. If non null it must be exactly the same length as the array of @@ -718,14 +804,14 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIsMultiChoice = true; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, * you will be notified of the selected item via the supplied listener. * The list will have a check mark displayed to the right of the text * for each checked item. Clicking on an item in the list will not * dismiss the dialog. Clicking on a button will dismiss the dialog. - * + * * @param items the text of the items to be displayed in the list. * @param checkedItems specifies which items are checked. It should be null in which case no * items are checked. If non null it must be exactly the same length as the array of @@ -736,7 +822,7 @@ public class AlertDialog extends Dialog implements DialogInterface { * * @return This Builder object to allow for chaining of calls to set methods */ - public Builder setMultiChoiceItems(CharSequence[] items, boolean[] checkedItems, + public Builder setMultiChoiceItems(CharSequence[] items, boolean[] checkedItems, final OnMultiChoiceClickListener listener) { P.mItems = items; P.mOnCheckboxClickListener = listener; @@ -744,14 +830,14 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIsMultiChoice = true; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, * you will be notified of the selected item via the supplied listener. * The list will have a check mark displayed to the right of the text * for each checked item. Clicking on an item in the list will not * dismiss the dialog. Clicking on a button will dismiss the dialog. - * + * * @param cursor the cursor used to provide the items. * @param isCheckedColumn specifies the column name on the cursor to use to determine * whether a checkbox is checked or not. It must return an integer value where 1 @@ -764,7 +850,7 @@ public class AlertDialog extends Dialog implements DialogInterface { * * @return This Builder object to allow for chaining of calls to set methods */ - public Builder setMultiChoiceItems(Cursor cursor, String isCheckedColumn, String labelColumn, + public Builder setMultiChoiceItems(Cursor cursor, String isCheckedColumn, String labelColumn, final OnMultiChoiceClickListener listener) { P.mCursor = cursor; P.mOnCheckboxClickListener = listener; @@ -773,14 +859,14 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIsMultiChoice = true; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, you will be notified of * the selected item via the supplied listener. This should be an array type i.e. * R.array.foo The list will have a check mark displayed to the right of the text for the * checked item. Clicking on an item in the list will not dismiss the dialog. Clicking on a * button will dismiss the dialog. - * + * * @param itemsId the resource id of an array i.e. R.array.foo * @param checkedItem specifies which item is checked. If -1 no items are checked. * @param listener notified when an item on the list is clicked. The dialog will not be @@ -797,13 +883,13 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIsSingleChoice = true; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, you will be notified of * the selected item via the supplied listener. The list will have a check mark displayed to * the right of the text for the checked item. Clicking on an item in the list will not * dismiss the dialog. Clicking on a button will dismiss the dialog. - * + * * @param cursor the cursor to retrieve the items from. * @param checkedItem specifies which item is checked. If -1 no items are checked. * @param labelColumn The column name on the cursor containing the string to display in the @@ -814,7 +900,7 @@ public class AlertDialog extends Dialog implements DialogInterface { * * @return This Builder object to allow for chaining of calls to set methods */ - public Builder setSingleChoiceItems(Cursor cursor, int checkedItem, String labelColumn, + public Builder setSingleChoiceItems(Cursor cursor, int checkedItem, String labelColumn, final OnClickListener listener) { P.mCursor = cursor; P.mOnClickListener = listener; @@ -823,13 +909,13 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIsSingleChoice = true; return this; } - + /** * Set a list of items to be displayed in the dialog as the content, you will be notified of * the selected item via the supplied listener. The list will have a check mark displayed to * the right of the text for the checked item. Clicking on an item in the list will not * dismiss the dialog. Clicking on a button will dismiss the dialog. - * + * * @param items the items to be displayed. * @param checkedItem specifies which item is checked. If -1 no items are checked. * @param listener notified when an item on the list is clicked. The dialog will not be @@ -844,14 +930,14 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mCheckedItem = checkedItem; P.mIsSingleChoice = true; return this; - } - + } + /** * Set a list of items to be displayed in the dialog as the content, you will be notified of * the selected item via the supplied listener. The list will have a check mark displayed to * the right of the text for the checked item. Clicking on an item in the list will not * dismiss the dialog. Clicking on a button will dismiss the dialog. - * + * * @param adapter The {@link ListAdapter} to supply the list of items * @param checkedItem specifies which item is checked. If -1 no items are checked. * @param listener notified when an item on the list is clicked. The dialog will not be @@ -867,26 +953,25 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mIsSingleChoice = true; return this; } - + /** * Sets a listener to be invoked when an item in the list is selected. - * - * @param listener The listener to be invoked. - * @see AdapterView#setOnItemSelectedListener(android.widget.AdapterView.OnItemSelectedListener) * - * @return This Builder object to allow for chaining of calls to set methods + * @param listener the listener to be invoked + * @return this Builder object to allow for chaining of calls to set methods + * @see AdapterView#setOnItemSelectedListener(android.widget.AdapterView.OnItemSelectedListener) */ public Builder setOnItemSelectedListener(final AdapterView.OnItemSelectedListener listener) { P.mOnItemSelectedListener = listener; return this; } - + /** * Set a custom view resource to be the contents of the Dialog. The * resource will be inflated, adding all top-level views to the screen. * * @param layoutResId Resource ID to be inflated. - * @return This Builder object to allow for chaining of calls to set + * @return this Builder object to allow for chaining of calls to set * methods */ public Builder setView(int layoutResId) { @@ -897,12 +982,18 @@ public class AlertDialog extends Dialog implements DialogInterface { } /** - * Set a custom view to be the contents of the Dialog. If the supplied view is an instance - * of a {@link ListView} the light background will be used. + * Sets a custom view to be the contents of the alert dialog. + *
+ * When using a pre-Holo theme, if the supplied view is an instance of + * a {@link ListView} then the light background will be used. + *
+ * Note: To ensure consistent styling, the custom view + * should be inflated or constructed using the alert dialog's themed + * context obtained via {@link #getContext()}. * - * @param view The view to use as the contents of the Dialog. - * - * @return This Builder object to allow for chaining of calls to set methods + * @param view the view to use as the contents of the alert dialog + * @return this Builder object to allow for chaining of calls to set + * methods */ public Builder setView(View view) { P.mView = view; @@ -910,29 +1001,34 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mViewSpacingSpecified = false; return this; } - + /** - * Set a custom view to be the contents of the Dialog, specifying the - * spacing to appear around that view. If the supplied view is an - * instance of a {@link ListView} the light background will be used. - * - * @param view The view to use as the contents of the Dialog. - * @param viewSpacingLeft Spacing between the left edge of the view and - * the dialog frame - * @param viewSpacingTop Spacing between the top edge of the view and - * the dialog frame - * @param viewSpacingRight Spacing between the right edge of the view - * and the dialog frame - * @param viewSpacingBottom Spacing between the bottom edge of the view - * and the dialog frame - * @return This Builder object to allow for chaining of calls to set + * Sets a custom view to be the contents of the alert dialog and + * specifies additional padding around that view. + *
+ * When using a pre-Holo theme, if the supplied view is an instance of + * a {@link ListView} then the light background will be used. + *
+ * Note: To ensure consistent styling, the custom view + * should be inflated or constructed using the alert dialog's themed + * context obtained via {@link #getContext()}. + * + * @param view the view to use as the contents of the alert dialog + * @param viewSpacingLeft spacing between the left edge of the view and + * the dialog frame + * @param viewSpacingTop spacing between the top edge of the view and + * the dialog frame + * @param viewSpacingRight spacing between the right edge of the view + * and the dialog frame + * @param viewSpacingBottom spacing between the bottom edge of the view + * and the dialog frame + * @return this Builder object to allow for chaining of calls to set * methods - * - * - * This is currently hidden because it seems like people should just - * be able to put padding around the view. - * @hide + * + * @hide Remove once the framework usages have been replaced. + * @deprecated Set the padding on the view itself. */ + @Deprecated public Builder setView(View view, int viewSpacingLeft, int viewSpacingTop, int viewSpacingRight, int viewSpacingBottom) { P.mView = view; @@ -944,15 +1040,18 @@ public class AlertDialog extends Dialog implements DialogInterface { P.mViewSpacingBottom = viewSpacingBottom; return this; } - + /** - * Sets the Dialog to use the inverse background, regardless of what the - * contents is. - * - * @param useInverseBackground Whether to use the inverse background - * - * @return This Builder object to allow for chaining of calls to set methods + * Sets the alert dialog to use the inverse background, regardless of + * what the contents is. + * + * @param useInverseBackground whether to use the inverse background + * @return this Builder object to allow for chaining of calls to set methods + * @deprecated This flag is only used for pre-Material themes. Instead, + * specify the window background using on the alert dialog + * theme. */ + @Deprecated public Builder setInverseBackgroundForced(boolean useInverseBackground) { P.mForceInverseBackground = useInverseBackground; return this; @@ -968,13 +1067,15 @@ public class AlertDialog extends Dialog implements DialogInterface { /** - * Creates a {@link AlertDialog} with the arguments supplied to this builder. It does not - * {@link Dialog#show()} the dialog. This allows the user to do any extra processing - * before displaying the dialog. Use {@link #show()} if you don't have any other processing - * to do and want this to be created and displayed. + * Creates an {@link AlertDialog} with the arguments supplied to this + * builder. + *
+ * Calling this method does not display the dialog. If no additional + * processing is needed, {@link #show()} may be called instead to both + * create and display the dialog. */ public AlertDialog create() { - final AlertDialog dialog = new AlertDialog(P.mContext, mTheme, false); + final AlertDialog dialog = new AlertDialog(P.mContext, mThemeResId); P.apply(dialog.mAlert); dialog.setCancelable(P.mCancelable); if (P.mCancelable) { @@ -989,14 +1090,20 @@ public class AlertDialog extends Dialog implements DialogInterface { } /** - * Creates a {@link AlertDialog} with the arguments supplied to this builder and - * {@link Dialog#show()}'s the dialog. + * Creates an {@link AlertDialog} with the arguments supplied to this + * builder and immediately displays the dialog. + *
+ * Calling this method is functionally identical to: + *
+ * AlertDialog dialog = builder.create(); + * dialog.show(); + **/ public AlertDialog show() { - AlertDialog dialog = create(); + final AlertDialog dialog = create(); dialog.show(); return dialog; } } - + } diff --git a/core/java/android/widget/CheckedTextView.java b/core/java/android/widget/CheckedTextView.java index 84f0ee556b2e5..22e079c175e8d 100644 --- a/core/java/android/widget/CheckedTextView.java +++ b/core/java/android/widget/CheckedTextView.java @@ -34,10 +34,13 @@ import android.view.accessibility.AccessibilityEvent; import android.view.accessibility.AccessibilityNodeInfo; /** - * An extension to TextView that supports the {@link android.widget.Checkable} interface. - * This is useful when used in a {@link android.widget.ListView ListView} where the it's - * {@link android.widget.ListView#setChoiceMode(int) setChoiceMode} has been set to - * something other than {@link android.widget.ListView#CHOICE_MODE_NONE CHOICE_MODE_NONE}. + * An extension to {@link TextView} that supports the {@link Checkable} + * interface and displays. + *
+ * This is useful when used in a {@link android.widget.ListView ListView} where + * the {@link android.widget.ListView#setChoiceMode(int) setChoiceMode} has + * been set to something other than + * {@link android.widget.ListView#CHOICE_MODE_NONE CHOICE_MODE_NONE}. * * @attr ref android.R.styleable#CheckedTextView_checked * @attr ref android.R.styleable#CheckedTextView_checkMark @@ -116,9 +119,10 @@ public class CheckedTextView extends TextView implements Checkable { } /** - *
Changes the checked state of this text view.
+ * Sets the checked state of this view. * - * @param checked true to check the text, false to uncheck it + * @param checked {@code true} set the state to checked, {@code false} to + * uncheck */ public void setChecked(boolean checked) { if (mChecked != checked) { @@ -129,24 +133,24 @@ public class CheckedTextView extends TextView implements Checkable { } } - /** - * Set the checkmark to a given Drawable, identified by its resourece id. This will be drawn - * when {@link #isChecked()} is true. - * - * @param resid The Drawable to use for the checkmark. + * Sets the check mark to the drawable with the specified resource ID. + *+ * When this view is checked, the drawable's state set will include + * {@link android.R.attr#state_checked}. * + * @param resId the resource identifier of drawable to use as the check + * mark + * @attr ref android.R.styleable#CheckedTextView_checkMark * @see #setCheckMarkDrawable(Drawable) * @see #getCheckMarkDrawable() - * - * @attr ref android.R.styleable#CheckedTextView_checkMark */ - public void setCheckMarkDrawable(@DrawableRes int resid) { - if (resid != 0 && resid == mCheckMarkResource) { + public void setCheckMarkDrawable(@DrawableRes int resId) { + if (resId != 0 && resId == mCheckMarkResource) { return; } - mCheckMarkResource = resid; + mCheckMarkResource = resId; Drawable d = null; if (mCheckMarkResource != 0) { @@ -156,14 +160,15 @@ public class CheckedTextView extends TextView implements Checkable { } /** - * Set the checkmark to a given Drawable. This will be drawn when {@link #isChecked()} is true. - * - * @param d The Drawable to use for the checkmark. + * Set the check mark to the specified drawable. + *
+ * When this view is checked, the drawable's state set will include
+ * {@link android.R.attr#state_checked}.
*
+ * @param d the drawable to use for the check mark
+ * @attr ref android.R.styleable#CheckedTextView_checkMark
* @see #setCheckMarkDrawable(int)
* @see #getCheckMarkDrawable()
- *
- * @attr ref android.R.styleable#CheckedTextView_checkMark
*/
public void setCheckMarkDrawable(Drawable d) {
if (mCheckMarkDrawable != null) {
diff --git a/core/res/res/values/public.xml b/core/res/res/values/public.xml
index af8ff413c8539..2cfdbb3700530 100644
--- a/core/res/res/values/public.xml
+++ b/core/res/res/values/public.xml
@@ -2634,6 +2634,7 @@