InputMethodSession.java revision 4df2423a947bcd3f024cc3d3a1a315a8dc428598
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 17package android.view.inputmethod; 18 19import android.graphics.Rect; 20import android.os.Bundle; 21import android.view.KeyEvent; 22import 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 */ 32public interface InputMethodSession { 33 34 public interface EventCallback { 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 */ 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 */ 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 cursor location of the target input field 67 * has changed within its window. This is not normally called, but will 68 * only be reported if requested by the input method. 69 * 70 * @param newCursor The rectangle of the cursor currently being shown in 71 * the input field's window coordinates. 72 */ 73 public void updateCursor(Rect newCursor); 74 75 /** 76 * Called by a text editor that performs auto completion, to tell the 77 * input method about the completions it has available. This can be used 78 * by the input method to display them to the user to select the text to 79 * be inserted. 80 * 81 * @param completions Array of text completions that are available, starting with 82 * the best. If this array is null, any existing completions will be 83 * removed. 84 */ 85 public void displayCompletions(CompletionInfo[] completions); 86 87 /** 88 * Called by a text editor to report its new extracted text when its 89 * contents change. This will only be called if the input method 90 * calls {@link InputConnection#getExtractedText(ExtractedTextRequest, int) 91 * InputConnection.getExtractedText()} with the option to report updates. 92 * 93 * @param token The input method supplied token for identifying its request. 94 * @param text The new extracted text. 95 */ 96 public void updateExtractedText(int token, ExtractedText text); 97 98 /** 99 * This method is called when a key is pressed. When done with the event, 100 * the implementation must call back on <var>callback</var> with its 101 * result. 102 * 103 * <p> 104 * If the input method wants to handle this event, return true, otherwise 105 * return false and the caller (i.e. the application) will handle the event. 106 * 107 * @param event The key event. 108 * 109 * @return Whether the input method wants to handle this event. 110 * 111 * @see #dispatchKeyUp 112 * @see android.view.KeyEvent 113 */ 114 public void dispatchKeyEvent(int seq, KeyEvent event, EventCallback callback); 115 116 /** 117 * This method is called when there is a track ball event. 118 * 119 * <p> 120 * If the input method wants to handle this event, return true, otherwise 121 * return false and the caller (i.e. the application) will handle the event. 122 * 123 * @param event The motion event. 124 * 125 * @return Whether the input method wants to handle this event. 126 * 127 * @see android.view.MotionEvent 128 */ 129 public void dispatchTrackballEvent(int seq, MotionEvent event, EventCallback callback); 130 131 /** 132 * Process a private command sent from the application to the input method. 133 * This can be used to provide domain-specific features that are 134 * only known between certain input methods and their clients. 135 * 136 * @param action Name of the command to be performed. This <em>must</em> 137 * be a scoped name, i.e. prefixed with a package name you own, so that 138 * different developers will not create conflicting commands. 139 * @param data Any data to include with the command. 140 */ 141 public void appPrivateCommand(String action, Bundle data); 142 143 /** 144 * Toggle the soft input window. 145 * Applications can toggle the state of the soft input window. 146 * @param showFlags Provides additional operating flags. May be 147 * 0 or have the {@link InputMethodManager#SHOW_IMPLICIT}, 148 * {@link InputMethodManager#SHOW_FORCED} bit set. 149 * @param hideFlags Provides additional operating flags. May be 150 * 0 or have the {@link InputMethodManager#HIDE_IMPLICIT_ONLY}, 151 * {@link InputMethodManager#HIDE_NOT_ALWAYS} bit set. 152 */ 153 public void toggleSoftInput(int showFlags, int hideFlags); 154} 155