| blob | 0f3befa1d946a4b5611ef82786824ad2e2d3e021 |
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
4 * You can obtain one at http://mozilla.org/MPL/2.0/.
5 */
7 [JSImplementation="@mozilla.org/b2g-inputmethod;1",
8 NavigatorProperty="mozInputMethod",
9 Func="Navigator::HasInputMethodSupport"]
10 interface MozInputMethod : EventTarget {
11 // Input Method Manager contain a few global methods expose to apps
12 readonly attribute MozInputMethodManager mgmt;
14 // Fired when the input context changes, include changes from and to null.
15 // The new InputContext instance will be available in the event
16 // object under |inputcontext| property. When it changes to null it
17 // means the app (the user of this API) no longer has the control of
18 // the original focused input field.
19 // Note that if the app saves the original context, it might get
20 // void; implementation decides when to void the input context.
21 attribute EventHandler oninputcontextchange;
23 // An "input context" is mapped to a text field that the app is
24 // allow to mutate. this attribute should be null when there is no
25 // text field currently focused.
26 readonly attribute MozInputContext? inputcontext;
28 [ChromeOnly]
29 // Activate or decactive current input method window.
30 void setActive(boolean isActive);
31 };
33 // Manages the list of IMEs, enables/disables IME and switches to an
34 // IME.
35 [JSImplementation="@mozilla.org/b2g-imm;1",
36 Pref="dom.mozInputMethod.enabled"]
37 interface MozInputMethodManager {
38 // Ask the OS to show a list of available IMEs for users to switch from.
39 // OS should ignore this request if the app is currently not the active one.
40 void showAll();
42 // Ask the OS to switch away from the current active Keyboard app.
43 // OS should ignore this request if the app is currently not the active one.
44 void next();
46 // To know if the OS supports IME switching or not.
47 // Use case: let the keyboard app knows if it is necessary to show the "IME switching"
48 // (globe) button. We have a use case that when there is only one IME enabled, we
49 // should not show the globe icon.
50 boolean supportsSwitching();
52 // Ask the OS to hide the current active Keyboard app. (was: |removeFocus()|)
53 // OS should ignore this request if the app is currently not the active one.
54 // The OS will void the current input context (if it exists).
55 // This method belong to |mgmt| because we would like to allow Keyboard to access to
56 // this method w/o a input context.
57 void hide();
58 };
60 // The input context, which consists of attributes and information of current input field.
61 // It also hosts the methods available to the keyboard app to mutate the input field represented.
62 // An "input context" gets void when the app is no longer allowed to interact with the text field,
63 // e.g., the text field does no longer exist, the app is being switched to background, and etc.
64 [JSImplementation="@mozilla.org/b2g-inputcontext;1",
65 Pref="dom.mozInputMethod.enabled"]
66 interface MozInputContext: EventTarget {
67 // The tag name of input field, which is enum of "input", "textarea", or "contenteditable"
68 readonly attribute DOMString? type;
69 // The type of the input field, which is enum of text, number, password, url, search, email, and so on.
70 // See http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#states-of-the-type-attribute
71 readonly attribute DOMString? inputType;
72 /*
73 * The inputmode string, representing the input mode.
74 * See http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#input-modalities:-the-inputmode-attribute
75 */
76 readonly attribute DOMString? inputMode;
77 /*
78 * The primary language for the input field.
79 * It is the value of HTMLElement.lang.
80 * See http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement
81 */
82 readonly attribute DOMString? lang;
83 /*
84 * Get the whole text content of the input field.
85 * @return DOMString
86 */
87 Promise getText(optional long offset, optional long length);
88 // The start and stop position of the selection.
89 readonly attribute long selectionStart;
90 readonly attribute long selectionEnd;
92 // The start and stop position of the selection.
93 readonly attribute DOMString? textBeforeCursor;
94 readonly attribute DOMString? textAfterCursor;
96 /*
97 * Set the selection range of the the editable text.
98 * Note: This method cannot be used to move the cursor during composition. Calling this
99 * method will cancel composition.
100 * @param start The beginning of the selected text.
101 * @param length The length of the selected text.
102 *
103 * Note that the start position should be less or equal to the end position.
104 * To move the cursor, set the start and end position to the same value.
105 *
106 * @return boolean
107 */
108 Promise setSelectionRange(long start, long length);
110 /* User moves the cursor, or changes the selection with other means. If the text around
111 * cursor has changed, but the cursor has not been moved, the IME won't get notification.
112 */
113 attribute EventHandler onselectionchange;
115 /*
116 * Commit text to current input field and replace text around
117 * cursor position. It will clear the current composition.
118 *
119 * @param text The string to be replaced with.
120 * @param offset The offset from the cursor position where replacing starts. Defaults to 0.
121 * @param length The length of text to replace. Defaults to 0.
122 * @return boolean
123 */
124 Promise replaceSurroundingText(DOMString text, optional long offset, optional long length);
126 /*
127 *
128 * Delete text around the cursor.
129 * @param offset The offset from the cursor position where deletion starts.
130 * @param length The length of text to delete.
131 * TODO: maybe updateSurroundingText(DOMString beforeText, DOMString afterText); ?
132 * @return boolean
133 */
134 Promise deleteSurroundingText(long offset, long length);
136 /*
137 * Notifies when the text around the cursor is changed, due to either text
138 * editing or cursor movement. If the cursor has been moved, but the text around has not
139 * changed, the IME won't get notification.
140 *
141 * The event handler function is specified as:
142 * @param beforeString Text before and including cursor position.
143 * @param afterString Text after and excluing cursor position.
144 * function(DOMString beforeText, DOMString afterText) {
145 * ...
146 * }
147 */
148 attribute EventHandler onsurroundingtextchange;
150 /*
151 * send a character with its key events.
152 * @param modifiers see http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/base/nsIDOMWindowUtils.idl#206
153 * @return true if succeeds. Otherwise false if the input context becomes void.
154 * Alternative: sendKey(KeyboardEvent event), but we will likely
155 * waste memory for creating the KeyboardEvent object.
156 */
157 Promise sendKey(long keyCode, long charCode, long modifiers);
159 /*
160 * Set current composing text. This method will start composition or update
161 * composition if it has started. The composition will be started right
162 * before the cursor position and any selected text will be replaced by the
163 * composing text. When the composition is started, calling this method can
164 * update the text and move cursor winthin the range of the composing text.
165 * @param text The new composition text to show.
166 * @param cursor The new cursor position relative to the start of the
167 * composition text. The cursor should be positioned within the composition
168 * text. This means the value should be >= 0 and <= the length of
169 * composition text. Defaults to the lenght of composition text, i.e., the
170 * cursor will be positioned after the composition text.
171 * @param clauses The array of composition clause information. If not set,
172 * only one clause is supported.
173 *
174 * The composing text, which is shown with underlined style to distinguish
175 * from the existing text, is used to compose non-ASCII characters from
176 * keystrokes, e.g. Pinyin or Hiragana. The composing text is the
177 * intermediate text to help input complex character and is not committed to
178 * current input field. Therefore if any text operation other than
179 * composition is performed, the composition will automatically end. Same
180 * apply when the inputContext is lost during an unfinished composition
181 * session.
182 *
183 * To finish composition and commit text to current input field, an IME
184 * should call |endComposition|.
185 */
186 Promise setComposition(DOMString text, optional long cursor,
187 optional sequence<CompositionClauseParameters> clauses);
189 /*
190 * End composition, clear the composing text and commit given text to
191 * current input field. The text will be committed before the cursor
192 * position.
193 * @param text The text to commited before cursor position. If empty string
194 * is given, no text will be committed.
195 *
196 * Note that composition always ends automatically with nothing to commit if
197 * the composition does not explicitly end by calling |endComposition|, but
198 * is interrupted by |sendKey|, |setSelectionRange|,
199 * |replaceSurroundingText|, |deleteSurroundingText|, user moving the
200 * cursor, changing the focus, etc.
201 */
202 Promise endComposition(optional DOMString text);
203 };
205 enum CompositionClauseSelectionType {
206 "raw-input",
207 "selected-raw-text",
208 "converted-text",
209 "selected-converted-text"
210 };
212 dictionary CompositionClauseParameters {
213 DOMString selectionType = "raw-input";
214 long length;
215 };