[go: nahoru, domu]

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
17package android.view.inputmethod;
18
19import android.os.Bundle;
20import android.os.Handler;
21import android.view.KeyCharacterMap;
22import 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 */
119public 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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
838    public void closeConnection();
839}
840