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