KeyDetector.java revision d6d0f6976ccb04570884b188175213bad2e5da61
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 android.util.Log; 20 21import java.util.Arrays; 22import java.util.List; 23 24public class KeyDetector { 25 private static final String TAG = KeyDetector.class.getSimpleName(); 26 private static final boolean DEBUG = false; 27 28 public static final int NOT_A_CODE = -1; 29 private static final int ADDITIONAL_PROXIMITY_CHAR_DELIMITER_CODE = 2; 30 31 private final int mKeyHysteresisDistanceSquared; 32 33 private Keyboard mKeyboard; 34 private int mCorrectionX; 35 private int mCorrectionY; 36 private boolean mProximityCorrectOn; 37 private int mProximityThresholdSquare; 38 39 // working area 40 private static final int MAX_NEARBY_KEYS = 12; 41 private final int[] mDistances = new int[MAX_NEARBY_KEYS]; 42 private final Key[] mNeighborKeys = new Key[MAX_NEARBY_KEYS]; 43 44 /** 45 * This class handles key detection. 46 * 47 * @param keyHysteresisDistance if the pointer movement distance is smaller than this, the 48 * movement will not been handled as meaningful movement. The unit is pixel. 49 */ 50 public KeyDetector(float keyHysteresisDistance) { 51 mKeyHysteresisDistanceSquared = (int)(keyHysteresisDistance * keyHysteresisDistance); 52 } 53 54 public void setKeyboard(Keyboard keyboard, float correctionX, float correctionY) { 55 if (keyboard == null) 56 throw new NullPointerException(); 57 mCorrectionX = (int)correctionX; 58 mCorrectionY = (int)correctionY; 59 mKeyboard = keyboard; 60 final int threshold = keyboard.mMostCommonKeyWidth; 61 mProximityThresholdSquare = threshold * threshold; 62 } 63 64 public int getKeyHysteresisDistanceSquared() { 65 return mKeyHysteresisDistanceSquared; 66 } 67 68 public int getTouchX(int x) { 69 return x + mCorrectionX; 70 } 71 72 public int getTouchY(int y) { 73 return y + mCorrectionY; 74 } 75 76 public Keyboard getKeyboard() { 77 if (mKeyboard == null) 78 throw new IllegalStateException("keyboard isn't set"); 79 return mKeyboard; 80 } 81 82 public void setProximityCorrectionEnabled(boolean enabled) { 83 mProximityCorrectOn = enabled; 84 } 85 86 public boolean isProximityCorrectionEnabled() { 87 return mProximityCorrectOn; 88 } 89 90 public void setProximityThreshold(int threshold) { 91 mProximityThresholdSquare = threshold * threshold; 92 } 93 94 public boolean alwaysAllowsSlidingInput() { 95 return false; 96 } 97 98 /** 99 * Computes maximum size of the array that can contain all nearby key codes returned by 100 * {@link #getNearbyCodes}. 101 * 102 * @return Returns maximum size of the array that can contain all nearby key codes returned 103 * by {@link #getNearbyCodes}. 104 */ 105 protected int getMaxNearbyKeys() { 106 return MAX_NEARBY_KEYS; 107 } 108 109 /** 110 * Allocates array that can hold all key codes returned by {@link #getNearbyCodes} 111 * method. The maximum size of the array should be computed by {@link #getMaxNearbyKeys}. 112 * 113 * @return Allocates and returns an array that can hold all key codes returned by 114 * {@link #getNearbyCodes} method. All elements in the returned array are 115 * initialized by {@link #NOT_A_CODE} value. 116 */ 117 public int[] newCodeArray() { 118 int[] codes = new int[getMaxNearbyKeys()]; 119 Arrays.fill(codes, NOT_A_CODE); 120 return codes; 121 } 122 123 private void initializeNearbyKeys() { 124 Arrays.fill(mDistances, Integer.MAX_VALUE); 125 Arrays.fill(mNeighborKeys, null); 126 } 127 128 /** 129 * Insert the key into nearby keys buffer and sort nearby keys by ascending order of distance. 130 * If the distance of two keys are the same, the key which the point is on should be considered 131 * as a closer one. 132 * 133 * @param key the key to be inserted into the nearby keys buffer. 134 * @param distance distance between the key's edge and user touched point. 135 * @param isOnKey true if the point is on the key. 136 * @return order of the key in the nearby buffer, 0 if it is the nearest key. 137 */ 138 private int sortNearbyKeys(Key key, int distance, boolean isOnKey) { 139 final int[] distances = mDistances; 140 final Key[] neighborKeys = mNeighborKeys; 141 for (int insertPos = 0; insertPos < distances.length; insertPos++) { 142 final int comparingDistance = distances[insertPos]; 143 if (distance < comparingDistance || (distance == comparingDistance && isOnKey)) { 144 final int nextPos = insertPos + 1; 145 if (nextPos < distances.length) { 146 System.arraycopy(distances, insertPos, distances, nextPos, 147 distances.length - nextPos); 148 System.arraycopy(neighborKeys, insertPos, neighborKeys, nextPos, 149 neighborKeys.length - nextPos); 150 } 151 distances[insertPos] = distance; 152 neighborKeys[insertPos] = key; 153 return insertPos; 154 } 155 } 156 return distances.length; 157 } 158 159 private void getNearbyKeyCodes(final int primaryCode, final int[] allCodes) { 160 final Key[] neighborKeys = mNeighborKeys; 161 final int maxCodesSize = allCodes.length; 162 163 // allCodes[0] should always have the key code even if it is a non-letter key. 164 if (neighborKeys[0] == null) { 165 allCodes[0] = NOT_A_CODE; 166 return; 167 } 168 169 int numCodes = 0; 170 for (int j = 0; j < neighborKeys.length && numCodes < maxCodesSize; j++) { 171 final Key key = neighborKeys[j]; 172 if (key == null) 173 break; 174 final int code = key.mCode; 175 // filter out a non-letter key from nearby keys 176 if (code < Keyboard.CODE_SPACE) 177 continue; 178 allCodes[numCodes++] = code; 179 } 180 if (maxCodesSize <= numCodes) { 181 return; 182 } 183 184 final int code = (primaryCode == NOT_A_CODE) ? allCodes[0] : primaryCode; 185 if (code == NOT_A_CODE) { 186 return; 187 } 188 final List<Integer> additionalChars = mKeyboard.getAdditionalProximityChars().get(code); 189 if (additionalChars == null || additionalChars.size() == 0) { 190 return; 191 } 192 int currentCodesSize = numCodes; 193 allCodes[numCodes++] = ADDITIONAL_PROXIMITY_CHAR_DELIMITER_CODE; 194 if (maxCodesSize <= numCodes) { 195 return; 196 } 197 // TODO: This is O(N^2). Assuming additionalChars.size() is up to 4 or 5. 198 for (int i = 0; i < additionalChars.size(); ++i) { 199 final int additionalChar = additionalChars.get(i); 200 boolean contains = false; 201 for (int j = 0; j < currentCodesSize; ++j) { 202 if (additionalChar == allCodes[j]) { 203 contains = true; 204 break; 205 } 206 } 207 if (!contains) { 208 allCodes[numCodes++] = additionalChar; 209 if (maxCodesSize <= numCodes) { 210 return; 211 } 212 } 213 } 214 } 215 216 /** 217 * Finds all possible nearby key codes around a touch event point and returns the nearest key. 218 * The algorithm to determine the nearby keys depends on the threshold set by 219 * {@link #setProximityThreshold(int)} and the mode set by 220 * {@link #setProximityCorrectionEnabled(boolean)}. 221 * 222 * @param x The x-coordinate of a touch point 223 * @param y The y-coordinate of a touch point 224 * @param allCodes All nearby key codes except functional key are returned in this array 225 */ 226 // TODO: Move this method to native code. 227 public void getNearbyCodes(int x, int y, final int[] allCodes) { 228 final int touchX = getTouchX(x); 229 final int touchY = getTouchY(y); 230 231 initializeNearbyKeys(); 232 Key primaryKey = null; 233 for (final Key key : mKeyboard.getNearestKeys(touchX, touchY)) { 234 final boolean isOnKey = key.isOnKey(touchX, touchY); 235 final int distance = key.squaredDistanceToEdge(touchX, touchY); 236 if (isOnKey || (mProximityCorrectOn && distance < mProximityThresholdSquare)) { 237 final int insertedPosition = sortNearbyKeys(key, distance, isOnKey); 238 if (insertedPosition == 0 && isOnKey) { 239 primaryKey = key; 240 } 241 } 242 } 243 244 getNearbyKeyCodes(primaryKey != null ? primaryKey.mCode : NOT_A_CODE, allCodes); 245 if (DEBUG) { 246 Log.d(TAG, "x=" + x + " y=" + y 247 + " primary=" + printableCode(primaryKey) 248 + " codes=" + printableCodes(allCodes)); 249 } 250 } 251 252 /** 253 * Detect the key whose hitbox the touch point is in. 254 * 255 * @param x The x-coordinate of a touch point 256 * @param y The y-coordinate of a touch point 257 * @return the key that the touch point hits. 258 */ 259 public Key detectHitKey(int x, int y) { 260 final int touchX = getTouchX(x); 261 final int touchY = getTouchY(y); 262 263 int minDistance = Integer.MAX_VALUE; 264 Key primaryKey = null; 265 for (final Key key: mKeyboard.getNearestKeys(touchX, touchY)) { 266 final boolean isOnKey = key.isOnKey(touchX, touchY); 267 final int distance = key.squaredDistanceToEdge(touchX, touchY); 268 // To take care of hitbox overlaps, we compare mCode here too. 269 if (primaryKey == null || distance < minDistance 270 || (distance == minDistance && isOnKey && key.mCode > primaryKey.mCode)) { 271 minDistance = distance; 272 primaryKey = key; 273 } 274 } 275 return primaryKey; 276 } 277 278 public static String printableCode(Key key) { 279 return key != null ? Keyboard.printableCode(key.mCode) : "none"; 280 } 281 282 public static String printableCodes(int[] codes) { 283 final StringBuilder sb = new StringBuilder(); 284 boolean addDelimiter = false; 285 for (final int code : codes) { 286 if (code == NOT_A_CODE) break; 287 if (code == ADDITIONAL_PROXIMITY_CHAR_DELIMITER_CODE) { 288 sb.append(" | "); 289 addDelimiter = false; 290 } else { 291 if (addDelimiter) sb.append(", "); 292 sb.append(Keyboard.printableCode(code)); 293 addDelimiter = true; 294 } 295 } 296 return "[" + sb + "]"; 297 } 298} 299