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
17package android.content;
18
19import 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 */
25public 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}
158