1 /* 2 * Copyright (C) 2024 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.FlaggedApi; 20 import android.annotation.FloatRange; 21 import android.annotation.NonNull; 22 import android.annotation.SystemApi; 23 import android.companion.virtualdevice.flags.Flags; 24 import android.os.Parcel; 25 import android.os.Parcelable; 26 import android.os.SystemClock; 27 import android.view.InputEvent; 28 29 import com.android.internal.util.Preconditions; 30 31 /** 32 * An event describing a rotary encoder scroll interaction originating from a remote device. 33 * 34 * @hide 35 */ 36 @FlaggedApi(Flags.FLAG_VIRTUAL_ROTARY) 37 @SystemApi 38 public final class VirtualRotaryEncoderScrollEvent implements Parcelable { 39 40 private final float mScrollAmount; 41 private final long mEventTimeNanos; 42 VirtualRotaryEncoderScrollEvent(float scrollAmount, long eventTimeNanos)43 private VirtualRotaryEncoderScrollEvent(float scrollAmount, long eventTimeNanos) { 44 mScrollAmount = scrollAmount; 45 mEventTimeNanos = eventTimeNanos; 46 } 47 VirtualRotaryEncoderScrollEvent(@onNull Parcel parcel)48 private VirtualRotaryEncoderScrollEvent(@NonNull Parcel parcel) { 49 mScrollAmount = parcel.readFloat(); 50 mEventTimeNanos = parcel.readLong(); 51 } 52 53 @Override writeToParcel(@onNull Parcel parcel, int parcelableFlags)54 public void writeToParcel(@NonNull Parcel parcel, int parcelableFlags) { 55 parcel.writeFloat(mScrollAmount); 56 parcel.writeLong(mEventTimeNanos); 57 } 58 59 @Override describeContents()60 public int describeContents() { 61 return 0; 62 } 63 64 @Override toString()65 public String toString() { 66 return "VirtualRotaryScrollEvent(" 67 + " scrollAmount=" + mScrollAmount 68 + " eventTime(ns)=" + mEventTimeNanos; 69 } 70 71 /** 72 * Returns the scroll amount, normalized from -1.0 to 1.0, inclusive. 73 * <p> 74 * Positive values indicate scrolling forward (e.g. down in a vertical list); negative values, 75 * backward. 76 * <p> 77 * Values of 1.0 or -1.0 represent the maximum supported scroll. 78 * </p> 79 */ getScrollAmount()80 public @FloatRange(from = -1.0f, to = 1.0f) float getScrollAmount() { 81 return mScrollAmount; 82 } 83 84 /** 85 * Returns the time this event occurred, in the {@link SystemClock#uptimeMillis()} time base but 86 * with nanosecond (instead of millisecond) precision. 87 * 88 * @see InputEvent#getEventTime() 89 */ getEventTimeNanos()90 public long getEventTimeNanos() { 91 return mEventTimeNanos; 92 } 93 94 /** 95 * Builder for {@link VirtualRotaryEncoderScrollEvent}. 96 */ 97 public static final class Builder { 98 99 @FloatRange(from = -1.0f, to = 1.0f) private float mScrollAmount = 0.0f; 100 private long mEventTimeNanos = 0L; 101 102 /** 103 * Creates a {@link VirtualRotaryEncoderScrollEvent} object with the current configuration. 104 */ build()105 public @NonNull VirtualRotaryEncoderScrollEvent build() { 106 return new VirtualRotaryEncoderScrollEvent(mScrollAmount, mEventTimeNanos); 107 } 108 109 /** 110 * Sets the scroll amount, normalized from -1.0 to 1.0, inclusive. By default, the scroll 111 * amount is 0, which results in no scroll. 112 * <p> 113 * Positive values indicate scrolling forward (e.g. down in a vertical list); negative 114 * values, backward. 115 * <p> 116 * Values of 1.0 or -1.0 represent the maximum supported scroll. 117 * </p> 118 * @return this builder, to allow for chaining of calls 119 */ setScrollAmount( @loatRangefrom = -1.0f, to = 1.0f) float scrollAmount)120 public @NonNull Builder setScrollAmount( 121 @FloatRange(from = -1.0f, to = 1.0f) float scrollAmount) { 122 Preconditions.checkArgumentInRange(scrollAmount, -1f, 1f, "scrollAmount"); 123 mScrollAmount = scrollAmount; 124 return this; 125 } 126 127 /** 128 * Sets the time (in nanoseconds) when this specific event was generated. This may be 129 * obtained from {@link SystemClock#uptimeMillis()} (with nanosecond precision instead of 130 * millisecond), but can be different depending on the use case. 131 * This field is optional and can be omitted. 132 * <p> 133 * If this field is unset, then the time at which this event is sent to the framework would 134 * be considered as the event time (even though 135 * {@link VirtualRotaryEncoderScrollEvent#getEventTimeNanos()}) would return {@code 0L}). 136 * 137 * @return this builder, to allow for chaining of calls 138 * @see InputEvent#getEventTime() 139 */ setEventTimeNanos(long eventTimeNanos)140 public @NonNull Builder setEventTimeNanos(long eventTimeNanos) { 141 if (eventTimeNanos < 0L) { 142 throw new IllegalArgumentException("Event time cannot be negative"); 143 } 144 mEventTimeNanos = eventTimeNanos; 145 return this; 146 } 147 } 148 149 public static final @NonNull Creator<VirtualRotaryEncoderScrollEvent> CREATOR = 150 new Creator<VirtualRotaryEncoderScrollEvent>() { 151 public VirtualRotaryEncoderScrollEvent createFromParcel(Parcel source) { 152 return new VirtualRotaryEncoderScrollEvent(source); 153 } 154 155 public VirtualRotaryEncoderScrollEvent[] newArray(int size) { 156 return new VirtualRotaryEncoderScrollEvent[size]; 157 } 158 }; 159 } 160