1 /* 2 * Copyright (C) 2020 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 package android.app.search; 17 18 import android.annotation.IntDef; 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.annotation.SystemApi; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 25 import java.lang.annotation.Retention; 26 import java.lang.annotation.RetentionPolicy; 27 import java.util.ArrayList; 28 import java.util.List; 29 import java.util.Objects; 30 31 /** 32 * A representation of an search target event. 33 * 34 * There are two types of events. First type of event correspends to the user interaction 35 * that happens on the search surface. (e.g., {@link #ACTION_TAP}. Second type of events 36 * correspends to the lifecycle event of the search surface {@link #ACTION_SURFACE_VISIBLE}. 37 * 38 * @hide 39 */ 40 @SystemApi 41 public final class SearchTargetEvent implements Parcelable { 42 43 /** 44 * @hide 45 */ 46 @IntDef(prefix = {"ACTION_"}, value = { 47 ACTION_SURFACE_VISIBLE, 48 ACTION_TAP, 49 ACTION_LONGPRESS, 50 ACTION_LAUNCH_TOUCH, 51 ACTION_LAUNCH_KEYBOARD_FOCUS, 52 ACTION_DRAGNDROP, 53 ACTION_SURFACE_INVISIBLE 54 }) 55 @Retention(RetentionPolicy.SOURCE) 56 public @interface ActionType {} 57 58 /** 59 * @hide 60 */ 61 @IntDef(prefix = {"FLAG_"}, value = { 62 FLAG_IME_SHOWN 63 }) 64 @Retention(RetentionPolicy.SOURCE) 65 public @interface FlagType {} 66 67 @NonNull 68 private final List<String> mTargetIds; 69 @Nullable 70 private final String mLocation; 71 @ActionType 72 private final int mAction; 73 @FlagType 74 private int mFlags; 75 76 /** 77 * IME was shown when event happened. 78 */ 79 public static final int FLAG_IME_SHOWN = 1 << 0; 80 81 82 /** 83 * Search container was opened. 84 */ 85 public static final int ACTION_SURFACE_VISIBLE = 1; 86 87 /** 88 * Constants that define tapping without closing the search surface. 89 */ 90 public static final int ACTION_TAP = 3; 91 92 /** 93 * Constants that define long pressing without closing the search surface. 94 */ 95 public static final int ACTION_LONGPRESS = 4; 96 97 /** 98 * Constants that define tapping on the touch target to launch. 99 */ 100 public static final int ACTION_LAUNCH_TOUCH = 5; 101 102 /** 103 * Constants that define tapping on the soft keyboard confirm or search to launch. 104 */ 105 public static final int ACTION_LAUNCH_KEYBOARD_FOCUS = 6; 106 107 /** 108 * Searcheable item was draged and dropped to another surface. 109 */ 110 public static final int ACTION_DRAGNDROP = 7; 111 112 /** 113 * Search container was closed. 114 */ 115 public static final int ACTION_SURFACE_INVISIBLE = 8; 116 SearchTargetEvent(@onNull List<String> targetIds, @Nullable String location, @ActionType int actionType, @FlagType int flags)117 private SearchTargetEvent(@NonNull List<String> targetIds, 118 @Nullable String location, 119 @ActionType int actionType, 120 @FlagType int flags) { 121 mTargetIds = Objects.requireNonNull(targetIds); 122 mLocation = location; 123 mAction = actionType; 124 mFlags = flags; 125 } 126 SearchTargetEvent(Parcel parcel)127 private SearchTargetEvent(Parcel parcel) { 128 mTargetIds = new ArrayList<>(); 129 parcel.readStringList(mTargetIds); 130 mLocation = parcel.readString(); 131 mAction = parcel.readInt(); 132 mFlags = parcel.readInt(); 133 } 134 135 /** 136 * Returns the primary search target with interaction. 137 */ 138 @NonNull getTargetId()139 public String getTargetId() { 140 return mTargetIds.get(0); 141 } 142 143 /** 144 * Returns the list of search targets with visualization change. 145 */ 146 @NonNull getTargetIds()147 public List<String> getTargetIds() { 148 return mTargetIds; 149 } 150 151 /** 152 * Returns the launch location. 153 */ 154 @Nullable getLaunchLocation()155 public String getLaunchLocation() { 156 return mLocation; 157 } 158 159 /** 160 * Returns the action type. 161 */ 162 @ActionType getAction()163 public int getAction() { 164 return mAction; 165 } 166 getFlags()167 public int getFlags() { 168 return mFlags; 169 } 170 171 @Override hashCode()172 public int hashCode() { 173 return mTargetIds.get(0).hashCode() + mAction; 174 } 175 176 @Override equals(@ullable Object o)177 public boolean equals(@Nullable Object o) { 178 if (!getClass().equals(o != null ? o.getClass() : null)) return false; 179 180 SearchTargetEvent other = (SearchTargetEvent) o; 181 return mTargetIds.equals(other.mTargetIds) 182 && mAction == other.mAction 183 && mFlags == other.mFlags 184 && mLocation == null ? other.mLocation == null : mLocation.equals(other.mLocation); 185 } 186 187 @Override describeContents()188 public int describeContents() { 189 return 0; 190 } 191 192 @Override writeToParcel(@onNull Parcel dest, int flags)193 public void writeToParcel(@NonNull Parcel dest, int flags) { 194 dest.writeStringList(mTargetIds); 195 dest.writeString(mLocation); 196 dest.writeInt(mAction); 197 dest.writeInt(mFlags); 198 } 199 200 public static final @NonNull Creator<SearchTargetEvent> CREATOR = 201 new Creator<SearchTargetEvent>() { 202 public SearchTargetEvent createFromParcel(Parcel parcel) { 203 return new SearchTargetEvent(parcel); 204 } 205 206 public SearchTargetEvent[] newArray(int size) { 207 return new SearchTargetEvent[size]; 208 } 209 }; 210 211 /** 212 * A builder for search target events. 213 * 214 * @hide 215 */ 216 @SystemApi 217 public static final class Builder { 218 @NonNull 219 private List<String> mTargetIds; 220 @Nullable 221 private String mLocation; 222 @ActionType 223 private int mAction; 224 private int mFlags; 225 226 /** 227 * @param id The target id that is associated with this event. 228 * @param actionType The event type 229 */ Builder(@onNull String id, @ActionType int actionType)230 public Builder(@NonNull String id, @ActionType int actionType) { 231 mTargetIds = new ArrayList<>(); 232 mTargetIds.add(id); 233 mAction = actionType; 234 } 235 236 /** 237 * @param ids The target ids that is associated with this event. 238 * @param actionType The event type 239 */ Builder(@onNull List<String> ids, @ActionType int actionType)240 public Builder(@NonNull List<String> ids, @ActionType int actionType) { 241 mTargetIds = ids; 242 mAction = actionType; 243 } 244 245 /** 246 * Sets the launch location. 247 */ 248 @NonNull setLaunchLocation(@ullable String location)249 public Builder setLaunchLocation(@Nullable String location) { 250 mLocation = location; 251 return this; 252 } 253 254 /** 255 * Sets the launch location. 256 */ 257 @NonNull setFlags(int flags)258 public Builder setFlags(int flags) { 259 mFlags = flags; 260 return this; 261 } 262 263 /** 264 * Builds a new event instance. 265 */ 266 @NonNull build()267 public SearchTargetEvent build() { 268 return new SearchTargetEvent(mTargetIds, mLocation, mAction, mFlags); 269 } 270 } 271 } 272