• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2007-2008 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * 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, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */
16 
17 package android.view.inputmethod;
18 
19 import android.os.Bundle;
20 import android.os.Handler;
21 import android.view.KeyCharacterMap;
22 import android.view.KeyEvent;
23 
24 /**
25  * The InputConnection interface is the communication channel from an
26  * {@link InputMethod} back to the application that is receiving its
27  * input. It is used to perform such things as reading text around the
28  * cursor, committing text to the text box, and sending raw key events
29  * to the application.
30  *
31  * <p>Starting from API Level {@link android.os.Build.VERSION_CODES#N},
32  * the system can deal with the situation where the application directly
33  * implements this class but one or more of the following methods are
34  * not implemented.</p>
35  * <ul>
36  *     <li>{@link #getSelectedText(int)}, which was introduced in
37  *     {@link android.os.Build.VERSION_CODES#GINGERBREAD}.</li>
38  *     <li>{@link #setComposingRegion(int, int)}, which was introduced
39  *     in {@link android.os.Build.VERSION_CODES#GINGERBREAD}.</li>
40  *     <li>{@link #commitCorrection(CorrectionInfo)}, which was introduced
41  *     in {@link android.os.Build.VERSION_CODES#HONEYCOMB}.</li>
42  *     <li>{@link #requestCursorUpdates(int)}, which was introduced in
43  *     {@link android.os.Build.VERSION_CODES#LOLLIPOP}.</li>
44  *     <li>{@link #deleteSurroundingTextInCodePoints(int, int)}}, which
45  *     was introduced in {@link android.os.Build.VERSION_CODES#N}.</li>
46  *     <li>{@link #getHandler()}}, which was introduced in
47  *     {@link android.os.Build.VERSION_CODES#N}.</li>
48  *     <li>{@link #closeConnection()}}, which was introduced in
49  *     {@link android.os.Build.VERSION_CODES#N}.</li>
50  * </ul>
51  *
52  * <h3>Implementing an IME or an editor</h3>
53  * <p>Text input is the result of the synergy of two essential components:
54  * an Input Method Engine (IME) and an editor. The IME can be a
55  * software keyboard, a handwriting interface, an emoji palette, a
56  * speech-to-text engine, and so on. There are typically several IMEs
57  * installed on any given Android device. In Android, IMEs extend
58  * {@link android.inputmethodservice.InputMethodService}.
59  * For more information about how to create an IME, see the
60  * <a href="{@docRoot}guide/topics/text/creating-input-method.html">
61  * Creating an input method</a> guide.
62  *
63  * The editor is the component that receives text and displays it.
64  * Typically, this is an {@link android.widget.EditText} instance, but
65  * some applications may choose to implement their own editor for
66  * various reasons. This is a large and complicated task, and an
67  * application that does this needs to make sure the behavior is
68  * consistent with standard EditText behavior in Android. An editor
69  * needs to interact with the IME, receiving commands through
70  * this InputConnection interface, and sending commands through
71  * {@link android.view.inputmethod.InputMethodManager}. An editor
72  * should start by implementing
73  * {@link android.view.View#onCreateInputConnection(EditorInfo)}
74  * to return its own input connection.</p>
75  *
76  * <p>If you are implementing your own IME, you will need to call the
77  * methods in this interface to interact with the application. Be sure
78  * to test your IME with a wide range of applications, including
79  * browsers and rich text editors, as some may have peculiarities you
80  * need to deal with. Remember your IME may not be the only source of
81  * changes on the text, and try to be as conservative as possible in
82  * the data you send and as liberal as possible in the data you
83  * receive.</p>
84  *
85  * <p>If you are implementing your own editor, you will probably need
86  * to provide your own subclass of {@link BaseInputConnection} to
87  * answer to the commands from IMEs. Please be sure to test your
88  * editor with as many IMEs as you can as their behavior can vary a
89  * lot. Also be sure to test with various languages, including CJK
90  * languages and right-to-left languages like Arabic, as these may
91  * have different input requirements. When in doubt about the
92  * behavior you should adopt for a particular call, please mimic the
93  * default TextView implementation in the latest Android version, and
94  * if you decide to drift from it, please consider carefully that
95  * inconsistencies in text editor behavior is almost universally felt
96  * as a bad thing by users.</p>
97  *
98  * <h3>Cursors, selections and compositions</h3>
99  * <p>In Android, the cursor and the selection are one and the same
100  * thing. A "cursor" is just the special case of a zero-sized
101  * selection. As such, this documentation uses them
102  * interchangeably. Any method acting "before the cursor" would act
103  * before the start of the selection if there is one, and any method
104  * acting "after the cursor" would act after the end of the
105  * selection.</p>
106  *
107  * <p>An editor needs to be able to keep track of a currently
108  * "composing" region, like the standard edition widgets do. The
109  * composition is marked in a specific style: see
110  * {@link android.text.Spanned#SPAN_COMPOSING}. IMEs use this to help
111  * the user keep track of what part of the text they are currently
112  * focusing on, and interact with the editor using
113  * {@link InputConnection#setComposingText(CharSequence, int)},
114  * {@link InputConnection#setComposingRegion(int, int)} and
115  * {@link InputConnection#finishComposingText()}.
116  * The composing region and the selection are completely independent
117  * of each other, and the IME may use them however they see fit.</p>
118  */
119 public interface InputConnection {
120     /**
121      * Flag for use with {@link #getTextAfterCursor} and
122      * {@link #getTextBeforeCursor} to have style information returned
123      * along with the text. If not set, {@link #getTextAfterCursor}
124      * sends only the raw text, without style or other spans. If set,
125      * it may return a complex CharSequence of both text and style
126      * spans. <strong>Editor authors</strong>: you should strive to
127      * send text with styles if possible, but it is not required.
128      */
129     static final int GET_TEXT_WITH_STYLES = 0x0001;
130 
131     /**
132      * Flag for use with {@link #getExtractedText} to indicate you
133      * would like to receive updates when the extracted text changes.
134      */
135     public static final int GET_EXTRACTED_TEXT_MONITOR = 0x0001;
136 
137     /**
138      * Get <var>n</var> characters of text before the current cursor
139      * position.
140      *
141      * <p>This method may fail either if the input connection has
142      * become invalid (such as its process crashing) or the editor is
143      * taking too long to respond with the text (it is given a couple
144      * seconds to return). In either case, null is returned. This
145      * method does not affect the text in the editor in any way, nor
146      * does it affect the selection or composing spans.</p>
147      *
148      * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the
149      * editor should return a {@link android.text.SpannableString}
150      * with all the spans set on the text.</p>
151      *
152      * <p><strong>IME authors:</strong> please consider this will
153      * trigger an IPC round-trip that will take some time. Assume this
154      * method consumes a lot of time. Also, please keep in mind the
155      * Editor may choose to return less characters than requested even
156      * if they are available for performance reasons.</p>
157      *
158      * <p><strong>Editor authors:</strong> please be careful of race
159      * conditions in implementing this call. An IME can make a change
160      * to the text and use this method right away; you need to make
161      * sure the returned value is consistent with the result of the
162      * latest edits. Also, you may return less than n characters if performance
163      * dictates so, but keep in mind IMEs are relying on this for many
164      * functions: you should not, for example, limit the returned value to
165      * the current line, and specifically do not return 0 characters unless
166      * the cursor is really at the start of the text.</p>
167      *
168      * @param n The expected length of the text.
169      * @param flags Supplies additional options controlling how the text is
170      * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
171      * @return the text before the cursor position; the length of the
172      * returned text might be less than <var>n</var>.
173      */
getTextBeforeCursor(int n, int flags)174     public CharSequence getTextBeforeCursor(int n, int flags);
175 
176     /**
177      * Get <var>n</var> characters of text after the current cursor
178      * position.
179      *
180      * <p>This method may fail either if the input connection has
181      * become invalid (such as its process crashing) or the client is
182      * taking too long to respond with the text (it is given a couple
183      * seconds to return). In either case, null is returned.
184      *
185      * <p>This method does not affect the text in the editor in any
186      * way, nor does it affect the selection or composing spans.</p>
187      *
188      * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the
189      * editor should return a {@link android.text.SpannableString}
190      * with all the spans set on the text.</p>
191      *
192      * <p><strong>IME authors:</strong> please consider this will
193      * trigger an IPC round-trip that will take some time. Assume this
194      * method consumes a lot of time.</p>
195      *
196      * <p><strong>Editor authors:</strong> please be careful of race
197      * conditions in implementing this call. An IME can make a change
198      * to the text and use this method right away; you need to make
199      * sure the returned value is consistent with the result of the
200      * latest edits. Also, you may return less than n characters if performance
201      * dictates so, but keep in mind IMEs are relying on this for many
202      * functions: you should not, for example, limit the returned value to
203      * the current line, and specifically do not return 0 characters unless
204      * the cursor is really at the end of the text.</p>
205      *
206      * @param n The expected length of the text.
207      * @param flags Supplies additional options controlling how the text is
208      * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
209      *
210      * @return the text after the cursor position; the length of the
211      * returned text might be less than <var>n</var>.
212      */
getTextAfterCursor(int n, int flags)213     public CharSequence getTextAfterCursor(int n, int flags);
214 
215     /**
216      * Gets the selected text, if any.
217      *
218      * <p>This method may fail if either the input connection has
219      * become invalid (such as its process crashing) or the client is
220      * taking too long to respond with the text (it is given a couple
221      * of seconds to return). In either case, null is returned.</p>
222      *
223      * <p>This method must not cause any changes in the editor's
224      * state.</p>
225      *
226      * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the
227      * editor should return a {@link android.text.SpannableString}
228      * with all the spans set on the text.</p>
229      *
230      * <p><strong>IME authors:</strong> please consider this will
231      * trigger an IPC round-trip that will take some time. Assume this
232      * method consumes a lot of time.</p>
233      *
234      * <p><strong>Editor authors:</strong> please be careful of race
235      * conditions in implementing this call. An IME can make a change
236      * to the text or change the selection position and use this
237      * method right away; you need to make sure the returned value is
238      * consistent with the results of the latest edits.</p>
239      *
240      * @param flags Supplies additional options controlling how the text is
241      * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
242      * @return the text that is currently selected, if any, or null if
243      * no text is selected. In {@link android.os.Build.VERSION_CODES#N} and
244      * later, returns false when the target application does not implement
245      * this method.
246      */
getSelectedText(int flags)247     public CharSequence getSelectedText(int flags);
248 
249     /**
250      * Retrieve the current capitalization mode in effect at the
251      * current cursor position in the text. See
252      * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}
253      * for more information.
254      *
255      * <p>This method may fail either if the input connection has
256      * become invalid (such as its process crashing) or the client is
257      * taking too long to respond with the text (it is given a couple
258      * seconds to return). In either case, 0 is returned.</p>
259      *
260      * <p>This method does not affect the text in the editor in any
261      * way, nor does it affect the selection or composing spans.</p>
262      *
263      * <p><strong>Editor authors:</strong> please be careful of race
264      * conditions in implementing this call. An IME can change the
265      * cursor position and use this method right away; you need to make
266      * sure the returned value is consistent with the results of the
267      * latest edits and changes to the cursor position.</p>
268      *
269      * @param reqModes The desired modes to retrieve, as defined by
270      * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These
271      * constants are defined so that you can simply pass the current
272      * {@link EditorInfo#inputType TextBoxAttribute.contentType} value
273      * directly in to here.
274      * @return the caps mode flags that are in effect at the current
275      * cursor position. See TYPE_TEXT_FLAG_CAPS_* in {@link android.text.InputType}.
276      */
getCursorCapsMode(int reqModes)277     public int getCursorCapsMode(int reqModes);
278 
279     /**
280      * Retrieve the current text in the input connection's editor, and
281      * monitor for any changes to it. This function returns with the
282      * current text, and optionally the input connection can send
283      * updates to the input method when its text changes.
284      *
285      * <p>This method may fail either if the input connection has
286      * become invalid (such as its process crashing) or the client is
287      * taking too long to respond with the text (it is given a couple
288      * seconds to return). In either case, null is returned.</p>
289      *
290      * <p>Editor authors: as a general rule, try to comply with the
291      * fields in <code>request</code> for how many chars to return,
292      * but if performance or convenience dictates otherwise, please
293      * feel free to do what is most appropriate for your case. Also,
294      * if the
295      * {@link #GET_EXTRACTED_TEXT_MONITOR} flag is set, you should be
296      * calling
297      * {@link InputMethodManager#updateExtractedText(View, int, ExtractedText)}
298      * whenever you call
299      * {@link InputMethodManager#updateSelection(View, int, int, int, int)}.</p>
300      *
301      * @param request Description of how the text should be returned.
302      * {@link android.view.inputmethod.ExtractedTextRequest}
303      * @param flags Additional options to control the client, either 0 or
304      * {@link #GET_EXTRACTED_TEXT_MONITOR}.
305 
306      * @return an {@link android.view.inputmethod.ExtractedText}
307      * object describing the state of the text view and containing the
308      * extracted text itself, or null if the input connection is no
309      * longer valid of the editor can't comply with the request for
310      * some reason.
311      */
getExtractedText(ExtractedTextRequest request, int flags)312     public ExtractedText getExtractedText(ExtractedTextRequest request,
313             int flags);
314 
315     /**
316      * Delete <var>beforeLength</var> characters of text before the
317      * current cursor position, and delete <var>afterLength</var>
318      * characters of text after the current cursor position, excluding
319      * the selection. Before and after refer to the order of the
320      * characters in the string, not to their visual representation:
321      * this means you don't have to figure out the direction of the
322      * text and can just use the indices as-is.
323      *
324      * <p>The lengths are supplied in Java chars, not in code points
325      * or in glyphs.</p>
326      *
327      * <p>Since this method only operates on text before and after the
328      * selection, it can't affect the contents of the selection. This
329      * may affect the composing span if the span includes characters
330      * that are to be deleted, but otherwise will not change it. If
331      * some characters in the composing span are deleted, the
332      * composing span will persist but get shortened by however many
333      * chars inside it have been removed.</p>
334      *
335      * <p><strong>IME authors:</strong> please be careful not to
336      * delete only half of a surrogate pair. Also take care not to
337      * delete more characters than are in the editor, as that may have
338      * ill effects on the application. Calling this method will cause
339      * the editor to call
340      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
341      * on your service after the batch input is over.</p>
342      *
343      * <p><strong>Editor authors:</strong> please be careful of race
344      * conditions in implementing this call. An IME can make a change
345      * to the text or change the selection position and use this
346      * method right away; you need to make sure the effects are
347      * consistent with the results of the latest edits. Also, although
348      * the IME should not send lengths bigger than the contents of the
349      * string, you should check the values for overflows and trim the
350      * indices to the size of the contents to avoid crashes. Since
351      * this changes the contents of the editor, you need to make the
352      * changes known to the input method by calling
353      * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
354      * but be careful to wait until the batch edit is over if one is
355      * in progress.</p>
356      *
357      * @param beforeLength The number of characters before the cursor to be deleted, in code unit.
358      *        If this is greater than the number of existing characters between the beginning of the
359      *        text and the cursor, then this method does not fail but deletes all the characters in
360      *        that range.
361      * @param afterLength The number of characters after the cursor to be deleted, in code unit.
362      *        If this is greater than the number of existing characters between the cursor and
363      *        the end of the text, then this method does not fail but deletes all the characters in
364      *        that range.
365      * @return true on success, false if the input connection is no longer valid.
366      */
deleteSurroundingText(int beforeLength, int afterLength)367     public boolean deleteSurroundingText(int beforeLength, int afterLength);
368 
369     /**
370      * A variant of {@link #deleteSurroundingText(int, int)}. Major differences are:
371      *
372      * <ul>
373      *     <li>The lengths are supplied in code points, not in Java chars or in glyphs.</>
374      *     <li>This method does nothing if there are one or more invalid surrogate pairs in the
375      *     requested range.</li>
376      * </ul>
377      *
378      * <p><strong>Editor authors:</strong> In addition to the requirement in
379      * {@link #deleteSurroundingText(int, int)}, make sure to do nothing when one ore more invalid
380      * surrogate pairs are found in the requested range.</p>
381      *
382      * @see #deleteSurroundingText(int, int)
383      *
384      * @param beforeLength The number of characters before the cursor to be deleted, in code points.
385      *        If this is greater than the number of existing characters between the beginning of the
386      *        text and the cursor, then this method does not fail but deletes all the characters in
387      *        that range.
388      * @param afterLength The number of characters after the cursor to be deleted, in code points.
389      *        If this is greater than the number of existing characters between the cursor and
390      *        the end of the text, then this method does not fail but deletes all the characters in
391      *        that range.
392      * @return true on success, false if the input connection is no longer valid.  Returns
393      * {@code false} when the target application does not implement this method.
394      */
deleteSurroundingTextInCodePoints(int beforeLength, int afterLength)395     public boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength);
396 
397     /**
398      * Replace the currently composing text with the given text, and
399      * set the new cursor position. Any composing text set previously
400      * will be removed automatically.
401      *
402      * <p>If there is any composing span currently active, all
403      * characters that it comprises are removed. The passed text is
404      * added in its place, and a composing span is added to this
405      * text. If there is no composing span active, the passed text is
406      * added at the cursor position (removing selected characters
407      * first if any), and a composing span is added on the new text.
408      * Finally, the cursor is moved to the location specified by
409      * <code>newCursorPosition</code>.</p>
410      *
411      * <p>This is usually called by IMEs to add or remove or change
412      * characters in the composing span. Calling this method will
413      * cause the editor to call
414      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
415      * on the current IME after the batch input is over.</p>
416      *
417      * <p><strong>Editor authors:</strong> please keep in mind the
418      * text may be very similar or completely different than what was
419      * in the composing span at call time, or there may not be a
420      * composing span at all. Please note that although it's not
421      * typical use, the string may be empty. Treat this normally,
422      * replacing the currently composing text with an empty string.
423      * Also, be careful with the cursor position. IMEs rely on this
424      * working exactly as described above. Since this changes the
425      * contents of the editor, you need to make the changes known to
426      * the input method by calling
427      * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
428      * but be careful to wait until the batch edit is over if one is
429      * in progress. Note that this method can set the cursor position
430      * on either edge of the composing text or entirely outside it,
431      * but the IME may also go on to move the cursor position to
432      * within the composing text in a subsequent call so you should
433      * make no assumption at all: the composing text and the selection
434      * are entirely independent.</p>
435      *
436      * @param text The composing text with styles if necessary. If no style
437      *        object attached to the text, the default style for composing text
438      *        is used. See {@link android.text.Spanned} for how to attach style
439      *        object to the text. {@link android.text.SpannableString} and
440      *        {@link android.text.SpannableStringBuilder} are two
441      *        implementations of the interface {@link android.text.Spanned}.
442      * @param newCursorPosition The new cursor position around the text. If
443      *        > 0, this is relative to the end of the text - 1; if <= 0, this
444      *        is relative to the start of the text. So a value of 1 will
445      *        always advance you to the position after the full text being
446      *        inserted. Note that this means you can't position the cursor
447      *        within the text, because the editor can make modifications to
448      *        the text you are providing so it is not possible to correctly
449      *        specify locations there.
450      * @return true on success, false if the input connection is no longer
451      * valid.
452      */
setComposingText(CharSequence text, int newCursorPosition)453     public boolean setComposingText(CharSequence text, int newCursorPosition);
454 
455     /**
456      * Mark a certain region of text as composing text. If there was a
457      * composing region, the characters are left as they were and the
458      * composing span removed, as if {@link #finishComposingText()}
459      * has been called. The default style for composing text is used.
460      *
461      * <p>The passed indices are clipped to the contents bounds. If
462      * the resulting region is zero-sized, no region is marked and the
463      * effect is the same as that of calling {@link #finishComposingText()}.
464      * The order of start and end is not important. In effect, the
465      * region from start to end and the region from end to start is
466      * the same. Editor authors, be ready to accept a start that is
467      * greater than end.</p>
468      *
469      * <p>Since this does not change the contents of the text, editors should not call
470      * {@link InputMethodManager#updateSelection(View, int, int, int, int)} and
471      * IMEs should not receive
472      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}.
473      * </p>
474      *
475      * <p>This has no impact on the cursor/selection position. It may
476      * result in the cursor being anywhere inside or outside the
477      * composing region, including cases where the selection and the
478      * composing region overlap partially or entirely.</p>
479      *
480      * @param start the position in the text at which the composing region begins
481      * @param end the position in the text at which the composing region ends
482      * @return true on success, false if the input connection is no longer
483      * valid. In {@link android.os.Build.VERSION_CODES#N} and later, false is returned when the
484      * target application does not implement this method.
485      */
setComposingRegion(int start, int end)486     public boolean setComposingRegion(int start, int end);
487 
488     /**
489      * Have the text editor finish whatever composing text is
490      * currently active. This simply leaves the text as-is, removing
491      * any special composing styling or other state that was around
492      * it. The cursor position remains unchanged.
493      *
494      * <p><strong>IME authors:</strong> be aware that this call may be
495      * expensive with some editors.</p>
496      *
497      * <p><strong>Editor authors:</strong> please note that the cursor
498      * may be anywhere in the contents when this is called, including
499      * in the middle of the composing span or in a completely
500      * unrelated place. It must not move.</p>
501      *
502      * @return true on success, false if the input connection
503      * is no longer valid.
504      */
finishComposingText()505     public boolean finishComposingText();
506 
507     /**
508      * Commit text to the text box and set the new cursor position.
509      *
510      * <p>This method removes the contents of the currently composing
511      * text and replaces it with the passed CharSequence, and then
512      * moves the cursor according to {@code newCursorPosition}. If there
513      * is no composing text when this method is called, the new text is
514      * inserted at the cursor position, removing text inside the selection
515      * if any. This behaves like calling
516      * {@link #setComposingText(CharSequence, int) setComposingText(text, newCursorPosition)}
517      * then {@link #finishComposingText()}.</p>
518      *
519      * <p>Calling this method will cause the editor to call
520      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
521      * on the current IME after the batch input is over.
522      * <strong>Editor authors</strong>, for this to happen you need to
523      * make the changes known to the input method by calling
524      * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
525      * but be careful to wait until the batch edit is over if one is
526      * in progress.</p>
527      *
528      * @param text The text to commit. This may include styles.
529      * @param newCursorPosition The new cursor position around the text,
530      *        in Java characters. If > 0, this is relative to the end
531      *        of the text - 1; if <= 0, this is relative to the start
532      *        of the text. So a value of 1 will always advance the cursor
533      *        to the position after the full text being inserted. Note that
534      *        this means you can't position the cursor within the text,
535      *        because the editor can make modifications to the text
536      *        you are providing so it is not possible to correctly specify
537      *        locations there.
538      * @return true on success, false if the input connection is no longer
539      * valid.
540      */
commitText(CharSequence text, int newCursorPosition)541     public boolean commitText(CharSequence text, int newCursorPosition);
542 
543     /**
544      * Commit a completion the user has selected from the possible ones
545      * previously reported to {@link InputMethodSession#displayCompletions
546      * InputMethodSession#displayCompletions(CompletionInfo[])} or
547      * {@link InputMethodManager#displayCompletions
548      * InputMethodManager#displayCompletions(View, CompletionInfo[])}.
549      * This will result in the same behavior as if the user had
550      * selected the completion from the actual UI. In all other
551      * respects, this behaves like {@link #commitText(CharSequence, int)}.
552      *
553      * <p><strong>IME authors:</strong> please take care to send the
554      * same object that you received through
555      * {@link android.inputmethodservice.InputMethodService#onDisplayCompletions(CompletionInfo[])}.
556      * </p>
557      *
558      * <p><strong>Editor authors:</strong> if you never call
559      * {@link InputMethodSession#displayCompletions(CompletionInfo[])} or
560      * {@link InputMethodManager#displayCompletions(View, CompletionInfo[])} then
561      * a well-behaved IME should never call this on your input
562      * connection, but be ready to deal with misbehaving IMEs without
563      * crashing.</p>
564      *
565      * <p>Calling this method (with a valid {@link CompletionInfo} object)
566      * will cause the editor to call
567      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
568      * on the current IME after the batch input is over.
569      * <strong>Editor authors</strong>, for this to happen you need to
570      * make the changes known to the input method by calling
571      * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
572      * but be careful to wait until the batch edit is over if one is
573      * in progress.</p>
574      *
575      * @param text The committed completion.
576      * @return true on success, false if the input connection is no longer
577      * valid.
578      */
commitCompletion(CompletionInfo text)579     public boolean commitCompletion(CompletionInfo text);
580 
581     /**
582      * Commit a correction automatically performed on the raw user's input. A
583      * typical example would be to correct typos using a dictionary.
584      *
585      * <p>Calling this method will cause the editor to call
586      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
587      * on the current IME after the batch input is over.
588      * <strong>Editor authors</strong>, for this to happen you need to
589      * make the changes known to the input method by calling
590      * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
591      * but be careful to wait until the batch edit is over if one is
592      * in progress.</p>
593      *
594      * @param correctionInfo Detailed information about the correction.
595      * @return true on success, false if the input connection is no longer valid.
596      * In {@link android.os.Build.VERSION_CODES#N} and later, returns false
597      * when the target application does not implement this method.
598      */
commitCorrection(CorrectionInfo correctionInfo)599     public boolean commitCorrection(CorrectionInfo correctionInfo);
600 
601     /**
602      * Set the selection of the text editor. To set the cursor
603      * position, start and end should have the same value.
604      *
605      * <p>Since this moves the cursor, calling this method will cause
606      * the editor to call
607      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
608      * on the current IME after the batch input is over.
609      * <strong>Editor authors</strong>, for this to happen you need to
610      * make the changes known to the input method by calling
611      * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
612      * but be careful to wait until the batch edit is over if one is
613      * in progress.</p>
614      *
615      * <p>This has no effect on the composing region which must stay
616      * unchanged. The order of start and end is not important. In
617      * effect, the region from start to end and the region from end to
618      * start is the same. Editor authors, be ready to accept a start
619      * that is greater than end.</p>
620      *
621      * @param start the character index where the selection should start.
622      * @param end the character index where the selection should end.
623      * @return true on success, false if the input connection is no longer
624      * valid.
625      */
setSelection(int start, int end)626     public boolean setSelection(int start, int end);
627 
628     /**
629      * Have the editor perform an action it has said it can do.
630      *
631      * <p>This is typically used by IMEs when the user presses the key
632      * associated with the action.</p>
633      *
634      * @param editorAction This must be one of the action constants for
635      * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as
636      * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}.
637      * @return true on success, false if the input connection is no longer
638      * valid.
639      */
performEditorAction(int editorAction)640     public boolean performEditorAction(int editorAction);
641 
642     /**
643      * Perform a context menu action on the field. The given id may be one of:
644      * {@link android.R.id#selectAll},
645      * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText},
646      * {@link android.R.id#cut}, {@link android.R.id#copy},
647      * {@link android.R.id#paste}, {@link android.R.id#copyUrl},
648      * or {@link android.R.id#switchInputMethod}
649      */
performContextMenuAction(int id)650     public boolean performContextMenuAction(int id);
651 
652     /**
653      * Tell the editor that you are starting a batch of editor
654      * operations. The editor will try to avoid sending you updates
655      * about its state until {@link #endBatchEdit} is called. Batch
656      * edits nest.
657      *
658      * <p><strong>IME authors:</strong> use this to avoid getting
659      * calls to
660      * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}
661      * corresponding to intermediate state. Also, use this to avoid
662      * flickers that may arise from displaying intermediate state. Be
663      * sure to call {@link #endBatchEdit} for each call to this, or
664      * you may block updates in the editor.</p>
665      *
666      * <p><strong>Editor authors:</strong> while a batch edit is in
667      * progress, take care not to send updates to the input method and
668      * not to update the display. IMEs use this intensively to this
669      * effect. Also please note that batch edits need to nest
670      * correctly.</p>
671      *
672      * @return true if a batch edit is now in progress, false otherwise. Since
673      * this method starts a batch edit, that means it will always return true
674      * unless the input connection is no longer valid.
675      */
beginBatchEdit()676     public boolean beginBatchEdit();
677 
678     /**
679      * Tell the editor that you are done with a batch edit previously
680      * initiated with {@link #beginBatchEdit}. This ends the latest
681      * batch only.
682      *
683      * <p><strong>IME authors:</strong> make sure you call this
684      * exactly once for each call to {@link #beginBatchEdit}.</p>
685      *
686      * <p><strong>Editor authors:</strong> please be careful about
687      * batch edit nesting. Updates still to be held back until the end
688      * of the last batch edit.</p>
689      *
690      * @return true if there is still a batch edit in progress after closing
691      * the latest one (in other words, if the nesting count is > 0), false
692      * otherwise or if the input connection is no longer valid.
693      */
endBatchEdit()694     public boolean endBatchEdit();
695 
696     /**
697      * Send a key event to the process that is currently attached
698      * through this input connection. The event will be dispatched
699      * like a normal key event, to the currently focused view; this
700      * generally is the view that is providing this InputConnection,
701      * but due to the asynchronous nature of this protocol that can
702      * not be guaranteed and the focus may have changed by the time
703      * the event is received.
704      *
705      * <p>This method can be used to send key events to the
706      * application. For example, an on-screen keyboard may use this
707      * method to simulate a hardware keyboard. There are three types
708      * of standard keyboards, numeric (12-key), predictive (20-key)
709      * and ALPHA (QWERTY). You can specify the keyboard type by
710      * specify the device id of the key event.</p>
711      *
712      * <p>You will usually want to set the flag
713      * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD}
714      * on all key event objects you give to this API; the flag will
715      * not be set for you.</p>
716      *
717      * <p>Note that it's discouraged to send such key events in normal
718      * operation; this is mainly for use with
719      * {@link android.text.InputType#TYPE_NULL} type text fields. Use
720      * the {@link #commitText} family of methods to send text to the
721      * application instead.</p>
722      *
723      * @param event The key event.
724      * @return true on success, false if the input connection is no longer
725      * valid.
726      *
727      * @see KeyEvent
728      * @see KeyCharacterMap#NUMERIC
729      * @see KeyCharacterMap#PREDICTIVE
730      * @see KeyCharacterMap#ALPHA
731      */
sendKeyEvent(KeyEvent event)732     public boolean sendKeyEvent(KeyEvent event);
733 
734     /**
735      * Clear the given meta key pressed states in the given input
736      * connection.
737      *
738      * <p>This can be used by the IME to clear the meta key states set
739      * by a hardware keyboard with latched meta keys, if the editor
740      * keeps track of these.</p>
741      *
742      * @param states The states to be cleared, may be one or more bits as
743      * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}.
744      * @return true on success, false if the input connection is no longer
745      * valid.
746      */
clearMetaKeyStates(int states)747     public boolean clearMetaKeyStates(int states);
748 
749     /**
750      * Called by the IME to tell the client when it switches between
751      * fullscreen and normal modes. This will normally be called for
752      * you by the standard implementation of
753      * {@link android.inputmethodservice.InputMethodService}.
754      *
755      * @return true on success, false if the input connection is no longer
756      * valid.
757      */
reportFullscreenMode(boolean enabled)758     public boolean reportFullscreenMode(boolean enabled);
759 
760     /**
761      * API to send private commands from an input method to its
762      * connected editor. This can be used to provide domain-specific
763      * features that are only known between certain input methods and
764      * their clients. Note that because the InputConnection protocol
765      * is asynchronous, you have no way to get a result back or know
766      * if the client understood the command; you can use the
767      * information in {@link EditorInfo} to determine if a client
768      * supports a particular command.
769      *
770      * @param action Name of the command to be performed. This <em>must</em>
771      * be a scoped name, i.e. prefixed with a package name you own, so that
772      * different developers will not create conflicting commands.
773      * @param data Any data to include with the command.
774      * @return true if the command was sent (whether or not the
775      * associated editor understood it), false if the input connection is no longer
776      * valid.
777      */
performPrivateCommand(String action, Bundle data)778     public boolean performPrivateCommand(String action, Bundle data);
779 
780     /**
781      * The editor is requested to call
782      * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} at
783      * once, as soon as possible, regardless of cursor/anchor position changes. This flag can be
784      * used together with {@link #CURSOR_UPDATE_MONITOR}.
785      */
786     public static final int CURSOR_UPDATE_IMMEDIATE = 1 << 0;
787 
788     /**
789      * The editor is requested to call
790      * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)}
791      * whenever cursor/anchor position is changed. To disable monitoring, call
792      * {@link InputConnection#requestCursorUpdates(int)} again with this flag off.
793      * <p>
794      * This flag can be used together with {@link #CURSOR_UPDATE_IMMEDIATE}.
795      * </p>
796      */
797     public static final int CURSOR_UPDATE_MONITOR = 1 << 1;
798 
799     /**
800      * Called by the input method to ask the editor for calling back
801      * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} to
802      * notify cursor/anchor locations.
803      *
804      * @param cursorUpdateMode {@link #CURSOR_UPDATE_IMMEDIATE} and/or
805      * {@link #CURSOR_UPDATE_MONITOR}. Pass {@code 0} to disable the effect of
806      * {@link #CURSOR_UPDATE_MONITOR}.
807      * @return {@code true} if the request is scheduled. {@code false} to indicate that when the
808      * application will not call
809      * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)}.
810      * In {@link android.os.Build.VERSION_CODES#N} and later, returns {@code false} also when the
811      * target application does not implement this method.
812      */
requestCursorUpdates(int cursorUpdateMode)813     public boolean requestCursorUpdates(int cursorUpdateMode);
814 
815     /**
816      * Called by the {@link InputMethodManager} to enable application developers to specify a
817      * dedicated {@link Handler} on which incoming IPC method calls from input methods will be
818      * dispatched.
819      *
820      * <p>Note: This does nothing when called from input methods.</p>
821      *
822      * @return {@code null} to use the default {@link Handler}.
823      */
getHandler()824     public Handler getHandler();
825 
826     /**
827      * Called by the system up to only once to notify that the system is about to invalidate
828      * connection between the input method and the application.
829      *
830      * <p><strong>Editor authors</strong>: You can clear all the nested batch edit right now and
831      * you no longer need to handle subsequent callbacks on this connection, including
832      * {@link #beginBatchEdit()}}.  Note that although the system tries to call this method whenever
833      * possible, there may be a chance that this method is not called in some exceptional
834      * situations.</p>
835      *
836      * <p>Note: This does nothing when called from input methods.</p>
837      */
closeConnection()838     public void closeConnection();
839 }
840