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 #dispatchKeyUp 121 * @see android.view.KeyEvent 122 */ dispatchKeyEvent(int seq, KeyEvent event, EventCallback callback)123 public void dispatchKeyEvent(int seq, KeyEvent event, EventCallback callback); 124 125 /** 126 * This method is called when there is a track ball event. 127 * 128 * <p> 129 * If the input method wants to handle this event, return true, otherwise 130 * return false and the caller (i.e. the application) will handle the event. 131 * 132 * @param event The motion event. 133 * 134 * @return Whether the input method wants to handle this event. 135 * 136 * @see android.view.MotionEvent 137 */ dispatchTrackballEvent(int seq, MotionEvent event, EventCallback callback)138 public void dispatchTrackballEvent(int seq, MotionEvent event, EventCallback callback); 139 140 /** 141 * Process a private command sent from the application to the input method. 142 * This can be used to provide domain-specific features that are 143 * only known between certain input methods and their clients. 144 * 145 * @param action Name of the command to be performed. This <em>must</em> 146 * be a scoped name, i.e. prefixed with a package name you own, so that 147 * different developers will not create conflicting commands. 148 * @param data Any data to include with the command. 149 */ appPrivateCommand(String action, Bundle data)150 public void appPrivateCommand(String action, Bundle data); 151 152 /** 153 * Toggle the soft input window. 154 * Applications can toggle the state of the soft input window. 155 * @param showFlags Provides additional operating flags. May be 156 * 0 or have the {@link InputMethodManager#SHOW_IMPLICIT}, 157 * {@link InputMethodManager#SHOW_FORCED} bit set. 158 * @param hideFlags Provides additional operating flags. May be 159 * 0 or have the {@link InputMethodManager#HIDE_IMPLICIT_ONLY}, 160 * {@link InputMethodManager#HIDE_NOT_ALWAYS} bit set. 161 */ toggleSoftInput(int showFlags, int hideFlags)162 public void toggleSoftInput(int showFlags, int hideFlags); 163 } 164