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