1 /* 2 * Copyright (C) 2021 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 17 package android.hardware.input; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.SystemApi; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 import android.os.SystemClock; 25 import android.view.InputEvent; 26 import android.view.KeyEvent; 27 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 31 /** 32 * An event describing a keyboard interaction originating from a remote device. 33 * 34 * When the user presses a key, an {@code ACTION_DOWN} event should be reported. When the user 35 * releases the key, an {@code ACTION_UP} event should be reported. 36 * 37 * See {@link android.view.KeyEvent}. 38 * 39 * @hide 40 */ 41 @SystemApi 42 public final class VirtualKeyEvent implements Parcelable { 43 44 /** @hide */ 45 public static final int ACTION_UNKNOWN = -1; 46 /** Action indicating the given key has been pressed. */ 47 public static final int ACTION_DOWN = KeyEvent.ACTION_DOWN; 48 /** Action indicating the previously pressed key has been lifted. */ 49 public static final int ACTION_UP = KeyEvent.ACTION_UP; 50 51 /** @hide */ 52 @IntDef(prefix = { "ACTION_" }, value = { 53 ACTION_UNKNOWN, 54 ACTION_DOWN, 55 ACTION_UP, 56 }) 57 @Retention(RetentionPolicy.SOURCE) 58 public @interface Action { 59 } 60 61 /** 62 * The set of allowed keycodes. 63 * @hide 64 */ 65 @IntDef(prefix = { "KEYCODE_" }, value = { 66 KeyEvent.KEYCODE_0, 67 KeyEvent.KEYCODE_1, 68 KeyEvent.KEYCODE_2, 69 KeyEvent.KEYCODE_3, 70 KeyEvent.KEYCODE_4, 71 KeyEvent.KEYCODE_5, 72 KeyEvent.KEYCODE_6, 73 KeyEvent.KEYCODE_7, 74 KeyEvent.KEYCODE_8, 75 KeyEvent.KEYCODE_9, 76 KeyEvent.KEYCODE_A, 77 KeyEvent.KEYCODE_B, 78 KeyEvent.KEYCODE_C, 79 KeyEvent.KEYCODE_D, 80 KeyEvent.KEYCODE_E, 81 KeyEvent.KEYCODE_F, 82 KeyEvent.KEYCODE_G, 83 KeyEvent.KEYCODE_H, 84 KeyEvent.KEYCODE_I, 85 KeyEvent.KEYCODE_J, 86 KeyEvent.KEYCODE_K, 87 KeyEvent.KEYCODE_L, 88 KeyEvent.KEYCODE_M, 89 KeyEvent.KEYCODE_N, 90 KeyEvent.KEYCODE_O, 91 KeyEvent.KEYCODE_P, 92 KeyEvent.KEYCODE_Q, 93 KeyEvent.KEYCODE_R, 94 KeyEvent.KEYCODE_S, 95 KeyEvent.KEYCODE_T, 96 KeyEvent.KEYCODE_U, 97 KeyEvent.KEYCODE_V, 98 KeyEvent.KEYCODE_W, 99 KeyEvent.KEYCODE_X, 100 KeyEvent.KEYCODE_Y, 101 KeyEvent.KEYCODE_Z, 102 KeyEvent.KEYCODE_F1, 103 KeyEvent.KEYCODE_F2, 104 KeyEvent.KEYCODE_F3, 105 KeyEvent.KEYCODE_F4, 106 KeyEvent.KEYCODE_F5, 107 KeyEvent.KEYCODE_F6, 108 KeyEvent.KEYCODE_F7, 109 KeyEvent.KEYCODE_F8, 110 KeyEvent.KEYCODE_F9, 111 KeyEvent.KEYCODE_F10, 112 KeyEvent.KEYCODE_F11, 113 KeyEvent.KEYCODE_F12, 114 KeyEvent.KEYCODE_NUMPAD_0, 115 KeyEvent.KEYCODE_NUMPAD_1, 116 KeyEvent.KEYCODE_NUMPAD_2, 117 KeyEvent.KEYCODE_NUMPAD_3, 118 KeyEvent.KEYCODE_NUMPAD_4, 119 KeyEvent.KEYCODE_NUMPAD_5, 120 KeyEvent.KEYCODE_NUMPAD_6, 121 KeyEvent.KEYCODE_NUMPAD_7, 122 KeyEvent.KEYCODE_NUMPAD_8, 123 KeyEvent.KEYCODE_NUMPAD_9, 124 KeyEvent.KEYCODE_NUMPAD_DIVIDE, 125 KeyEvent.KEYCODE_NUMPAD_MULTIPLY, 126 KeyEvent.KEYCODE_NUMPAD_SUBTRACT, 127 KeyEvent.KEYCODE_NUMPAD_ADD, 128 KeyEvent.KEYCODE_NUMPAD_DOT, 129 KeyEvent.KEYCODE_NUMPAD_COMMA, 130 KeyEvent.KEYCODE_NUMPAD_ENTER, 131 KeyEvent.KEYCODE_NUMPAD_EQUALS, 132 KeyEvent.KEYCODE_NUMPAD_LEFT_PAREN, 133 KeyEvent.KEYCODE_NUMPAD_RIGHT_PAREN, 134 KeyEvent.KEYCODE_GRAVE, 135 KeyEvent.KEYCODE_MINUS, 136 KeyEvent.KEYCODE_EQUALS, 137 KeyEvent.KEYCODE_LEFT_BRACKET, 138 KeyEvent.KEYCODE_RIGHT_BRACKET, 139 KeyEvent.KEYCODE_BACKSLASH, 140 KeyEvent.KEYCODE_SEMICOLON, 141 KeyEvent.KEYCODE_APOSTROPHE, 142 KeyEvent.KEYCODE_COMMA, 143 KeyEvent.KEYCODE_PERIOD, 144 KeyEvent.KEYCODE_SLASH, 145 KeyEvent.KEYCODE_ALT_LEFT, 146 KeyEvent.KEYCODE_ALT_RIGHT, 147 KeyEvent.KEYCODE_CTRL_LEFT, 148 KeyEvent.KEYCODE_CTRL_RIGHT, 149 KeyEvent.KEYCODE_SHIFT_LEFT, 150 KeyEvent.KEYCODE_SHIFT_RIGHT, 151 KeyEvent.KEYCODE_META_LEFT, 152 KeyEvent.KEYCODE_META_RIGHT, 153 KeyEvent.KEYCODE_CAPS_LOCK, 154 KeyEvent.KEYCODE_SCROLL_LOCK, 155 KeyEvent.KEYCODE_NUM_LOCK, 156 KeyEvent.KEYCODE_ENTER, 157 KeyEvent.KEYCODE_TAB, 158 KeyEvent.KEYCODE_SPACE, 159 KeyEvent.KEYCODE_DPAD_DOWN, 160 KeyEvent.KEYCODE_DPAD_UP, 161 KeyEvent.KEYCODE_DPAD_LEFT, 162 KeyEvent.KEYCODE_DPAD_RIGHT, 163 KeyEvent.KEYCODE_DPAD_CENTER, 164 KeyEvent.KEYCODE_MOVE_END, 165 KeyEvent.KEYCODE_MOVE_HOME, 166 KeyEvent.KEYCODE_PAGE_DOWN, 167 KeyEvent.KEYCODE_PAGE_UP, 168 KeyEvent.KEYCODE_DEL, 169 KeyEvent.KEYCODE_FORWARD_DEL, 170 KeyEvent.KEYCODE_INSERT, 171 KeyEvent.KEYCODE_ESCAPE, 172 KeyEvent.KEYCODE_BREAK, 173 KeyEvent.KEYCODE_BACK, 174 KeyEvent.KEYCODE_FORWARD, 175 KeyEvent.KEYCODE_LANGUAGE_SWITCH, 176 }) 177 @Retention(RetentionPolicy.SOURCE) 178 public @interface SupportedKeycode { 179 } 180 181 private final @Action int mAction; 182 private final int mKeyCode; 183 private final long mEventTimeNanos; 184 VirtualKeyEvent(@ction int action, int keyCode, long eventTimeNanos)185 private VirtualKeyEvent(@Action int action, int keyCode, long eventTimeNanos) { 186 mAction = action; 187 mKeyCode = keyCode; 188 mEventTimeNanos = eventTimeNanos; 189 } 190 VirtualKeyEvent(@onNull Parcel parcel)191 private VirtualKeyEvent(@NonNull Parcel parcel) { 192 mAction = parcel.readInt(); 193 mKeyCode = parcel.readInt(); 194 mEventTimeNanos = parcel.readLong(); 195 } 196 197 @Override writeToParcel(@onNull Parcel parcel, int parcelableFlags)198 public void writeToParcel(@NonNull Parcel parcel, int parcelableFlags) { 199 parcel.writeInt(mAction); 200 parcel.writeInt(mKeyCode); 201 parcel.writeLong(mEventTimeNanos); 202 } 203 204 @Override describeContents()205 public int describeContents() { 206 return 0; 207 } 208 209 @Override toString()210 public String toString() { 211 return "VirtualKeyEvent(" 212 + " action=" + KeyEvent.actionToString(mAction) 213 + " keyCode=" + KeyEvent.keyCodeToString(mKeyCode) 214 + " eventTime(ns)=" + mEventTimeNanos; 215 } 216 217 /** 218 * Returns the key code associated with this event. 219 */ getKeyCode()220 public int getKeyCode() { 221 return mKeyCode; 222 } 223 224 /** 225 * Returns the action associated with this event. 226 */ getAction()227 public @Action int getAction() { 228 return mAction; 229 } 230 231 /** 232 * Returns the time this event occurred, in the {@link SystemClock#uptimeMillis()} time base but 233 * with nanosecond (instead of millisecond) precision. 234 * 235 * @see InputEvent#getEventTime() 236 */ getEventTimeNanos()237 public long getEventTimeNanos() { 238 return mEventTimeNanos; 239 } 240 241 /** 242 * Builder for {@link VirtualKeyEvent}. 243 */ 244 public static final class Builder { 245 246 private @Action int mAction = ACTION_UNKNOWN; 247 private int mKeyCode = -1; 248 private long mEventTimeNanos = 0L; 249 250 /** 251 * Creates a {@link VirtualKeyEvent} object with the current builder configuration. 252 */ build()253 public @NonNull VirtualKeyEvent build() { 254 if (mAction == ACTION_UNKNOWN || mKeyCode == -1) { 255 throw new IllegalArgumentException( 256 "Cannot build virtual key event with unset fields"); 257 } 258 return new VirtualKeyEvent(mAction, mKeyCode, mEventTimeNanos); 259 } 260 261 /** 262 * Sets the Android key code of the event. 263 * 264 * @return this builder, to allow for chaining of calls 265 */ setKeyCode(@upportedKeycode int keyCode)266 public @NonNull Builder setKeyCode(@SupportedKeycode int keyCode) { 267 mKeyCode = keyCode; 268 return this; 269 } 270 271 /** 272 * Sets the action of the event. 273 * 274 * @return this builder, to allow for chaining of calls 275 */ setAction(@ction int action)276 public @NonNull Builder setAction(@Action int action) { 277 if (action != ACTION_DOWN && action != ACTION_UP) { 278 throw new IllegalArgumentException("Unsupported action type"); 279 } 280 mAction = action; 281 return this; 282 } 283 284 /** 285 * Sets the time (in nanoseconds) when this specific event was generated. This may be 286 * obtained from {@link SystemClock#uptimeMillis()} (with nanosecond precision instead of 287 * millisecond), but can be different depending on the use case. 288 * This field is optional and can be omitted. 289 * 290 * @return this builder, to allow for chaining of calls 291 * @see InputEvent#getEventTime() 292 */ setEventTimeNanos(long eventTimeNanos)293 public @NonNull Builder setEventTimeNanos(long eventTimeNanos) { 294 if (eventTimeNanos < 0L) { 295 throw new IllegalArgumentException("Event time cannot be negative"); 296 } 297 mEventTimeNanos = eventTimeNanos; 298 return this; 299 } 300 } 301 302 public static final @NonNull Parcelable.Creator<VirtualKeyEvent> CREATOR = 303 new Parcelable.Creator<VirtualKeyEvent>() { 304 public VirtualKeyEvent createFromParcel(Parcel source) { 305 return new VirtualKeyEvent(source); 306 } 307 308 public VirtualKeyEvent[] newArray(int size) { 309 return new VirtualKeyEvent[size]; 310 } 311 }; 312 } 313