1/*
2 * Copyright (C) 2011 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 com.android.inputmethod.keyboard;
18
19import android.view.View;
20
21public interface MoreKeysPanel {
22    public interface Controller {
23        /**
24         * Add the {@link MoreKeysPanel} to the target view.
25         * @param panel the panel to be shown.
26         */
27        public void onShowMoreKeysPanel(final MoreKeysPanel panel);
28
29        /**
30         * Remove the current {@link MoreKeysPanel} from the target view.
31         * @param panel the panel to be dismissed.
32         */
33        public void onDismissMoreKeysPanel(final MoreKeysPanel panel);
34
35        /**
36         * Instructs the parent to cancel the panel (e.g., when entering a different input mode).
37         * @param panel the panel to be canceled.
38         */
39        public void onCancelMoreKeysPanel(final MoreKeysPanel panel);
40    }
41
42    public static final Controller EMPTY_CONTROLLER = new Controller() {
43        @Override
44        public void onShowMoreKeysPanel(final MoreKeysPanel panel) {}
45        @Override
46        public void onDismissMoreKeysPanel(final MoreKeysPanel panel) {}
47        @Override
48        public void onCancelMoreKeysPanel(final MoreKeysPanel panel) {}
49    };
50
51    /**
52     * Initializes the layout and event handling of this {@link MoreKeysPanel} and calls the
53     * controller's onShowMoreKeysPanel to add the panel's container view.
54     *
55     * @param parentView the parent view of this {@link MoreKeysPanel}
56     * @param controller the controller that can dismiss this {@link MoreKeysPanel}
57     * @param pointX x coordinate of this {@link MoreKeysPanel}
58     * @param pointY y coordinate of this {@link MoreKeysPanel}
59     * @param listener the listener that will receive keyboard action from this
60     * {@link MoreKeysPanel}.
61     */
62    // TODO: Currently the MoreKeysPanel is inside a container view that is added to the parent.
63    // Consider the simpler approach of placing the MoreKeysPanel itself into the parent view.
64    public void showMoreKeysPanel(View parentView, Controller controller, int pointX,
65            int pointY, KeyboardActionListener listener);
66
67    /**
68     * Dismisses the more keys panel and calls the controller's onDismissMoreKeysPanel to remove
69     * the panel's container view.
70     */
71    public void dismissMoreKeysPanel();
72
73    /**
74     * Process a move event on the more keys panel.
75     *
76     * @param x translated x coordinate of the touch point
77     * @param y translated y coordinate of the touch point
78     * @param pointerId pointer id touch point
79     * @param eventTime timestamp of touch point
80     */
81    public void onMoveEvent(final int x, final int y, final int pointerId, final long eventTime);
82
83    /**
84     * Process a down event on the more keys panel.
85     *
86     * @param x translated x coordinate of the touch point
87     * @param y translated y coordinate of the touch point
88     * @param pointerId pointer id touch point
89     * @param eventTime timestamp of touch point
90     */
91    public void onDownEvent(final int x, final int y, final int pointerId, final long eventTime);
92
93    /**
94     * Process an up event on the more keys panel.
95     *
96     * @param x translated x coordinate of the touch point
97     * @param y translated y coordinate of the touch point
98     * @param pointerId pointer id touch point
99     * @param eventTime timestamp of touch point
100     */
101    public void onUpEvent(final int x, final int y, final int pointerId, final long eventTime);
102
103    /**
104     * Translate X-coordinate of touch event to the local X-coordinate of this
105     * {@link MoreKeysPanel}.
106     *
107     * @param x the global X-coordinate
108     * @return the local X-coordinate to this {@link MoreKeysPanel}
109     */
110    public int translateX(int x);
111
112    /**
113     * Translate Y-coordinate of touch event to the local Y-coordinate of this
114     * {@link MoreKeysPanel}.
115     *
116     * @param y the global Y-coordinate
117     * @return the local Y-coordinate to this {@link MoreKeysPanel}
118     */
119    public int translateY(int y);
120
121    /**
122     * Return the view containing the more keys panel.
123     */
124    public View getContainerView();
125
126    /**
127     * Return whether the panel is currently being shown.
128     */
129    public boolean isShowingInParent();
130}
131