1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/webidl/InputMethod.webidl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,248 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.7 + * You can obtain one at http://mozilla.org/MPL/2.0/.
1.8 + */
1.9 +
1.10 +[JSImplementation="@mozilla.org/b2g-inputmethod;1",
1.11 + NavigatorProperty="mozInputMethod",
1.12 + Func="Navigator::HasInputMethodSupport"]
1.13 +interface MozInputMethod : EventTarget {
1.14 + // Input Method Manager contain a few global methods expose to apps
1.15 + readonly attribute MozInputMethodManager mgmt;
1.16 +
1.17 + // Fired when the input context changes, include changes from and to null.
1.18 + // The new InputContext instance will be available in the event
1.19 + // object under |inputcontext| property. When it changes to null it
1.20 + // means the app (the user of this API) no longer has the control of
1.21 + // the original focused input field.
1.22 + // Note that if the app saves the original context, it might get
1.23 + // void; implementation decides when to void the input context.
1.24 + attribute EventHandler oninputcontextchange;
1.25 +
1.26 + // An "input context" is mapped to a text field that the app is
1.27 + // allow to mutate. this attribute should be null when there is no
1.28 + // text field currently focused.
1.29 + readonly attribute MozInputContext? inputcontext;
1.30 +
1.31 + [ChromeOnly]
1.32 + // Activate or decactive current input method window.
1.33 + void setActive(boolean isActive);
1.34 +
1.35 + // The following are internal methods for Firefox OS system app only.
1.36 +
1.37 + // Set the value on the currently focused element. This has to be used
1.38 + // for special situations where the value had to be chosen amongst a
1.39 + // list (type=month) or a widget (type=date, time, etc.).
1.40 + // If the value passed in parameter isn't valid (in the term of HTML5
1.41 + // Forms Validation), the value will simply be ignored by the element.
1.42 + [Throws]
1.43 + void setValue(DOMString value);
1.44 +
1.45 + // Select the <select> option specified by index.
1.46 + // If this method is called on a <select> that support multiple
1.47 + // selection, then the option specified by index will be added to
1.48 + // the selection.
1.49 + // If this method is called for a select that does not support multiple
1.50 + // selection the previous element will be unselected.
1.51 + [Throws]
1.52 + void setSelectedOption(long index);
1.53 +
1.54 + // Select the <select> options specified by indexes. All other options
1.55 + // will be deselected.
1.56 + // If this method is called for a <select> that does not support multiple
1.57 + // selection, then the last index specified in indexes will be selected.
1.58 + [Throws]
1.59 + void setSelectedOptions(sequence<long> indexes);
1.60 +
1.61 + [Throws]
1.62 + void removeFocus();
1.63 +};
1.64 +
1.65 +// Manages the list of IMEs, enables/disables IME and switches to an
1.66 +// IME.
1.67 +[JSImplementation="@mozilla.org/b2g-imm;1",
1.68 + Pref="dom.mozInputMethod.enabled"]
1.69 +interface MozInputMethodManager {
1.70 + // Ask the OS to show a list of available IMEs for users to switch from.
1.71 + // OS should ignore this request if the app is currently not the active one.
1.72 + void showAll();
1.73 +
1.74 + // Ask the OS to switch away from the current active Keyboard app.
1.75 + // OS should ignore this request if the app is currently not the active one.
1.76 + void next();
1.77 +
1.78 + // To know if the OS supports IME switching or not.
1.79 + // Use case: let the keyboard app knows if it is necessary to show the "IME switching"
1.80 + // (globe) button. We have a use case that when there is only one IME enabled, we
1.81 + // should not show the globe icon.
1.82 + boolean supportsSwitching();
1.83 +
1.84 + // Ask the OS to hide the current active Keyboard app. (was: |removeFocus()|)
1.85 + // OS should ignore this request if the app is currently not the active one.
1.86 + // The OS will void the current input context (if it exists).
1.87 + // This method belong to |mgmt| because we would like to allow Keyboard to access to
1.88 + // this method w/o a input context.
1.89 + void hide();
1.90 +};
1.91 +
1.92 +// The input context, which consists of attributes and information of current input field.
1.93 +// It also hosts the methods available to the keyboard app to mutate the input field represented.
1.94 +// An "input context" gets void when the app is no longer allowed to interact with the text field,
1.95 +// e.g., the text field does no longer exist, the app is being switched to background, and etc.
1.96 +[JSImplementation="@mozilla.org/b2g-inputcontext;1",
1.97 + Pref="dom.mozInputMethod.enabled"]
1.98 +interface MozInputContext: EventTarget {
1.99 + // The tag name of input field, which is enum of "input", "textarea", or "contenteditable"
1.100 + readonly attribute DOMString? type;
1.101 + // The type of the input field, which is enum of text, number, password, url, search, email, and so on.
1.102 + // See http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#states-of-the-type-attribute
1.103 + readonly attribute DOMString? inputType;
1.104 + /*
1.105 + * The inputmode string, representing the input mode.
1.106 + * See http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#input-modalities:-the-inputmode-attribute
1.107 + */
1.108 + readonly attribute DOMString? inputMode;
1.109 + /*
1.110 + * The primary language for the input field.
1.111 + * It is the value of HTMLElement.lang.
1.112 + * See http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement
1.113 + */
1.114 + readonly attribute DOMString? lang;
1.115 + /*
1.116 + * Get the whole text content of the input field.
1.117 + * @return DOMString
1.118 + */
1.119 + Promise getText(optional long offset, optional long length);
1.120 + // The start and stop position of the selection.
1.121 + readonly attribute long selectionStart;
1.122 + readonly attribute long selectionEnd;
1.123 +
1.124 + // The text before and after the begining of the selected text.
1.125 + readonly attribute DOMString? textBeforeCursor;
1.126 + readonly attribute DOMString? textAfterCursor;
1.127 +
1.128 + /*
1.129 + * Set the selection range of the the editable text.
1.130 + * Note: This method cannot be used to move the cursor during composition. Calling this
1.131 + * method will cancel composition.
1.132 + * @param start The beginning of the selected text.
1.133 + * @param length The length of the selected text.
1.134 + *
1.135 + * Note that the start position should be less or equal to the end position.
1.136 + * To move the cursor, set the start and end position to the same value.
1.137 + *
1.138 + * @return boolean
1.139 + */
1.140 + Promise setSelectionRange(long start, long length);
1.141 +
1.142 + /* User moves the cursor, or changes the selection with other means. If the text around
1.143 + * cursor has changed, but the cursor has not been moved, the IME won't get notification.
1.144 + */
1.145 + attribute EventHandler onselectionchange;
1.146 +
1.147 + /*
1.148 + * Commit text to current input field and replace text around
1.149 + * cursor position. It will clear the current composition.
1.150 + *
1.151 + * @param text The string to be replaced with.
1.152 + * @param offset The offset from the cursor position where replacing starts. Defaults to 0.
1.153 + * @param length The length of text to replace. Defaults to 0.
1.154 + * @return boolean
1.155 + */
1.156 + Promise replaceSurroundingText(DOMString text, optional long offset, optional long length);
1.157 +
1.158 + /*
1.159 + *
1.160 + * Delete text around the cursor.
1.161 + * @param offset The offset from the cursor position where deletion starts.
1.162 + * @param length The length of text to delete.
1.163 + * TODO: maybe updateSurroundingText(DOMString beforeText, DOMString afterText); ?
1.164 + * @return boolean
1.165 + */
1.166 + Promise deleteSurroundingText(long offset, long length);
1.167 +
1.168 + /*
1.169 + * Notifies when the text around the cursor is changed, due to either text
1.170 + * editing or cursor movement. If the cursor has been moved, but the text around has not
1.171 + * changed, the IME won't get notification.
1.172 + *
1.173 + * The event handler function is specified as:
1.174 + * @param beforeString Text before and including cursor position.
1.175 + * @param afterString Text after and excluing cursor position.
1.176 + * function(DOMString beforeText, DOMString afterText) {
1.177 + * ...
1.178 + * }
1.179 + */
1.180 + attribute EventHandler onsurroundingtextchange;
1.181 +
1.182 + /*
1.183 + * send a character with its key events.
1.184 + * @param modifiers see http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/base/nsIDOMWindowUtils.idl#206
1.185 + * @param repeat indicates whether a key would be sent repeatedly.
1.186 + * @return true if succeeds. Otherwise false if the input context becomes void.
1.187 + * Alternative: sendKey(KeyboardEvent event), but we will likely
1.188 + * waste memory for creating the KeyboardEvent object.
1.189 + * Note that, if you want to send a key n times repeatedly, make sure set
1.190 + * parameter repeat to true and invoke sendKey n-1 times, and then set
1.191 + * repeat to false in the last invoke.
1.192 + */
1.193 + Promise sendKey(long keyCode, long charCode, long modifiers, optional boolean repeat);
1.194 +
1.195 + /*
1.196 + * Set current composing text. This method will start composition or update
1.197 + * composition if it has started. The composition will be started right
1.198 + * before the cursor position and any selected text will be replaced by the
1.199 + * composing text. When the composition is started, calling this method can
1.200 + * update the text and move cursor winthin the range of the composing text.
1.201 + * @param text The new composition text to show.
1.202 + * @param cursor The new cursor position relative to the start of the
1.203 + * composition text. The cursor should be positioned within the composition
1.204 + * text. This means the value should be >= 0 and <= the length of
1.205 + * composition text. Defaults to the lenght of composition text, i.e., the
1.206 + * cursor will be positioned after the composition text.
1.207 + * @param clauses The array of composition clause information. If not set,
1.208 + * only one clause is supported.
1.209 + *
1.210 + * The composing text, which is shown with underlined style to distinguish
1.211 + * from the existing text, is used to compose non-ASCII characters from
1.212 + * keystrokes, e.g. Pinyin or Hiragana. The composing text is the
1.213 + * intermediate text to help input complex character and is not committed to
1.214 + * current input field. Therefore if any text operation other than
1.215 + * composition is performed, the composition will automatically end. Same
1.216 + * apply when the inputContext is lost during an unfinished composition
1.217 + * session.
1.218 + *
1.219 + * To finish composition and commit text to current input field, an IME
1.220 + * should call |endComposition|.
1.221 + */
1.222 + Promise setComposition(DOMString text, optional long cursor,
1.223 + optional sequence<CompositionClauseParameters> clauses);
1.224 +
1.225 + /*
1.226 + * End composition, clear the composing text and commit given text to
1.227 + * current input field. The text will be committed before the cursor
1.228 + * position.
1.229 + * @param text The text to commited before cursor position. If empty string
1.230 + * is given, no text will be committed.
1.231 + *
1.232 + * Note that composition always ends automatically with nothing to commit if
1.233 + * the composition does not explicitly end by calling |endComposition|, but
1.234 + * is interrupted by |sendKey|, |setSelectionRange|,
1.235 + * |replaceSurroundingText|, |deleteSurroundingText|, user moving the
1.236 + * cursor, changing the focus, etc.
1.237 + */
1.238 + Promise endComposition(optional DOMString text);
1.239 +};
1.240 +
1.241 +enum CompositionClauseSelectionType {
1.242 + "raw-input",
1.243 + "selected-raw-text",
1.244 + "converted-text",
1.245 + "selected-converted-text"
1.246 +};
1.247 +
1.248 +dictionary CompositionClauseParameters {
1.249 + DOMString selectionType = "raw-input";
1.250 + long length;
1.251 +};
