• 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.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 input. It
26  * is used to perform such things as reading text around the cursor,
27  * committing text to the text box, and sending raw key events to the application.
28  *
29  * <p>Applications should never directly implement this interface, but instead
30  * subclass from {@link BaseInputConnection}.  This will ensure that the
31  * application does not break when new methods are added to the interface.
32  */
33 public interface InputConnection {
34     /**
35      * Flag for use with {@link #getTextAfterCursor} and
36      * {@link #getTextBeforeCursor} to have style information returned along
37      * with the text.  If not set, you will receive only the raw text.  If
38      * set, you may receive a complex CharSequence of both text and style
39      * spans.
40      */
41     static final int GET_TEXT_WITH_STYLES = 0x0001;
42 
43     /**
44      * Flag for use with {@link #getExtractedText} to indicate you would
45      * like to receive updates when the extracted text changes.
46      */
47     public static final int GET_EXTRACTED_TEXT_MONITOR = 0x0001;
48 
49     /**
50      * Get <var>n</var> characters of text before the current cursor position.
51      *
52      * <p>This method may fail either if the input connection has become invalid
53      * (such as its process crashing) or the client is taking too long to
54      * respond with the text (it is given a couple seconds to return).
55      * In either case, a null is returned.
56      *
57      * @param n The expected length of the text.
58      * @param flags Supplies additional options controlling how the text is
59      * returned.  May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
60      *
61      * @return Returns the text before the cursor position; the length of the
62      * returned text might be less than <var>n</var>.
63      */
getTextBeforeCursor(int n, int flags)64     public CharSequence getTextBeforeCursor(int n, int flags);
65 
66     /**
67      * Get <var>n</var> characters of text after the current cursor position.
68      *
69      * <p>This method may fail either if the input connection has become invalid
70      * (such as its process crashing) or the client is taking too long to
71      * respond with the text (it is given a couple seconds to return).
72      * In either case, a null is returned.
73      *
74      * @param n The expected length of the text.
75      * @param flags Supplies additional options controlling how the text is
76      * returned.  May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
77      *
78      * @return Returns the text after the cursor position; the length of the
79      * returned text might be less than <var>n</var>.
80      */
getTextAfterCursor(int n, int flags)81     public CharSequence getTextAfterCursor(int n, int flags);
82 
83     /**
84      * Gets the selected text, if any.
85      *
86      * <p>This method may fail if either the input connection has become
87      * invalid (such as its process crashing) or the client is taking too
88      * long to respond with the text (it is given a couple of seconds to return).
89      * In either case, a null is returned.
90      *
91      * @param flags Supplies additional options controlling how the text is
92      * returned.  May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
93      * @return Returns the text that is currently selected, if any, or null if
94      * no text is selected.
95      */
getSelectedText(int flags)96     public CharSequence getSelectedText(int flags);
97 
98     /**
99      * Retrieve the current capitalization mode in effect at the current
100      * cursor position in the text.  See
101      * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode} for
102      * more information.
103      *
104      * <p>This method may fail either if the input connection has become invalid
105      * (such as its process crashing) or the client is taking too long to
106      * respond with the text (it is given a couple seconds to return).
107      * In either case, a 0 is returned.
108      *
109      * @param reqModes The desired modes to retrieve, as defined by
110      * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}.  These
111      * constants are defined so that you can simply pass the current
112      * {@link EditorInfo#inputType TextBoxAttribute.contentType} value
113      * directly in to here.
114      *
115      * @return Returns the caps mode flags that are in effect.
116      */
getCursorCapsMode(int reqModes)117     public int getCursorCapsMode(int reqModes);
118 
119     /**
120      * Retrieve the current text in the input connection's editor, and monitor
121      * for any changes to it.  This function returns with the current text,
122      * and optionally the input connection can send updates to the
123      * input method when its text changes.
124      *
125      * <p>This method may fail either if the input connection has become invalid
126      * (such as its process crashing) or the client is taking too long to
127      * respond with the text (it is given a couple seconds to return).
128      * In either case, a null is returned.
129      *
130      * @param request Description of how the text should be returned.
131      * @param flags Additional options to control the client, either 0 or
132      * {@link #GET_EXTRACTED_TEXT_MONITOR}.
133      *
134      * @return Returns an ExtractedText object describing the state of the
135      * text view and containing the extracted text itself.
136      */
getExtractedText(ExtractedTextRequest request, int flags)137     public ExtractedText getExtractedText(ExtractedTextRequest request,
138             int flags);
139 
140     /**
141      * Delete <var>leftLength</var> characters of text before the current cursor
142      * position, and delete <var>rightLength</var> characters of text after the
143      * current cursor position, excluding composing text.
144      *
145      * @param leftLength The number of characters to be deleted before the
146      *        current cursor position.
147      * @param rightLength The number of characters to be deleted after the
148      *        current cursor position.
149      *
150      * @return Returns true on success, false if the input connection is no longer
151      * valid.
152      */
deleteSurroundingText(int leftLength, int rightLength)153     public boolean deleteSurroundingText(int leftLength, int rightLength);
154 
155     /**
156      * Set composing text around the current cursor position with the given text,
157      * and set the new cursor position.  Any composing text set previously will
158      * be removed automatically.
159      *
160      * @param text The composing text with styles if necessary. If no style
161      *        object attached to the text, the default style for composing text
162      *        is used. See {#link android.text.Spanned} for how to attach style
163      *        object to the text. {#link android.text.SpannableString} and
164      *        {#link android.text.SpannableStringBuilder} are two
165      *        implementations of the interface {#link android.text.Spanned}.
166      * @param newCursorPosition The new cursor position around the text.  If
167      *        > 0, this is relative to the end of the text - 1; if <= 0, this
168      *        is relative to the start of the text.  So a value of 1 will
169      *        always advance you to the position after the full text being
170      *        inserted.  Note that this means you can't position the cursor
171      *        within the text, because the editor can make modifications to
172      *        the text you are providing so it is not possible to correctly
173      *        specify locations there.
174      *
175      * @return Returns true on success, false if the input connection is no longer
176      * valid.
177      */
setComposingText(CharSequence text, int newCursorPosition)178     public boolean setComposingText(CharSequence text, int newCursorPosition);
179 
180     /**
181      * Mark a certain region of text as composing text. Any composing text set
182      * previously will be removed automatically. The default style for composing
183      * text is used.
184      *
185      * @param start the position in the text at which the composing region begins
186      * @param end the position in the text at which the composing region ends
187      * @return Returns true on success, false if the input connection is no longer
188      * valid.
189      */
setComposingRegion(int start, int end)190     public boolean setComposingRegion(int start, int end);
191 
192     /**
193      * Have the text editor finish whatever composing text is currently
194      * active.  This simply leaves the text as-is, removing any special
195      * composing styling or other state that was around it.  The cursor
196      * position remains unchanged.
197      */
finishComposingText()198     public boolean finishComposingText();
199 
200     /**
201      * Commit text to the text box and set the new cursor position.
202      * Any composing text set previously will be removed
203      * automatically.
204      *
205      * @param text The committed text.
206      * @param newCursorPosition The new cursor position around the text.  If
207      *        > 0, this is relative to the end of the text - 1; if <= 0, this
208      *        is relative to the start of the text.  So a value of 1 will
209      *        always advance you to the position after the full text being
210      *        inserted.  Note that this means you can't position the cursor
211      *        within the text, because the editor can make modifications to
212      *        the text you are providing so it is not possible to correctly
213      *        specify locations there.
214      *
215      *
216      * @return Returns true on success, false if the input connection is no longer
217      * valid.
218      */
commitText(CharSequence text, int newCursorPosition)219     public boolean commitText(CharSequence text, int newCursorPosition);
220 
221     /**
222      * Commit a completion the user has selected from the possible ones
223      * previously reported to {@link InputMethodSession#displayCompletions
224      * InputMethodSession.displayCompletions()}.  This will result in the
225      * same behavior as if the user had selected the completion from the
226      * actual UI.
227      *
228      * @param text The committed completion.
229      *
230      * @return Returns true on success, false if the input connection is no longer
231      * valid.
232      */
commitCompletion(CompletionInfo text)233     public boolean commitCompletion(CompletionInfo text);
234 
235     /**
236      * Commit a correction automatically performed on the raw user's input. A typical example would
237      * be to correct typos using a dictionary.
238      *
239      * @param correctionInfo Detailed information about the correction.
240      *
241      * @return True on success, false if the input connection is no longer valid.
242      */
commitCorrection(CorrectionInfo correctionInfo)243     public boolean commitCorrection(CorrectionInfo correctionInfo);
244 
245     /**
246      * Set the selection of the text editor.  To set the cursor position,
247      * start and end should have the same value.
248      * @return Returns true on success, false if the input connection is no longer
249      * valid.
250      */
setSelection(int start, int end)251     public boolean setSelection(int start, int end);
252 
253     /**
254      * Have the editor perform an action it has said it can do.
255      *
256      * @param editorAction This must be one of the action constants for
257      * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as
258      * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}.
259      *
260      * @return Returns true on success, false if the input connection is no longer
261      * valid.
262      */
performEditorAction(int editorAction)263     public boolean performEditorAction(int editorAction);
264 
265     /**
266      * Perform a context menu action on the field.  The given id may be one of:
267      * {@link android.R.id#selectAll},
268      * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText},
269      * {@link android.R.id#cut}, {@link android.R.id#copy},
270      * {@link android.R.id#paste}, {@link android.R.id#copyUrl},
271      * or {@link android.R.id#switchInputMethod}
272      */
performContextMenuAction(int id)273     public boolean performContextMenuAction(int id);
274 
275     /**
276      * Tell the editor that you are starting a batch of editor operations.
277      * The editor will try to avoid sending you updates about its state
278      * until {@link #endBatchEdit} is called.
279      */
beginBatchEdit()280     public boolean beginBatchEdit();
281 
282     /**
283      * Tell the editor that you are done with a batch edit previously
284      * initiated with {@link #endBatchEdit}.
285      */
endBatchEdit()286     public boolean endBatchEdit();
287 
288     /**
289      * Send a key event to the process that is currently attached through
290      * this input connection.  The event will be dispatched like a normal
291      * key event, to the currently focused; this generally is the view that
292      * is providing this InputConnection, but due to the asynchronous nature
293      * of this protocol that can not be guaranteed and the focus may have
294      * changed by the time the event is received.
295      *
296      * <p>
297      * This method can be used to send key events to the application. For
298      * example, an on-screen keyboard may use this method to simulate a hardware
299      * keyboard. There are three types of standard keyboards, numeric (12-key),
300      * predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type
301      * by specify the device id of the key event.
302      *
303      * <p>
304      * You will usually want to set the flag
305      * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} on all
306      * key event objects you give to this API; the flag will not be set
307      * for you.
308      *
309      * @param event The key event.
310      *
311      * @return Returns true on success, false if the input connection is no longer
312      * valid.
313      *
314      * @see KeyEvent
315      * @see KeyCharacterMap#NUMERIC
316      * @see KeyCharacterMap#PREDICTIVE
317      * @see KeyCharacterMap#ALPHA
318      */
sendKeyEvent(KeyEvent event)319     public boolean sendKeyEvent(KeyEvent event);
320 
321     /**
322      * Clear the given meta key pressed states in the given input connection.
323      *
324      * @param states The states to be cleared, may be one or more bits as
325      * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}.
326      *
327      * @return Returns true on success, false if the input connection is no longer
328      * valid.
329      */
clearMetaKeyStates(int states)330     public boolean clearMetaKeyStates(int states);
331 
332     /**
333      * Called by the IME to tell the client when it switches between fullscreen
334      * and normal modes.  This will normally be called for you by the standard
335      * implementation of {@link android.inputmethodservice.InputMethodService}.
336      */
reportFullscreenMode(boolean enabled)337     public boolean reportFullscreenMode(boolean enabled);
338 
339     /**
340      * API to send private commands from an input method to its connected
341      * editor.  This can be used to provide domain-specific features that are
342      * only known between certain input methods and their clients.  Note that
343      * because the InputConnection protocol is asynchronous, you have no way
344      * to get a result back or know if the client understood the command; you
345      * can use the information in {@link EditorInfo} to determine if
346      * a client supports a particular command.
347      *
348      * @param action Name of the command to be performed.  This <em>must</em>
349      * be a scoped name, i.e. prefixed with a package name you own, so that
350      * different developers will not create conflicting commands.
351      * @param data Any data to include with the command.
352      * @return Returns true if the command was sent (whether or not the
353      * associated editor understood it), false if the input connection is no longer
354      * valid.
355      */
performPrivateCommand(String action, Bundle data)356     public boolean performPrivateCommand(String action, Bundle data);
357 }
358