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 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     */
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     */
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     */
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     */
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     */
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     */
138    public void dispatchTrackballEvent(int seq, MotionEvent event, EventCallback callback);
139
140    /**
141     * This method is called when there is a generic motion event.
142     *
143     * <p>
144     * If the input method wants to handle this event, return true, otherwise
145     * return false and the caller (i.e. the application) will handle the event.
146     *
147     * @param event The motion event.
148     *
149     * @return Whether the input method wants to handle this event.
150     *
151     * @see android.view.MotionEvent
152     */
153    public void dispatchGenericMotionEvent(int seq, MotionEvent event, EventCallback callback);
154
155    /**
156     * Process a private command sent from the application to the input method.
157     * This can be used to provide domain-specific features that are
158     * only known between certain input methods and their clients.
159     *
160     * @param action Name of the command to be performed.  This <em>must</em>
161     * be a scoped name, i.e. prefixed with a package name you own, so that
162     * different developers will not create conflicting commands.
163     * @param data Any data to include with the command.
164     */
165    public void appPrivateCommand(String action, Bundle data);
166
167    /**
168     * Toggle the soft input window.
169     * Applications can toggle the state of the soft input window.
170     * @param showFlags Provides additional operating flags.  May be
171     * 0 or have the {@link InputMethodManager#SHOW_IMPLICIT},
172     * {@link InputMethodManager#SHOW_FORCED} bit set.
173     * @param hideFlags Provides additional operating flags.  May be
174     * 0 or have the {@link  InputMethodManager#HIDE_IMPLICIT_ONLY},
175     * {@link  InputMethodManager#HIDE_NOT_ALWAYS} bit set.
176     */
177    public void toggleSoftInput(int showFlags, int hideFlags);
178
179    /**
180     * This method is called when the cursor and/or the character position relevant to text input
181     * is changed on the screen.  This is not called by default.  It will only be reported if
182     * requested by the input method.
183     *
184     * @param cursorAnchorInfo Positional information relevant to text input, such as text
185     * insertion point and composition string.
186     */
187    public void updateCursorAnchorInfo(CursorAnchorInfo cursorAnchorInfo);
188}
189