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