core/java/android/content/DialogInterface.java

   1 /*
   2  * Copyright (C) 2006 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.content;
  18
  19 import android.view.KeyEvent;
  20
  21 /**
  22  * Interface that defines a dialog-type class that can be shown, dismissed, or
  23  * canceled, and may have buttons that can be clicked.
  24  */
  25 public interface DialogInterface {
  26     /** The identifier for the positive button. */
  27     int BUTTON_POSITIVE = -1;
  28
  29     /** The identifier for the negative button. */
  30     int BUTTON_NEGATIVE = -2;
  31
  32     /** The identifier for the neutral button. */
  33     int BUTTON_NEUTRAL = -3;
  34
  35     /** @deprecated Use {@link #BUTTON_POSITIVE} */
  36     @Deprecated
  37     int BUTTON1 = BUTTON_POSITIVE;
  38
  39     /** @deprecated Use {@link #BUTTON_NEGATIVE} */
  40     @Deprecated
  41     int BUTTON2 = BUTTON_NEGATIVE;
  42
  43     /** @deprecated Use {@link #BUTTON_NEUTRAL} */
  44     @Deprecated
  45     int BUTTON3 = BUTTON_NEUTRAL;
  46
  47     /**
  48      * Cancels the dialog, invoking the {@link OnCancelListener}.
  49      * <p>
  50      * The {@link OnDismissListener} may also be called if cancellation
  51      * dismisses the dialog.
  52      */
  53     void cancel();
  54
  55     /**
  56      * Dismisses the dialog, invoking the {@link OnDismissListener}.
  57      */
  58     void dismiss();
  59
  60     /**
  61      * Interface used to allow the creator of a dialog to run some code when the
  62      * dialog is canceled.
  63      * <p>
  64      * This will only be called when the dialog is canceled, if the creator
  65      * needs to know when it is dismissed in general, use
  66      * {@link DialogInterface.OnDismissListener}.
  67      */
  68     interface OnCancelListener {
  69         /**
  70          * This method will be invoked when the dialog is canceled.
  71          *
  72          * @param dialog the dialog that was canceled will be passed into the
  73          *               method
  74          */
  75         void onCancel(DialogInterface dialog);
  76     }
  77
  78     /**
  79      * Interface used to allow the creator of a dialog to run some code when the
  80      * dialog is dismissed.
  81      */
  82     interface OnDismissListener {
  83         /**
  84          * This method will be invoked when the dialog is dismissed.
  85          *
  86          * @param dialog the dialog that was dismissed will be passed into the
  87          *               method
  88          */
  89         void onDismiss(DialogInterface dialog);
  90     }
  91
  92     /**
  93      * Interface used to allow the creator of a dialog to run some code when the
  94      * dialog is shown.
  95      */
  96     interface OnShowListener {
  97         /**
  98          * This method will be invoked when the dialog is shown.
  99          *
 100          * @param dialog the dialog that was shown will be passed into the
 101          *               method
 102          */
 103         void onShow(DialogInterface dialog);
 104     }
 105
 106     /**
 107      * Interface used to allow the creator of a dialog to run some code when an
 108      * item on the dialog is clicked.
 109      */
 110     interface OnClickListener {
 111         /**
 112          * This method will be invoked when a button in the dialog is clicked.
 113          *
 114          * @param dialog the dialog that received the click
 115          * @param which the button that was clicked (ex.
 116          *              {@link DialogInterface#BUTTON_POSITIVE}) or the position
 117          *              of the item clicked
 118          */
 119         void onClick(DialogInterface dialog, int which);
 120     }
 121
 122     /**
 123      * Interface used to allow the creator of a dialog to run some code when an
 124      * item in a multi-choice dialog is clicked.
 125      */
 126     interface OnMultiChoiceClickListener {
 127         /**
 128          * This method will be invoked when an item in the dialog is clicked.
 129          *
 130          * @param dialog the dialog where the selection was made
 131          * @param which the position of the item in the list that was clicked
 132          * @param isChecked {@code true} if the click checked the item, else
 133          *                  {@code false}
 134          */
 135         void onClick(DialogInterface dialog, int which, boolean isChecked);
 136     }
 137
 138     /**
 139      * Interface definition for a callback to be invoked when a key event is
 140      * dispatched to this dialog. The callback will be invoked before the key
 141      * event is given to the dialog.
 142      */
 143     interface OnKeyListener {
 144         /**
 145          * Called when a key is dispatched to a dialog. This allows listeners to
 146          * get a chance to respond before the dialog.
 147          *
 148          * @param dialog the dialog the key has been dispatched to
 149          * @param keyCode the code for the physical key that was pressed
 150          * @param event the KeyEvent object containing full information about
 151          *              the event
 152          * @return {@code true} if the listener has consumed the event,
 153          *         {@code false} otherwise
 154          */
 155         boolean onKey(DialogInterface dialog, int keyCode, KeyEvent event);
 156     }
 157 }