1 /* 2 * Copyright (C) 2015 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.view; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.graphics.Matrix; 22 import android.graphics.Rect; 23 import android.os.Bundle; 24 import android.os.LocaleList; 25 import android.util.Pair; 26 import android.view.View.AutofillImportance; 27 import android.view.ViewStructure.HtmlInfo; 28 import android.view.autofill.AutofillId; 29 import android.view.autofill.AutofillValue; 30 31 import com.android.internal.util.Preconditions; 32 33 import java.util.List; 34 35 /** 36 * Container for storing additional per-view data generated by {@link View#onProvideStructure 37 * View.onProvideStructure} and {@link View#onProvideAutofillStructure 38 * View.onProvideAutofillStructure}. 39 */ 40 public abstract class ViewStructure { 41 42 /** 43 * Set the identifier for this view. 44 * 45 * @param id The view's identifier, as per {@link View#getId View.getId()}. 46 * @param packageName The package name of the view's identifier, or null if there is none. 47 * @param typeName The type name of the view's identifier, or null if there is none. 48 * @param entryName The entry name of the view's identifier, or null if there is none. 49 */ setId(int id, String packageName, String typeName, String entryName)50 public abstract void setId(int id, String packageName, String typeName, String entryName); 51 52 /** 53 * Set the basic dimensions of this view. 54 * 55 * @param left The view's left position, in pixels relative to its parent's left edge. 56 * @param top The view's top position, in pixels relative to its parent's top edge. 57 * @param scrollX How much the view's x coordinate space has been scrolled, in pixels. 58 * @param scrollY How much the view's y coordinate space has been scrolled, in pixels. 59 * @param width The view's visible width, in pixels. This is the width visible on screen, 60 * not the total data width of a scrollable view. 61 * @param height The view's visible height, in pixels. This is the height visible on 62 * screen, not the total data height of a scrollable view. 63 */ setDimens(int left, int top, int scrollX, int scrollY, int width, int height)64 public abstract void setDimens(int left, int top, int scrollX, int scrollY, int width, 65 int height); 66 67 /** 68 * Set the transformation matrix associated with this view, as per 69 * {@link View#getMatrix View.getMatrix()}, or null if there is none. 70 */ setTransformation(Matrix matrix)71 public abstract void setTransformation(Matrix matrix); 72 73 /** 74 * Set the visual elevation (shadow) of the view, as per 75 * {@link View#getZ View.getZ()}. Note this is <em>not</em> related 76 * to the physical Z-ordering of this view relative to its other siblings (that is how 77 * they overlap when drawing), it is only the visual representation for shadowing. 78 */ setElevation(float elevation)79 public abstract void setElevation(float elevation); 80 81 /** 82 * Set an alpha transformation that is applied to this view, as per 83 * {@link View#getAlpha View.getAlpha()}. Value ranges from 0 84 * (completely transparent) to 1 (completely opaque); the default is 1, which means 85 * no transformation. 86 */ setAlpha(float alpha)87 public abstract void setAlpha(float alpha); 88 89 /** 90 * Set the visibility state of this view, as per 91 * {@link View#getVisibility View.getVisibility()}. 92 */ setVisibility(int visibility)93 public abstract void setVisibility(int visibility); 94 95 /** @hide */ setAssistBlocked(boolean state)96 public abstract void setAssistBlocked(boolean state); 97 98 /** 99 * Set the enabled state of this view, as per {@link View#isEnabled View.isEnabled()}. 100 */ setEnabled(boolean state)101 public abstract void setEnabled(boolean state); 102 103 /** 104 * Set the clickable state of this view, as per {@link View#isClickable View.isClickable()}. 105 */ setClickable(boolean state)106 public abstract void setClickable(boolean state); 107 108 /** 109 * Set the long clickable state of this view, as per 110 * {@link View#isLongClickable View.isLongClickable()}. 111 */ setLongClickable(boolean state)112 public abstract void setLongClickable(boolean state); 113 114 /** 115 * Set the context clickable state of this view, as per 116 * {@link View#isContextClickable View.isContextClickable()}. 117 */ setContextClickable(boolean state)118 public abstract void setContextClickable(boolean state); 119 120 /** 121 * Set the focusable state of this view, as per {@link View#isFocusable View.isFocusable()}. 122 */ setFocusable(boolean state)123 public abstract void setFocusable(boolean state); 124 125 /** 126 * Set the focused state of this view, as per {@link View#isFocused View.isFocused()}. 127 */ setFocused(boolean state)128 public abstract void setFocused(boolean state); 129 130 /** 131 * Set the accessibility focused state of this view, as per 132 * {@link View#isAccessibilityFocused View.isAccessibilityFocused()}. 133 */ setAccessibilityFocused(boolean state)134 public abstract void setAccessibilityFocused(boolean state); 135 136 /** 137 * Set the checkable state of this view, such as whether it implements the 138 * {@link android.widget.Checkable} interface. 139 */ setCheckable(boolean state)140 public abstract void setCheckable(boolean state); 141 142 /** 143 * Set the checked state of this view, such as 144 * {@link android.widget.Checkable#isChecked Checkable.isChecked()}. 145 */ setChecked(boolean state)146 public abstract void setChecked(boolean state); 147 148 /** 149 * Set the selected state of this view, as per {@link View#isSelected View.isSelected()}. 150 */ setSelected(boolean state)151 public abstract void setSelected(boolean state); 152 153 /** 154 * Set the activated state of this view, as per {@link View#isActivated View.isActivated()}. 155 */ setActivated(boolean state)156 public abstract void setActivated(boolean state); 157 158 /** 159 * Set the opaque state of this view, as per {@link View#isOpaque View.isOpaque()}. 160 */ setOpaque(boolean opaque)161 public abstract void setOpaque(boolean opaque); 162 163 /** 164 * Set the class name of the view, as per 165 * {@link View#getAccessibilityClassName View.getAccessibilityClassName()}. 166 */ setClassName(String className)167 public abstract void setClassName(String className); 168 169 /** 170 * Set the content description of the view, as per 171 * {@link View#getContentDescription View.getContentDescription()}. 172 */ setContentDescription(CharSequence contentDescription)173 public abstract void setContentDescription(CharSequence contentDescription); 174 175 /** 176 * Set the text that is associated with this view. There is no selection 177 * associated with the text. The text may have style spans to supply additional 178 * display and semantic information. 179 */ setText(CharSequence text)180 public abstract void setText(CharSequence text); 181 182 /** 183 * Like {@link #setText(CharSequence)} but with an active selection 184 * extending from <var>selectionStart</var> through <var>selectionEnd</var>. 185 */ setText(CharSequence text, int selectionStart, int selectionEnd)186 public abstract void setText(CharSequence text, int selectionStart, int selectionEnd); 187 188 /** 189 * Explicitly set default global style information for text that was previously set with 190 * {@link #setText}. 191 * 192 * @param size The size, in pixels, of the text. 193 * @param fgColor The foreground color, packed as 0xAARRGGBB. 194 * @param bgColor The background color, packed as 0xAARRGGBB. 195 * @param style Style flags, as defined by {@link android.app.assist.AssistStructure.ViewNode}. 196 */ setTextStyle(float size, int fgColor, int bgColor, int style)197 public abstract void setTextStyle(float size, int fgColor, int bgColor, int style); 198 199 /** 200 * Set line information for test that was previously supplied through 201 * {@link #setText(CharSequence)}. This provides the line breaking of the text as it 202 * is shown on screen. This function takes ownership of the provided arrays; you should 203 * not make further modification to them. 204 * 205 * @param charOffsets The offset in to {@link #setText} where a line starts. 206 * @param baselines The baseline where the line is drawn on screen. 207 */ setTextLines(int[] charOffsets, int[] baselines)208 public abstract void setTextLines(int[] charOffsets, int[] baselines); 209 210 /** 211 * Sets the identifier used to set the text associated with this view. 212 * 213 * <p>Should only be set when the node is used for autofill purposes - it will be ignored 214 * when used for Assist. 215 */ setTextIdEntry(@onNull String entryName)216 public void setTextIdEntry(@NonNull String entryName) { 217 Preconditions.checkNotNull(entryName); 218 } 219 220 /** 221 * Set optional hint text associated with this view; this is for example the text that is 222 * shown by an EditText when it is empty to indicate to the user the kind of text to input. 223 */ setHint(CharSequence hint)224 public abstract void setHint(CharSequence hint); 225 226 /** 227 * Retrieve the last {@link #setText(CharSequence)}. 228 */ getText()229 public abstract CharSequence getText(); 230 231 /** 232 * Retrieve the last selection start set by {@link #setText(CharSequence, int, int)}. 233 */ getTextSelectionStart()234 public abstract int getTextSelectionStart(); 235 236 /** 237 * Retrieve the last selection end set by {@link #setText(CharSequence, int, int)}. 238 */ getTextSelectionEnd()239 public abstract int getTextSelectionEnd(); 240 241 /** 242 * Retrieve the last hint set by {@link #setHint}. 243 */ getHint()244 public abstract CharSequence getHint(); 245 246 /** 247 * Get extra data associated with this view structure; the returned Bundle is mutable, 248 * allowing you to view and modify its contents. Keys placed in the Bundle should use 249 * an appropriate namespace prefix (such as com.google.MY_KEY) to avoid conflicts. 250 */ getExtras()251 public abstract Bundle getExtras(); 252 253 /** 254 * Returns true if {@link #getExtras} has been used to create extra content. 255 */ hasExtras()256 public abstract boolean hasExtras(); 257 258 /** 259 * Set the number of children of this view, which defines the range of indices you can 260 * use with {@link #newChild} and {@link #asyncNewChild}. Calling this method again 261 * resets all of the child state of the view, removing any children that had previously 262 * been added. 263 */ setChildCount(int num)264 public abstract void setChildCount(int num); 265 266 /** 267 * Add to this view's child count. This increases the current child count by 268 * <var>num</var> children beyond what was last set by {@link #setChildCount} 269 * or {@link #addChildCount}. The index at which the new child starts in the child 270 * array is returned. 271 * 272 * @param num The number of new children to add. 273 * @return Returns the index in the child array at which the new children start. 274 */ addChildCount(int num)275 public abstract int addChildCount(int num); 276 277 /** 278 * Return the child count as set by {@link #setChildCount}. 279 */ getChildCount()280 public abstract int getChildCount(); 281 282 /** 283 * Create a new child {@link ViewStructure} in this view, putting into the list of 284 * children at <var>index</var>. 285 * 286 * <p><b>NOTE: </b>you must pre-allocate space for the child first, by calling either 287 * {@link #addChildCount(int)} or {@link #setChildCount(int)}. 288 * 289 * @return Returns an fresh {@link ViewStructure} ready to be filled in. 290 */ newChild(int index)291 public abstract ViewStructure newChild(int index); 292 293 /** 294 * Like {@link #newChild}, but allows the caller to asynchronously populate the returned 295 * child. It can transfer the returned {@link ViewStructure} to another thread for it 296 * to build its content (and children etc). Once done, some thread must call 297 * {@link #asyncCommit} to tell the containing {@link ViewStructure} that the async 298 * population is done. 299 * 300 * <p><b>NOTE: </b>you must pre-allocate space for the child first, by calling either 301 * {@link #addChildCount(int)} or {@link #setChildCount(int)}. 302 * 303 * @return Returns an fresh {@link ViewStructure} ready to be filled in. 304 */ asyncNewChild(int index)305 public abstract ViewStructure asyncNewChild(int index); 306 307 /** 308 * Gets the {@link AutofillId} associated with this node. 309 */ 310 @Nullable getAutofillId()311 public abstract AutofillId getAutofillId(); 312 313 /** 314 * Sets the {@link AutofillId} associated with this node. 315 */ setAutofillId(@onNull AutofillId id)316 public abstract void setAutofillId(@NonNull AutofillId id); 317 318 /** 319 * Sets the {@link AutofillId} for this virtual node. 320 * 321 * @param parentId id of the parent node. 322 * @param virtualId an opaque ID to the Android System; it's the same id used on 323 * {@link View#autofill(android.util.SparseArray)}. 324 */ setAutofillId(@onNull AutofillId parentId, int virtualId)325 public abstract void setAutofillId(@NonNull AutofillId parentId, int virtualId); 326 327 /** 328 * Sets the {@link View#getAutofillType()} that can be used to autofill this node. 329 */ setAutofillType(@iew.AutofillType int type)330 public abstract void setAutofillType(@View.AutofillType int type); 331 332 /** 333 * Sets the a hints that helps the autofill service to select the appropriate data to fill the 334 * view. 335 */ setAutofillHints(@ullable String[] hint)336 public abstract void setAutofillHints(@Nullable String[] hint); 337 338 /** 339 * Sets the {@link AutofillValue} representing the current value of this node. 340 */ setAutofillValue(AutofillValue value)341 public abstract void setAutofillValue(AutofillValue value); 342 343 /** 344 * Sets the options that can be used to autofill this node. 345 * 346 * <p>Typically used by nodes whose {@link View#getAutofillType()} is a list to indicate the 347 * meaning of each possible value in the list. 348 */ setAutofillOptions(CharSequence[] options)349 public abstract void setAutofillOptions(CharSequence[] options); 350 351 /** 352 * Sets the {@link View#setImportantForAutofill(int) importantForAutofill mode} of the 353 * view associated with this node. 354 */ setImportantForAutofill(@utofillImportance int mode)355 public void setImportantForAutofill(@AutofillImportance int mode) {} 356 357 /** 358 * Sets the {@link android.text.InputType} bits of this node. 359 * 360 * @param inputType inputType bits as defined by {@link android.text.InputType}. 361 */ setInputType(int inputType)362 public abstract void setInputType(int inputType); 363 364 /** 365 * Sets whether the data on this node is sensitive; if it is, then its content (text, autofill 366 * value, etc..) is striped before calls to {@link 367 * android.service.autofill.AutofillService#onFillRequest(android.service.autofill.FillRequest, 368 * android.os.CancellationSignal, android.service.autofill.FillCallback)}. 369 * 370 * <p>By default, all nodes are assumed to be sensitive, and only nodes that does not have PII 371 * (Personally Identifiable Information - sensitive data such as email addresses, credit card 372 * numbers, passwords, etc...) should be marked as non-sensitive; a good rule of thumb is to 373 * mark as non-sensitive nodes whose value were statically set from resources. 374 * 375 * <p>Notice that the content of even sensitive nodes are sent to the service (through the 376 * {@link 377 * android.service.autofill.AutofillService#onSaveRequest(android.service.autofill.SaveRequest, 378 * android.service.autofill.SaveCallback)} call) when the user consented to save 379 * thedata, so it is important to set the content of sensitive nodes as well, but mark them as 380 * sensitive. 381 * 382 * <p>Should only be set when the node is used for autofill purposes - it will be ignored 383 * when used for Assist. 384 */ setDataIsSensitive(boolean sensitive)385 public abstract void setDataIsSensitive(boolean sensitive); 386 387 /** 388 * Sets the minimum width in ems of the text associated with this view, when supported. 389 * 390 * <p>Should only be set when the node is used for autofill purposes - it will be ignored 391 * when used for Assist. 392 */ setMinTextEms(@uppressWarnings"unused") int minEms)393 public void setMinTextEms(@SuppressWarnings("unused") int minEms) {} 394 395 /** 396 * Sets the maximum width in ems of the text associated with this view, when supported. 397 * 398 * <p>Should only be set when the node is used for autofill purposes - it will be ignored 399 * when used for Assist. 400 */ setMaxTextEms(@uppressWarnings"unused") int maxEms)401 public void setMaxTextEms(@SuppressWarnings("unused") int maxEms) {} 402 403 /** 404 * Sets the maximum length of the text associated with this view, when supported. 405 * 406 * <p>Should only be set when the node is used for autofill purposes - it will be ignored 407 * when used for Assist. 408 */ setMaxTextLength(@uppressWarnings"unused") int maxLength)409 public void setMaxTextLength(@SuppressWarnings("unused") int maxLength) {} 410 411 /** 412 * Call when done populating a {@link ViewStructure} returned by 413 * {@link #asyncNewChild}. 414 */ asyncCommit()415 public abstract void asyncCommit(); 416 417 /** @hide */ getTempRect()418 public abstract Rect getTempRect(); 419 420 /** 421 * Sets the Web domain represented by this node. 422 * 423 * <p>Typically used when the view is a container for an HTML document. 424 * 425 * @param domain RFC 2396-compliant URI representing the domain. 426 */ setWebDomain(@ullable String domain)427 public abstract void setWebDomain(@Nullable String domain); 428 429 /** 430 * Sets the the list of locales associated with this node. 431 */ setLocaleList(LocaleList localeList)432 public abstract void setLocaleList(LocaleList localeList); 433 434 /** 435 * Creates a new {@link HtmlInfo.Builder} for the given HTML tag. 436 * 437 * @param tagName name of the HTML tag. 438 * @return a new builder. 439 */ newHtmlInfoBuilder(@onNull String tagName)440 public abstract HtmlInfo.Builder newHtmlInfoBuilder(@NonNull String tagName); 441 442 /** 443 * Sets the HTML properties of this node when it represents an HTML element. 444 * 445 * <p>Should only be set when the node is used for autofill purposes - it will be ignored 446 * when used for assist. 447 * 448 * @param htmlInfo HTML properties. 449 */ setHtmlInfo(@onNull HtmlInfo htmlInfo)450 public abstract void setHtmlInfo(@NonNull HtmlInfo htmlInfo); 451 452 /** 453 * Simplified representation of the HTML properties of a node that represents an HTML element. 454 */ 455 public abstract static class HtmlInfo { 456 457 /** 458 * Gets the HTML tag. 459 */ 460 @NonNull getTag()461 public abstract String getTag(); 462 463 /** 464 * Gets the list of HTML attributes. 465 * 466 * @return list of key/value pairs; could contain pairs with the same keys. 467 */ 468 @Nullable getAttributes()469 public abstract List<Pair<String, String>> getAttributes(); 470 471 /** 472 * Builder for {@link HtmlInfo} objects. 473 */ 474 public abstract static class Builder { 475 476 /** 477 * Adds an HTML attribute. 478 * 479 * @param name name of the attribute. 480 * @param value value of the attribute. 481 * @return same builder, for chaining. 482 */ addAttribute(@onNull String name, @NonNull String value)483 public abstract Builder addAttribute(@NonNull String name, @NonNull String value); 484 485 /** 486 * Builds the {@link HtmlInfo} object. 487 * 488 * @return a new {@link HtmlInfo} instance. 489 */ build()490 public abstract HtmlInfo build(); 491 } 492 } 493 } 494