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      */
cancel()53     void cancel();
54 
55     /**
56      * Dismisses the dialog, invoking the {@link OnDismissListener}.
57      */
dismiss()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          */
onCancel(DialogInterface dialog)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          */
onDismiss(DialogInterface dialog)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          */
onShow(DialogInterface dialog)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          */
onClick(DialogInterface dialog, int which)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          */
onClick(DialogInterface dialog, int which, boolean isChecked)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          */
onKey(DialogInterface dialog, int keyCode, KeyEvent event)155         boolean onKey(DialogInterface dialog, int keyCode, KeyEvent event);
156     }
157 }
158