KeyboardActionListener.java revision eea34598bf63f670f47d7b3f37b6436921e5fe02 
1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5 * use this file except in compliance with the License. You may obtain a copy of
6 * 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, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations under
14 * the License.
15 */
16
17package com.android.inputmethod.keyboard;
18
19import com.android.inputmethod.latin.InputPointers;
20import com.android.inputmethod.latin.SuggestedWords;
21
22public interface KeyboardActionListener {
23
24    /**
25     * Called when the user presses a key. This is sent before the {@link #onCodeInput} is called.
26     * For keys that repeat, this is only called once.
27     *
28     * @param primaryCode the unicode of the key being pressed. If the touch is not on a valid key,
29     *            the value will be zero.
30     */
31    public void onPressKey(int primaryCode);
32
33    /**
34     * Called when the user releases a key. This is sent after the {@link #onCodeInput} is called.
35     * For keys that repeat, this is only called once.
36     *
37     * @param primaryCode the code of the key that was released
38     * @param withSliding true if releasing has occurred because the user slid finger from the key
39     *             to other key without releasing the finger.
40     */
41    public void onReleaseKey(int primaryCode, boolean withSliding);
42
43    /**
44     * Send a key code to the listener.
45     *
46     * @param primaryCode this is the code of the key that was pressed
47     * @param x x-coordinate pixel of touched event. If {@link #onCodeInput} is not called by
48     *            {@link PointerTracker} or so, the value should be {@link #NOT_A_TOUCH_COORDINATE}.
49     *            If it's called on insertion from the suggestion strip, it should be
50     *            {@link #SUGGESTION_STRIP_COORDINATE}.
51     * @param y y-coordinate pixel of touched event. If {@link #onCodeInput} is not called by
52     *            {@link PointerTracker} or so, the value should be {@link #NOT_A_TOUCH_COORDINATE}.
53     *            If it's called on insertion from the suggestion strip, it should be
54     *            {@link #SUGGESTION_STRIP_COORDINATE}.
55     */
56    public void onCodeInput(int primaryCode, int x, int y);
57
58    // See {@link Adapter#isInvalidCoordinate(int)}.
59    public static final int NOT_A_TOUCH_COORDINATE = -1;
60    public static final int SUGGESTION_STRIP_COORDINATE = -2;
61    public static final int SPELL_CHECKER_COORDINATE = -3;
62
63    /**
64     * Sends a sequence of characters to the listener.
65     *
66     * @param text the sequence of characters to be displayed.
67     */
68    public void onTextInput(CharSequence text);
69
70    /**
71     * Called when user started batch input.
72     */
73    public void onStartBatchInput();
74
75    /**
76     * Sends the batch input points data to get updated suggestions
77     * @param batchPointers the batch input points representing the user input
78     * @return updated suggestions that reflects the user input
79     */
80    public SuggestedWords onUpdateBatchInput(InputPointers batchPointers);
81
82    /**
83     * Sends a sequence of characters to the listener as batch input.
84     *
85     * @param text the sequence of characters to be displayed as composing text.
86     */
87    public void onEndBatchInput(CharSequence text);
88
89    /**
90     * Called when user released a finger outside any key.
91     */
92    public void onCancelInput();
93
94    /**
95     * Send a non-"code input" custom request to the listener.
96     * @return true if the request has been consumed, false otherwise.
97     */
98    public boolean onCustomRequest(int requestCode);
99
100    public static class Adapter implements KeyboardActionListener {
101        @Override
102        public void onPressKey(int primaryCode) {}
103        @Override
104        public void onReleaseKey(int primaryCode, boolean withSliding) {}
105        @Override
106        public void onCodeInput(int primaryCode, int x, int y) {}
107        @Override
108        public void onTextInput(CharSequence text) {}
109        @Override
110        public void onStartBatchInput() {}
111        @Override
112        public SuggestedWords onUpdateBatchInput(InputPointers batchPointers) { return null; }
113        @Override
114        public void onEndBatchInput(CharSequence text) {}
115        @Override
116        public void onCancelInput() {}
117        @Override
118        public boolean onCustomRequest(int requestCode) {
119            return false;
120        }
121
122        // TODO: Remove this method when the vertical correction is removed.
123        public static boolean isInvalidCoordinate(int coordinate) {
124            // Detect {@link KeyboardActionListener#NOT_A_TOUCH_COORDINATE},
125            // {@link KeyboardActionListener#SUGGESTION_STRIP_COORDINATE}, and
126            // {@link KeyboardActionListener#SPELL_CHECKER_COORDINATE}.
127            return coordinate < 0;
128        }
129    }
130}
131