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 }) 176 @Retention(RetentionPolicy.SOURCE) 177 public @interface SupportedKeycode { 178 } 179 180 private final @Action int mAction; 181 private final int mKeyCode; 182 private final long mEventTimeNanos; 183 VirtualKeyEvent(@ction int action, int keyCode, long eventTimeNanos)184 private VirtualKeyEvent(@Action int action, int keyCode, long eventTimeNanos) { 185 mAction = action; 186 mKeyCode = keyCode; 187 mEventTimeNanos = eventTimeNanos; 188 } 189 VirtualKeyEvent(@onNull Parcel parcel)190 private VirtualKeyEvent(@NonNull Parcel parcel) { 191 mAction = parcel.readInt(); 192 mKeyCode = parcel.readInt(); 193 mEventTimeNanos = parcel.readLong(); 194 } 195 196 @Override writeToParcel(@onNull Parcel parcel, int parcelableFlags)197 public void writeToParcel(@NonNull Parcel parcel, int parcelableFlags) { 198 parcel.writeInt(mAction); 199 parcel.writeInt(mKeyCode); 200 parcel.writeLong(mEventTimeNanos); 201 } 202 203 @Override describeContents()204 public int describeContents() { 205 return 0; 206 } 207 208 /** 209 * Returns the key code associated with this event. 210 */ getKeyCode()211 public int getKeyCode() { 212 return mKeyCode; 213 } 214 215 /** 216 * Returns the action associated with this event. 217 */ getAction()218 public @Action int getAction() { 219 return mAction; 220 } 221 222 /** 223 * Returns the time this event occurred, in the {@link SystemClock#uptimeMillis()} time base but 224 * with nanosecond (instead of millisecond) precision. 225 * 226 * @see InputEvent#getEventTime() 227 */ getEventTimeNanos()228 public long getEventTimeNanos() { 229 return mEventTimeNanos; 230 } 231 232 /** 233 * Builder for {@link VirtualKeyEvent}. 234 */ 235 public static final class Builder { 236 237 private @Action int mAction = ACTION_UNKNOWN; 238 private int mKeyCode = -1; 239 private long mEventTimeNanos = 0L; 240 241 /** 242 * Creates a {@link VirtualKeyEvent} object with the current builder configuration. 243 */ build()244 public @NonNull VirtualKeyEvent build() { 245 if (mAction == ACTION_UNKNOWN || mKeyCode == -1) { 246 throw new IllegalArgumentException( 247 "Cannot build virtual key event with unset fields"); 248 } 249 return new VirtualKeyEvent(mAction, mKeyCode, mEventTimeNanos); 250 } 251 252 /** 253 * Sets the Android key code of the event. 254 * 255 * @return this builder, to allow for chaining of calls 256 */ setKeyCode(@upportedKeycode int keyCode)257 public @NonNull Builder setKeyCode(@SupportedKeycode int keyCode) { 258 mKeyCode = keyCode; 259 return this; 260 } 261 262 /** 263 * Sets the action of the event. 264 * 265 * @return this builder, to allow for chaining of calls 266 */ setAction(@ction int action)267 public @NonNull Builder setAction(@Action int action) { 268 if (action != ACTION_DOWN && action != ACTION_UP) { 269 throw new IllegalArgumentException("Unsupported action type"); 270 } 271 mAction = action; 272 return this; 273 } 274 275 /** 276 * Sets the time (in nanoseconds) when this specific event was generated. This may be 277 * obtained from {@link SystemClock#uptimeMillis()} (with nanosecond precision instead of 278 * millisecond), but can be different depending on the use case. 279 * This field is optional and can be omitted. 280 * 281 * @return this builder, to allow for chaining of calls 282 * @see InputEvent#getEventTime() 283 */ setEventTimeNanos(long eventTimeNanos)284 public @NonNull Builder setEventTimeNanos(long eventTimeNanos) { 285 if (eventTimeNanos < 0L) { 286 throw new IllegalArgumentException("Event time cannot be negative"); 287 } 288 mEventTimeNanos = eventTimeNanos; 289 return this; 290 } 291 } 292 293 public static final @NonNull Parcelable.Creator<VirtualKeyEvent> CREATOR = 294 new Parcelable.Creator<VirtualKeyEvent>() { 295 public VirtualKeyEvent createFromParcel(Parcel source) { 296 return new VirtualKeyEvent(source); 297 } 298 299 public VirtualKeyEvent[] newArray(int size) { 300 return new VirtualKeyEvent[size]; 301 } 302 }; 303 } 304