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.graphics.Rect; 20 import android.inputmethodservice.InputMethodService; 21 import android.os.Bundle; 22 import android.view.KeyEvent; 23 import android.view.MotionEvent; 24 25 import com.android.internal.view.IInputContext; 26 27 /** 28 * The InputMethodSession interface provides the per-client functionality 29 * of {@link InputMethod} that is safe to expose to applications. 30 * 31 * <p>Applications will not normally use this interface themselves, instead 32 * relying on the standard interaction provided by 33 * {@link android.widget.TextView} and {@link android.widget.EditText}. 34 */ 35 public interface InputMethodSession { 36 37 public interface EventCallback { finishedEvent(int seq, boolean handled)38 void finishedEvent(int seq, boolean handled); 39 } 40 41 /** 42 * This method is called when the application would like to stop 43 * receiving text input. 44 */ finishInput()45 public void finishInput(); 46 47 /** 48 * This method is called when the selection or cursor in the current 49 * target input field has changed. 50 * 51 * @param oldSelStart The previous text offset of the cursor selection 52 * start position. 53 * @param oldSelEnd The previous text offset of the cursor selection 54 * end position. 55 * @param newSelStart The new text offset of the cursor selection 56 * start position. 57 * @param newSelEnd The new text offset of the cursor selection 58 * end position. 59 * @param candidatesStart The text offset of the current candidate 60 * text start position. 61 * @param candidatesEnd The text offset of the current candidate 62 * text end position. 63 */ updateSelection(int oldSelStart, int oldSelEnd, int newSelStart, int newSelEnd, int candidatesStart, int candidatesEnd)64 public void updateSelection(int oldSelStart, int oldSelEnd, 65 int newSelStart, int newSelEnd, 66 int candidatesStart, int candidatesEnd); 67 68 /** 69 * This method is called when the user tapped a text view. 70 * IMEs can't rely on this method being called because this was not part of the original IME 71 * protocol, so applications with custom text editing written before this method appeared will 72 * not call to inform the IME of this interaction. 73 * @param focusChanged true if the user changed the focused view by this click. 74 */ viewClicked(boolean focusChanged)75 public void viewClicked(boolean focusChanged); 76 77 /** 78 * This method is called when cursor location of the target input field 79 * has changed within its window. This is not normally called, but will 80 * only be reported if requested by the input method. 81 * 82 * @param newCursor The rectangle of the cursor currently being shown in 83 * the input field's window coordinates. 84 */ updateCursor(Rect newCursor)85 public void updateCursor(Rect newCursor); 86 87 /** 88 * Called by a text editor that performs auto completion, to tell the 89 * input method about the completions it has available. This can be used 90 * by the input method to display them to the user to select the text to 91 * be inserted. 92 * 93 * @param completions Array of text completions that are available, starting with 94 * the best. If this array is null, any existing completions will be 95 * removed. 96 */ displayCompletions(CompletionInfo[] completions)97 public void displayCompletions(CompletionInfo[] completions); 98 99 /** 100 * Called by a text editor to report its new extracted text when its 101 * contents change. This will only be called if the input method 102 * calls {@link InputConnection#getExtractedText(ExtractedTextRequest, int) 103 * InputConnection.getExtractedText()} with the option to report updates. 104 * 105 * @param token The input method supplied token for identifying its request. 106 * @param text The new extracted text. 107 */ updateExtractedText(int token, ExtractedText text)108 public void updateExtractedText(int token, ExtractedText text); 109 110 /** 111 * This method is called when a key is pressed. When done with the event, 112 * the implementation must call back on <var>callback</var> with its 113 * result. 114 * 115 * <p> 116 * If the input method wants to handle this event, return true, otherwise 117 * return false and the caller (i.e. the application) will handle the event. 118 * 119 * @param event The key event. 120 * 121 * @return Whether the input method wants to handle this event. 122 * 123 * @see android.view.KeyEvent 124 */ dispatchKeyEvent(int seq, KeyEvent event, EventCallback callback)125 public void dispatchKeyEvent(int seq, KeyEvent event, EventCallback callback); 126 127 /** 128 * This method is called when there is a track ball event. 129 * 130 * <p> 131 * If the input method wants to handle this event, return true, otherwise 132 * return false and the caller (i.e. the application) will handle the event. 133 * 134 * @param event The motion event. 135 * 136 * @return Whether the input method wants to handle this event. 137 * 138 * @see android.view.MotionEvent 139 */ dispatchTrackballEvent(int seq, MotionEvent event, EventCallback callback)140 public void dispatchTrackballEvent(int seq, MotionEvent event, EventCallback callback); 141 142 /** 143 * This method is called when there is a generic motion event. 144 * 145 * <p> 146 * If the input method wants to handle this event, return true, otherwise 147 * return false and the caller (i.e. the application) will handle the event. 148 * 149 * @param event The motion event. 150 * 151 * @return Whether the input method wants to handle this event. 152 * 153 * @see android.view.MotionEvent 154 */ dispatchGenericMotionEvent(int seq, MotionEvent event, EventCallback callback)155 public void dispatchGenericMotionEvent(int seq, MotionEvent event, EventCallback callback); 156 157 /** 158 * Process a private command sent from the application to the input method. 159 * This can be used to provide domain-specific features that are 160 * only known between certain input methods and their clients. 161 * 162 * @param action Name of the command to be performed. This <em>must</em> 163 * be a scoped name, i.e. prefixed with a package name you own, so that 164 * different developers will not create conflicting commands. 165 * @param data Any data to include with the command. 166 */ appPrivateCommand(String action, Bundle data)167 public void appPrivateCommand(String action, Bundle data); 168 169 /** 170 * Toggle the soft input window. 171 * Applications can toggle the state of the soft input window. 172 * @param showFlags Provides additional operating flags. May be 173 * 0 or have the {@link InputMethodManager#SHOW_IMPLICIT}, 174 * {@link InputMethodManager#SHOW_FORCED} bit set. 175 * @param hideFlags Provides additional operating flags. May be 176 * 0 or have the {@link InputMethodManager#HIDE_IMPLICIT_ONLY}, 177 * {@link InputMethodManager#HIDE_NOT_ALWAYS} bit set. 178 * 179 * @deprecated Starting in {@link android.os.Build.VERSION_CODES#S} the system no longer invokes 180 * this method, instead it explicitly shows or hides the IME. An {@code InputMethodService} 181 * wishing to toggle its own visibility should instead invoke {@link 182 * InputMethodService#requestShowSelf} or {@link InputMethodService#requestHideSelf} 183 */ 184 @Deprecated toggleSoftInput(int showFlags, int hideFlags)185 public void toggleSoftInput(int showFlags, int hideFlags); 186 187 /** 188 * This method is called when the cursor and/or the character position relevant to text input 189 * is changed on the screen. This is not called by default. It will only be reported if 190 * requested by the input method. 191 * 192 * @param cursorAnchorInfo Positional information relevant to text input, such as text 193 * insertion point and composition string. 194 */ updateCursorAnchorInfo(CursorAnchorInfo cursorAnchorInfo)195 public void updateCursorAnchorInfo(CursorAnchorInfo cursorAnchorInfo); 196 197 /** 198 * Notify IME directly to remove surface as it is no longer visible. 199 * @hide 200 */ removeImeSurface()201 public void removeImeSurface(); 202 203 /** 204 * Called when {@code inputContext} is about to be reset with {@code sessionId}. 205 * 206 * <p>The actual implementation should ignore if {@code inputContext} is no longer the current 207 * {@link InputConnection} due to a stale callback.</p> 208 * 209 * @param editorInfo {@link EditorInfo} to be used 210 * @param inputContext specifies which {@link InputConnection} is being updated. 211 * @param sessionId the ID to be specified to 212 * {@link com.android.internal.inputmethod.InputConnectionCommandHeader}. 213 * @hide 214 */ invalidateInputInternal(EditorInfo editorInfo, IInputContext inputContext, int sessionId)215 default void invalidateInputInternal(EditorInfo editorInfo, IInputContext inputContext, 216 int sessionId) { 217 } 218 } 219