1 /*
2  * Copyright (C) 2021 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.inputmethod;
18 
19 import android.annotation.NonNull;
20 import android.os.Parcel;
21 import android.os.Parcelable;
22 import android.os.PersistableBundle;
23 
24 import java.util.ArrayList;
25 import java.util.Collections;
26 import java.util.List;
27 
28 /**
29  * The data class that IME can take extra information to applications when setting the text.
30  *
31  * See {@link InputConnection#commitText(CharSequence, int, TextAttribute)} and
32  * {@link InputConnection#setComposingRegion(int, int, TextAttribute)} and
33  * {@link InputConnection#setComposingText(CharSequence, int, TextAttribute)}
34  */
35 public final class TextAttribute implements Parcelable {
36     private final @NonNull List<String> mTextConversionSuggestions;
37     private final @NonNull PersistableBundle mExtras;
38 
TextAttribute(Builder builder)39     private TextAttribute(Builder builder) {
40         mTextConversionSuggestions = builder.mTextConversionSuggestions;
41         mExtras = builder.mExtras;
42     }
43 
TextAttribute(Parcel source)44     private TextAttribute(Parcel source) {
45         mTextConversionSuggestions = source.createStringArrayList();
46         mExtras = source.readPersistableBundle();
47     }
48 
49     /**
50      * Get the list of text conversion suggestions. More text conversion details in
51      * {@link Builder#setTextConversionSuggestions(List)}.
52      *
53      * @return List of text conversion suggestions. If the list is empty, it means that IME not set
54      * this field or IME didn't have suggestions for applications.
55      */
getTextConversionSuggestions()56     public @NonNull List<String> getTextConversionSuggestions() {
57         return mTextConversionSuggestions;
58     }
59 
60     /**
61      * Get the extras data. More extras data details in
62      * {@link Builder#setExtras(PersistableBundle)}.
63      *
64      * @return Extras data. If the Bundle is empty, it means that IME not set this field or IME
65      * didn't have extras data.
66      */
getExtras()67     public @NonNull PersistableBundle getExtras() {
68         return mExtras;
69     }
70 
71     /**
72      * Builder for creating a {@link TextAttribute}.
73      */
74     public static final class Builder {
75         private List<String> mTextConversionSuggestions = new ArrayList<>();
76         private PersistableBundle mExtras = new PersistableBundle();
77 
78         /**
79          * Sets text conversion suggestions.
80          *
81          * <p>Text conversion suggestion is for some transliteration languages which has
82          * pronunciation characters and target characters. When the user is typing the pronunciation
83          * characters, the input method can insert possible target characters into this list so that
84          * the editor authors can provide suggestion before the user enters the complete
85          * pronunciation characters.</p>
86          *
87          * @param textConversionSuggestions The list of text conversion suggestions.
88          * @return This builder
89          */
setTextConversionSuggestions( @onNull List<String> textConversionSuggestions)90         public @NonNull Builder setTextConversionSuggestions(
91                 @NonNull List<String> textConversionSuggestions) {
92             mTextConversionSuggestions = Collections.unmodifiableList(textConversionSuggestions);
93             return this;
94         }
95 
96         /**
97          * Sets extras data.
98          *
99          * <p>Any extra data to supply to the applications. This field is for extended communication
100          * with IME if there is data not defined in framework.</p>
101          *
102          * @return This builder.
103          */
setExtras(@onNull PersistableBundle extras)104         public @NonNull Builder setExtras(@NonNull PersistableBundle extras) {
105             mExtras = extras;
106             return this;
107         }
108 
109         /**
110          * @return a new {@link TextAttribute}.
111          */
build()112         public @NonNull TextAttribute build() {
113             return new TextAttribute(this);
114         }
115     }
116 
117     @Override
describeContents()118     public int describeContents() {
119         return 0;
120     }
121 
122     @Override
writeToParcel(@onNull Parcel dest, int flags)123     public void writeToParcel(@NonNull Parcel dest, int flags) {
124         dest.writeStringList(mTextConversionSuggestions);
125         dest.writePersistableBundle(mExtras);
126     }
127 
128     public static final @NonNull Parcelable.Creator<TextAttribute> CREATOR =
129             new Parcelable.Creator<TextAttribute>() {
130         @Override
131         public TextAttribute createFromParcel(Parcel source) {
132             return new TextAttribute(source);
133         }
134 
135         @Override
136         public TextAttribute[] newArray(int size) {
137             return new TextAttribute[size];
138         }
139     };
140 }
141