Mady Mellor | 238b9b6 | 2018-01-09 16:15:40 -0800 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2018 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 androidx.app.slice.widget; |
| 18 | |
| 19 | import android.support.annotation.IntDef; |
| 20 | import android.support.annotation.RestrictTo; |
| 21 | |
| 22 | /** |
| 23 | * Represents information associated with a logged event on {@link SliceView}. |
| 24 | * @hide |
| 25 | */ |
| 26 | @RestrictTo(RestrictTo.Scope.LIBRARY) |
| 27 | public class EventInfo { |
| 28 | |
| 29 | /** |
| 30 | * @hide |
| 31 | */ |
| 32 | @RestrictTo(RestrictTo.Scope.LIBRARY) |
| 33 | @IntDef({ |
| 34 | ROW_TYPE_SHORTCUT, ROW_TYPE_LIST, ROW_TYPE_GRID, ROW_TYPE_MESSAGING |
| 35 | }) |
| 36 | public @interface SliceRowType {} |
| 37 | |
| 38 | /** |
| 39 | * Indicates the slice is represented as a shortcut. |
| 40 | */ |
| 41 | public static final int ROW_TYPE_SHORTCUT = -1; |
| 42 | /** |
| 43 | * Indicates the row is represented in a list template. |
| 44 | */ |
| 45 | public static final int ROW_TYPE_LIST = 0; |
| 46 | /** |
| 47 | * Indicates the row is represented in a grid template. |
| 48 | */ |
| 49 | public static final int ROW_TYPE_GRID = 1; |
| 50 | /** |
| 51 | * Indicates the row is represented as a messaging template. |
| 52 | */ |
| 53 | public static final int ROW_TYPE_MESSAGING = 2; |
| 54 | |
| 55 | /** |
| 56 | * @hide |
| 57 | */ |
| 58 | @RestrictTo(RestrictTo.Scope.LIBRARY) |
| 59 | @IntDef({ |
| 60 | ACTION_TYPE_TOGGLE, ACTION_TYPE_BUTTON, ACTION_TYPE_SLIDER, ACTION_TYPE_CONTENT |
| 61 | }) |
| 62 | public @interface SliceActionType{} |
| 63 | |
| 64 | /** |
| 65 | * Indicates the event was an interaction with a toggle. Check {@link EventInfo#state} to |
| 66 | * see the new state of the toggle. |
| 67 | */ |
| 68 | public static final int ACTION_TYPE_TOGGLE = 0; |
| 69 | /** |
| 70 | * Indicates the event was an interaction with a button. Check {@link EventInfo#actionPosition} |
| 71 | * to see where on the card the button is placed. |
| 72 | */ |
| 73 | public static final int ACTION_TYPE_BUTTON = 1; |
| 74 | /** |
| 75 | * Indicates the event was an interaction with a slider. Check {@link EventInfo#state} to |
| 76 | * see the new state of the slider. |
| 77 | */ |
| 78 | public static final int ACTION_TYPE_SLIDER = 2; |
| 79 | /** |
| 80 | * Indicates the event was a tap on the entire row. |
| 81 | */ |
| 82 | public static final int ACTION_TYPE_CONTENT = 3; |
| 83 | |
| 84 | /** |
| 85 | * @hide |
| 86 | */ |
| 87 | @RestrictTo(RestrictTo.Scope.LIBRARY) |
| 88 | @IntDef({ |
| 89 | POSITION_START, POSITION_END, POSITION_CELL |
| 90 | }) |
| 91 | public @interface SliceButtonPosition{} |
| 92 | |
| 93 | /** |
| 94 | * Indicates the event was an interaction with a button positioned at the start of the row. |
| 95 | */ |
| 96 | public static final int POSITION_START = 0; |
| 97 | /** |
| 98 | * Indicates the event was an interaction with a button positioned at the end of the row, |
| 99 | * potentially grouped with other buttons. |
| 100 | */ |
| 101 | public static final int POSITION_END = 1; |
| 102 | /** |
| 103 | * Indicates the event was an interaction with a button positioned in a grid cell. |
| 104 | */ |
| 105 | public static final int POSITION_CELL = 2; |
| 106 | |
| 107 | /** |
| 108 | * Indicates the state of a toggle is off. |
| 109 | */ |
| 110 | public static final int STATE_OFF = 0; |
| 111 | /** |
| 112 | * Indicates the state of a toggle is on. |
| 113 | */ |
| 114 | public static final int STATE_ON = 1; |
| 115 | |
| 116 | /** |
| 117 | * The display mode of the slice being interacted with. |
| 118 | */ |
| 119 | public @SliceView.SliceMode int sliceMode; |
| 120 | /** |
| 121 | * The type of action that occurred. |
| 122 | */ |
| 123 | public @SliceActionType int actionType; |
| 124 | /** |
| 125 | * The template type of the row that was interacted with in the slice. |
| 126 | */ |
| 127 | public @SliceRowType int rowTemplateType; |
| 128 | /** |
| 129 | * Index of the row that was interacted with in the slice. |
| 130 | */ |
| 131 | public int rowIndex; |
| 132 | /** |
| 133 | * If multiple buttons are presented in this {@link #actionPosition} on the row, then this is |
| 134 | * the index of that button that was interacted with. For total number of actions |
| 135 | * see {@link #actionCount}. |
| 136 | * |
| 137 | * <p>If the {@link #actionPosition} is {@link #POSITION_CELL} the button is a cell within |
| 138 | * a grid, and this index would represent the cell position.</p> |
| 139 | * <p>If the {@link #actionPosition} is {@link #POSITION_END} there might be other buttons |
| 140 | * in the end position, and this index would represent the position.</p> |
| 141 | */ |
| 142 | public int actionIndex; |
| 143 | /** |
| 144 | * Total number of actions available in this row of the slice. |
| 145 | * |
| 146 | * <p>If the {@link #actionPosition} is {@link #POSITION_CELL} the button is a cell within |
| 147 | * a grid row, and this is the number of cells in the row.</p> |
| 148 | * <p>If the {@link #actionPosition} is {@link #POSITION_END} this is the number of buttons |
| 149 | * in the end position of this row.</p> |
| 150 | */ |
| 151 | public int actionCount; |
| 152 | /** |
| 153 | * Position of the button on the template. |
| 154 | * |
| 155 | * {@link #POSITION_START} |
| 156 | * {@link #POSITION_END} |
| 157 | * {@link #POSITION_CELL} |
| 158 | */ |
| 159 | public @SliceButtonPosition int actionPosition; |
| 160 | /** |
| 161 | * Represents the state after the event or -1 if not applicable for the event type. |
| 162 | * |
| 163 | * <p>For {@link #ACTION_TYPE_TOGGLE} events, the state will be either {@link #STATE_OFF} |
| 164 | * or {@link #STATE_ON}.</p> |
| 165 | * <p>For {@link #ACTION_TYPE_SLIDER} events, the state will be a number representing |
| 166 | * the new position of the slider.</p> |
| 167 | */ |
| 168 | public int state; |
| 169 | |
| 170 | /** |
| 171 | * Constructs an event info object with the required information for an event. |
| 172 | * |
| 173 | * @param sliceMode The display mode of the slice interacted with. |
| 174 | * @param actionType The type of action this event represents. |
| 175 | * @param rowTemplateType The template type of the row interacted with. |
| 176 | * @param rowIndex The index of the row that was interacted with in the slice. |
| 177 | */ |
| 178 | public EventInfo(@SliceView.SliceMode int sliceMode, @SliceActionType int actionType, |
| 179 | @SliceRowType int rowTemplateType, int rowIndex) { |
| 180 | this.sliceMode = sliceMode; |
| 181 | this.actionType = actionType; |
| 182 | this.rowTemplateType = rowTemplateType; |
| 183 | this.rowIndex = rowIndex; |
| 184 | |
| 185 | this.actionPosition = -1; |
| 186 | this.actionIndex = -1; |
| 187 | this.actionCount = -1; |
| 188 | this.state = -1; |
| 189 | } |
| 190 | |
| 191 | /** |
| 192 | * Sets positional information for the event. |
| 193 | * |
| 194 | * @param actionPosition The position of the button on the template. |
| 195 | * @param actionIndex The index of that button that was interacted with. |
| 196 | * @param actionCount The number of actions available in this group of buttons on the slice. |
| 197 | */ |
| 198 | public void setPosition(@SliceButtonPosition int actionPosition, int actionIndex, |
| 199 | int actionCount) { |
| 200 | this.actionPosition = actionPosition; |
| 201 | this.actionIndex = actionIndex; |
| 202 | this.actionCount = actionCount; |
| 203 | } |
| 204 | |
| 205 | @Override |
| 206 | public String toString() { |
| 207 | StringBuilder sb = new StringBuilder(); |
| 208 | sb.append("mode=").append(SliceView.modeToString(sliceMode)); |
| 209 | sb.append(", actionType=").append(actionToString(actionType)); |
| 210 | sb.append(", rowTemplateType=").append(rowTypeToString(rowTemplateType)); |
| 211 | sb.append(", rowIndex=").append(rowIndex); |
| 212 | sb.append(", actionPosition=").append(positionToString(actionPosition)); |
| 213 | sb.append(", actionIndex=").append(actionIndex); |
| 214 | sb.append(", actionCount=").append(actionCount); |
| 215 | sb.append(", state=").append(state); |
| 216 | return sb.toString(); |
| 217 | } |
| 218 | |
| 219 | /** |
| 220 | * @return String representation of the provided position. |
| 221 | */ |
| 222 | private static String positionToString(@SliceButtonPosition int position) { |
| 223 | switch (position) { |
| 224 | case POSITION_START: |
| 225 | return "START"; |
| 226 | case POSITION_END: |
| 227 | return "END"; |
| 228 | case POSITION_CELL: |
| 229 | return "CELL"; |
| 230 | default: |
| 231 | return "unknown position: " + position; |
| 232 | } |
| 233 | } |
| 234 | |
| 235 | /** |
| 236 | * @return String representation of the provided action. |
| 237 | */ |
| 238 | private static String actionToString(@SliceActionType int action) { |
| 239 | switch (action) { |
| 240 | case ACTION_TYPE_TOGGLE: |
| 241 | return "TOGGLE"; |
| 242 | case ACTION_TYPE_BUTTON: |
| 243 | return "BUTTON"; |
| 244 | case ACTION_TYPE_SLIDER: |
| 245 | return "SLIDER"; |
| 246 | case ACTION_TYPE_CONTENT: |
| 247 | return "CONTENT"; |
| 248 | default: |
| 249 | return "unknown action: " + action; |
| 250 | } |
| 251 | } |
| 252 | |
| 253 | /** |
| 254 | * @return String representation of the provided row template type. |
| 255 | */ |
| 256 | private static String rowTypeToString(@SliceRowType int type) { |
| 257 | switch (type) { |
| 258 | case ROW_TYPE_LIST: |
| 259 | return "LIST"; |
| 260 | case ROW_TYPE_GRID: |
| 261 | return "GRID"; |
| 262 | case ROW_TYPE_MESSAGING: |
| 263 | return "MESSAGING"; |
| 264 | case ROW_TYPE_SHORTCUT: |
| 265 | return "SHORTCUT"; |
| 266 | default: |
| 267 | return "unknown row type: " + type; |
| 268 | } |
| 269 | } |
| 270 | } |