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