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