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