Merge "Updated docs with clarifications on specific limitations with the new Inline APIs." into rvc-dev am: 3532bdaa36 am: f336feb6df

Original change: https://googleplex-android-review.googlesource.com/c/platform/frameworks/base/+/12175369

Change-Id: I8c4d50150824f8f64b2c961663e19bf15331acb0

core/java/android/view/inputmethod/InlineSuggestionsRequest.java

@@ -47,6 +47,9 @@ public final class InlineSuggestionsRequest implements Parcelable {
     /**
      * Max number of suggestions expected from the response. It must be a positive value.
      * Defaults to {@code SUGGESTION_COUNT_UNLIMITED} if not set.
+     *
+     * <p>In practice, it is recommended that the max suggestion count does not exceed <b>5</b>
+     * for performance reasons.</p>
      */
     private final int mMaxSuggestionCount;
 
@@ -67,6 +70,9 @@ public final class InlineSuggestionsRequest implements Parcelable {
     /**
      * The IME provided locales for the request. If non-empty, the inline suggestions should
      * return languages from the supported locales. If not provided, it'll default to system locale.
+     *
+     * <p>Note for Autofill Providers: It is <b>recommended</b> for the returned inline suggestions
+     * to have one locale to guarantee consistent UI rendering.</p>
      */
     private @NonNull LocaleList mSupportedLocales;
 
@@ -227,6 +233,9 @@ public final class InlineSuggestionsRequest implements Parcelable {
     /**
      * Max number of suggestions expected from the response. It must be a positive value.
      * Defaults to {@code SUGGESTION_COUNT_UNLIMITED} if not set.
+     *
+     * <p>In practice, it is recommended that the max suggestion count does not exceed <b>5</b>
+     * for performance reasons.</p>
      */
     @DataClass.Generated.Member
     public int getMaxSuggestionCount() {
@@ -256,6 +265,9 @@ public final class InlineSuggestionsRequest implements Parcelable {
     /**
      * The IME provided locales for the request. If non-empty, the inline suggestions should
      * return languages from the supported locales. If not provided, it'll default to system locale.
+     *
+     * <p>Note for Autofill Providers: It is <b>recommended</b> for the returned inline suggestions
+     * to have one locale to guarantee consistent UI rendering.</p>
      */
     @DataClass.Generated.Member
     public @NonNull LocaleList getSupportedLocales() {
@@ -458,6 +470,9 @@ public final class InlineSuggestionsRequest implements Parcelable {
         /**
          * Max number of suggestions expected from the response. It must be a positive value.
          * Defaults to {@code SUGGESTION_COUNT_UNLIMITED} if not set.
+         *
+         * <p>In practice, it is recommended that the max suggestion count does not exceed <b>5</b>
+         * for performance reasons.</p>
          */
         @DataClass.Generated.Member
         public @NonNull Builder setMaxSuggestionCount(int value) {
@@ -508,6 +523,9 @@ public final class InlineSuggestionsRequest implements Parcelable {
         /**
          * The IME provided locales for the request. If non-empty, the inline suggestions should
          * return languages from the supported locales. If not provided, it'll default to system locale.
+         *
+         * <p>Note for Autofill Providers: It is <b>recommended</b> for the returned inline suggestions
+         * to have one locale to guarantee consistent UI rendering.</p>
          */
         @DataClass.Generated.Member
         public @NonNull Builder setSupportedLocales(@NonNull LocaleList value) {
@@ -604,7 +622,7 @@ public final class InlineSuggestionsRequest implements Parcelable {
     }
 
     @DataClass.Generated(
-            time = 1588109685838L,
+            time = 1595457701315L,
             codegenVersion = "1.0.15",
             sourceFile = "frameworks/base/core/java/android/view/inputmethod/InlineSuggestionsRequest.java",
             inputSignatures = "public static final  int SUGGESTION_COUNT_UNLIMITED\nprivate final  int mMaxSuggestionCount\nprivate final @android.annotation.NonNull java.util.List<android.widget.inline.InlinePresentationSpec> mInlinePresentationSpecs\nprivate @android.annotation.NonNull java.lang.String mHostPackageName\nprivate @android.annotation.NonNull android.os.LocaleList mSupportedLocales\nprivate @android.annotation.NonNull android.os.Bundle mExtras\nprivate @android.annotation.Nullable android.os.IBinder mHostInputToken\nprivate  int mHostDisplayId\npublic  void setHostInputToken(android.os.IBinder)\nprivate  boolean extrasEquals(android.os.Bundle)\nprivate  void parcelHostInputToken(android.os.Parcel,int)\nprivate @android.annotation.Nullable android.os.IBinder unparcelHostInputToken(android.os.Parcel)\npublic  void setHostDisplayId(int)\nprivate  void onConstructed()\npublic  void filterContentTypes()\nprivate static  int defaultMaxSuggestionCount()\nprivate static  java.lang.String defaultHostPackageName()\nprivate static  android.os.LocaleList defaultSupportedLocales()\nprivate static @android.annotation.Nullable android.os.IBinder defaultHostInputToken()\nprivate static @android.annotation.Nullable int defaultHostDisplayId()\nprivate static @android.annotation.NonNull android.os.Bundle defaultExtras()\nclass InlineSuggestionsRequest extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genEqualsHashCode=true, genToString=true, genBuilder=true)\nabstract  android.view.inputmethod.InlineSuggestionsRequest.Builder setInlinePresentationSpecs(java.util.List<android.widget.inline.InlinePresentationSpec>)\nabstract  android.view.inputmethod.InlineSuggestionsRequest.Builder setHostPackageName(java.lang.String)\nabstract  android.view.inputmethod.InlineSuggestionsRequest.Builder setHostInputToken(android.os.IBinder)\nabstract  android.view.inputmethod.InlineSuggestionsRequest.Builder setHostDisplayId(int)\nclass BaseBuilder extends java.lang.Object implements []")

core/java/android/view/inputmethod/InlineSuggestionsResponse.java

@@ -32,7 +32,18 @@ import java.util.List;
  */
 @DataClass(genEqualsHashCode = true, genToString = true, genHiddenConstructor = true)
 public final class InlineSuggestionsResponse implements Parcelable {
-    private final @NonNull List<InlineSuggestion> mInlineSuggestions;
+    /**
+     * List of {@link InlineSuggestion}s returned as a part of this response.
+     *
+     * <p>When the host app requests to inflate this <b>ordered</b> list of inline suggestions by
+     * calling {@link InlineSuggestion#inflate}, it is the host's responsibility to track the
+     * order of the inflated {@link android.view.View}s. These views are to be added in
+     * order to the view hierarchy, because the inflation calls will return asynchronously.</p>
+     *
+     * <p>The inflation ordering does not apply to the pinned icon.</p>
+     */
+    @NonNull
+    private final List<InlineSuggestion> mInlineSuggestions;
 
     /**
      * Creates a new {@link InlineSuggestionsResponse}, for testing purpose.
@@ -48,7 +59,7 @@ public final class InlineSuggestionsResponse implements Parcelable {
 
 
 
-    // Code below generated by codegen v1.0.14.
+    // Code below generated by codegen v1.0.15.
     //
     // DO NOT MODIFY!
     // CHECKSTYLE:OFF Generated code
@@ -64,6 +75,15 @@ public final class InlineSuggestionsResponse implements Parcelable {
     /**
      * Creates a new InlineSuggestionsResponse.
      *
+     * @param inlineSuggestions
+     *   List of {@link InlineSuggestion}s returned as a part of this response.
+     *
+     *   <p>When the host app requests to inflate this <b>ordered</b> list of inline suggestions by
+     *   calling {@link InlineSuggestion#inflate}, it is the host's responsibility to track the
+     *   order of the inflated {@link android.view.View}s. These views are to be added in
+     *   order to the view hierarchy, because the inflation calls will return asynchronously.</p>
+     *
+     *   <p>The inflation ordering does not apply to the pinned icon.</p>
      * @hide
      */
     @DataClass.Generated.Member
@@ -76,6 +96,16 @@ public final class InlineSuggestionsResponse implements Parcelable {
         // onConstructed(); // You can define this method to get a callback
     }
 
+    /**
+     * List of {@link InlineSuggestion}s returned as a part of this response.
+     *
+     * <p>When the host app requests to inflate this <b>ordered</b> list of inline suggestions by
+     * calling {@link InlineSuggestion#inflate}, it is the host's responsibility to track the
+     * order of the inflated {@link android.view.View}s. These views are to be added in
+     * order to the view hierarchy, because the inflation calls will return asynchronously.</p>
+     *
+     * <p>The inflation ordering does not apply to the pinned icon.</p>
+     */
     @DataClass.Generated.Member
     public @NonNull List<InlineSuggestion> getInlineSuggestions() {
         return mInlineSuggestions;
@@ -164,8 +194,8 @@ public final class InlineSuggestionsResponse implements Parcelable {
     };
 
     @DataClass.Generated(
-            time = 1578972149519L,
+            time = 1595891876037L,
-            codegenVersion = "1.0.14",
+            codegenVersion = "1.0.15",
             sourceFile = "frameworks/base/core/java/android/view/inputmethod/InlineSuggestionsResponse.java",
             inputSignatures = "private final @android.annotation.NonNull java.util.List<android.view.inputmethod.InlineSuggestion> mInlineSuggestions\npublic static @android.annotation.TestApi @android.annotation.NonNull android.view.inputmethod.InlineSuggestionsResponse newInlineSuggestionsResponse(java.util.List<android.view.inputmethod.InlineSuggestion>)\nclass InlineSuggestionsResponse extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genEqualsHashCode=true, genToString=true, genHiddenConstructor=true)")
     @Deprecated