Introduce EditorInfo#locales.

The primary goal of this CL is to enable application developers to
provide more context-based language (locale) information for IME
developers so that users can be benefited by more natural text input
experience.

As of API Level 23, there are several APIs that allow IMEs to retrieve
locale/country related information.

  - Locale#getDefault()
  - Configuration#locale
  - LocaleSpan#getLocale()
  - SubscriptionInfo#getCountryIso()

However, only LocaleSpan#getLocale() can be used to pass application
specific languge (locale) context from applications to IMEs.  Also
LocaleSpan is not designed to be used per input-context.  We want to
have something in EditorInfo and LocaleList would be the right thing.

Although default implementation of TextView#onCreateInputConnection()
starts filling EditorInfo#localeList with TextView#getTextLocales() by
this CL, application developers are encouraged to provide its own
LocaleList when they are confident that the user want to use a
certain (set) of language(s).

For instance, a chat application may be able to guess what language will
be used in the conversation before the user start typing.  At least it
should be able to remember the last used language for each conversation.

Another instance would be "From" and "To" EditText fields in a
translation app.  Those fields should have different LocaleList based on
the languages that the user want to translate from and to.

Bug: 22859862
Change-Id: I77db5b99a7cf745d800db75baf135bb60ad04820

api/current.txt

@@ -42909,6 +42909,7 @@ package android.view.inputmethod {
     field public int initialSelStart;
     field public int inputType;
     field public java.lang.CharSequence label;
+    field public android.util.LocaleList locales;
     field public java.lang.String packageName;
     field public java.lang.String privateImeOptions;
   }

api/system-current.txt

@@ -45237,6 +45237,7 @@ package android.view.inputmethod {
     field public int initialSelStart;
     field public int inputType;
     field public java.lang.CharSequence label;
+    field public android.util.LocaleList locales;
     field public java.lang.String packageName;
     field public java.lang.String privateImeOptions;
   }

api/test-current.txt

@@ -42911,6 +42911,7 @@ package android.view.inputmethod {
     field public int initialSelStart;
     field public int inputType;
     field public java.lang.CharSequence label;
+    field public android.util.LocaleList locales;
     field public java.lang.String packageName;
     field public java.lang.String privateImeOptions;
   }

core/java/android/view/inputmethod/EditorInfo.java

@@ -21,6 +21,7 @@
 import android.os.Parcelable;
 import android.text.InputType;
 import android.text.TextUtils;
+import android.util.LocaleList;
 import android.util.Printer;
 
 /**
@@ -339,6 +340,22 @@ public class EditorInfo implements InputType, Parcelable {
      */
     public Bundle extras;
 
+    /**
+     * Additional context information that tells what languages are expected by the user.
+     *
+     * <p><strong>IME authors:</strong> Possible use cases for IME developers would be:</p>
+     * <ul>
+     *     <li>Automatically switching keyboard layout.</li>
+     *     <li>Changing language model for better typing experience.</li>
+     * </ul>
+     *
+     * <p><strong>Editor authors:</strong> Providing this context information can help IMEs to
+     * improve text input experience.  For example, chat applications can remember what language is
+     * used in the last conversation for each chat session, and put the last used language at the
+     * top of {@link #locales}.</p>
+     */
+    public LocaleList locales = LocaleList.getEmptyLocaleList();
+
     /**
      * Ensure that the data in this EditorInfo is compatible with an application
      * that was developed against the given target API version.  This can
@@ -393,6 +410,7 @@ public void dump(Printer pw, String prefix) {
                 + " fieldId=" + fieldId
                 + " fieldName=" + fieldName);
         pw.println(prefix + "extras=" + extras);
+        pw.println(prefix + "locales=" + locales);
     }
 
     /**
@@ -416,6 +434,7 @@ public void writeToParcel(Parcel dest, int flags) {
         dest.writeInt(fieldId);
         dest.writeString(fieldName);
         dest.writeBundle(extras);
+        locales.writeToParcel(dest, flags);
     }
 
     /**
@@ -439,6 +458,7 @@ public EditorInfo createFromParcel(Parcel source) {
                     res.fieldId = source.readInt();
                     res.fieldName = source.readString();
                     res.extras = source.readBundle();
+                    res.locales = LocaleList.CREATOR.createFromParcel(source);
                     return res;
                 }
 

core/java/android/widget/TextView.java

@@ -6439,6 +6439,9 @@ public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
                 outAttrs.initialCapsMode = ic.getCursorCapsMode(getInputType());
                 return ic;
             }
+            // LocaleList is designed to be immutable.  This is theoretically equivalent to copy
+            // the snapshot of the current text locales.
+            outAttrs.locales = getTextLocales();
         }
         return null;
     }