diff options
Diffstat (limited to 'dom/webidl/InputMethod.webidl')
| -rw-r--r-- | dom/webidl/InputMethod.webidl | 738 |
1 files changed, 738 insertions, 0 deletions
diff --git a/dom/webidl/InputMethod.webidl b/dom/webidl/InputMethod.webidl new file mode 100644 index 000000000..ca22dcc1b --- /dev/null +++ b/dom/webidl/InputMethod.webidl @@ -0,0 +1,738 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. + */ + +/** + * InputMethod API implements a bridge between the web content hosting an input + * element and the input content (a.k.a. input app, virtual keyboard app, + * or IME). This API is input content facing in order for it to interact with + * the remote input element. + * The API also contains a few Gaia System app only methods + * (marked with "input-manage" permission) for Gaia System app to interact with + * some types of inputs and to regulate the input apps. + */ +[JSImplementation="@mozilla.org/b2g-inputmethod;1", + NavigatorProperty="mozInputMethod", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputMethod : EventTarget { + /** + * Activate or decactive current API instance. + * Gaia System app call this method via BrowserElement#setInputMethodActive. + */ + [ChromeOnly] + void setActive(boolean isActive); + + /** + * InputMethodManager contain a few global methods expose to input apps. + */ + readonly attribute MozInputMethodManager mgmt; + + /** + * Fired when the input context changes, include changes from and to null. + * The new InputContext instance will be available in the event + * object under |inputcontext| property. When it changes to null it + * means the app (the user of this API) no longer has the control of + * the original focused input field. + * Note that if the app saves the original context, it might get + * void; implementation decides when to void the input context. + */ + attribute EventHandler oninputcontextchange; + + /** + * An "input context" is mapped to a text field that the app is + * allow to mutate. This attribute should be null when there is no + * text field currently focused. + */ + readonly attribute MozInputContext? inputcontext; + + /** + * Add a dynamically declared input. + * + * The id must not be the same with any statically declared input in the app + * manifest. If an input of the same id is already declared, the info of that + * input will be updated. + */ + Promise<void> addInput(DOMString inputId, + MozInputMethodInputManifest inputManifest); + + /** + * Remove a dynamically declared input. + * + * The id must not be the same with any statically declared input in the app + * manifest. Silently resolves if the input is not previously declared; + * rejects if attempt to remove a statically declared input. + */ + Promise<void> removeInput(DOMString id); + + /** + * Remove focus from the current input, usable by Gaia System app, globally, + * regardless of the current focus state. + */ + void removeFocus(); + + /** + * The following are internal methods for Firefox OS System app only, + * for handling the "option" group inputs. + */ + + /** + * Set the value on the currently focused element. This has to be used + * for special situations where the value had to be chosen amongst a + * list (type=month) or a widget (type=date, time, etc.). + * If the value passed in parameter isn't valid (in the term of HTML5 + * Forms Validation), the value will simply be ignored by the element. + */ + void setValue(DOMString value); + + /** + * Select the <select> option specified by index. + * If this method is called on a <select> that support multiple + * selection, then the option specified by index will be added to + * the selection. + * If this method is called for a select that does not support multiple + * selection the previous element will be unselected. + */ + void setSelectedOption(long index); + + /** + * Select the <select> options specified by indexes. All other options + * will be deselected. + * If this method is called for a <select> that does not support multiple + * selection, then the last index specified in indexes will be selected. + */ + void setSelectedOptions(sequence<long> indexes); +}; + +/** + * InputMethodManager contains a few of the global methods for the input app. + */ +[JSImplementation="@mozilla.org/b2g-imm;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputMethodManager : EventTarget { + /** + * Ask the OS to show a list of available inputs for users to switch from. + * OS should sliently ignore this request if the app is currently not the + * active one. + */ + void showAll(); + + /** + * Ask the OS to switch away from the current active input app. + * OS should sliently ignore this request if the app is currently not the + * active one. + */ + void next(); + + /** + * If this method returns true, it is recommended that the input app provides + * a shortcut that would invoke the next() method above, for easy switching + * between inputs -- i.e. show a "global" button on screen if the input app + * implements an on-screen virtual keyboard. + * + * The returning value is depend on the inputType of the current input context. + */ + boolean supportsSwitching(); + + /** + * Ask the OS to remove the input focus, will cause the lost of input context. + * OS should sliently ignore this request if the app is currently not the + * active one. + */ + void hide(); + + /** + * Update Gecko with information on the input types which supportsSwitching() + * should return ture. + * + * @param types Array of input types in which supportsSwitching() should + * return true. + */ + void setSupportsSwitchingTypes(sequence<MozInputMethodInputContextInputTypes> types); + + /** + * CustomEvent dispatches to System when there is an input to handle. + * If the API consumer failed to handle and call preventDefault(), + * there will be a message printed on the console. + * + * evt.detail is defined by MozInputContextFocusEventDetail. + */ + attribute EventHandler oninputcontextfocus; + + /** + * Event dispatches to System when there is no longer an input to handle. + * If the API consumer failed to handle and call preventDefault(), + * there will be a message printed on the console. + */ + attribute EventHandler oninputcontextblur; + + /** + * Event dispatches to System when there is a showAll() call. + * If the API consumer failed to handle and call preventDefault(), + * there will be a message printed on the console. + */ + attribute EventHandler onshowallrequest; + + /** + * Event dispatches to System when there is a next() call. + * If the API consumer failed to handle and call preventDefault(), + * there will be a message printed on the console. + */ + attribute EventHandler onnextrequest; + + /** + * Event dispatches to System when there is a addInput() call. + * The API consumer must call preventDefault() to indicate the event is + * consumed, otherwise the request is not considered handled even if + * waitUntil() was called. + * + * evt.detail is defined by MozInputRegistryEventDetail. + */ + attribute EventHandler onaddinputrequest; + + /** + * Event dispatches to System when there is a removeInput() call. + * The API consumer must call preventDefault() to indicate the event is + * consumed, otherwise the request is not considered handled even if + * waitUntil() was called. + * + * evt.detail is defined by MozInputRegistryEventDetail. + */ + attribute EventHandler onremoveinputrequest; +}; + +/** + * Detail of the inputcontextfocus event. + */ +[JSImplementation="@mozilla.org/b2g-imm-focus;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputContextFocusEventDetail { + /** + * The type of the focused input. + */ + readonly attribute MozInputMethodInputContextTypes type; + /** + * The input type of the focused input. + */ + readonly attribute MozInputMethodInputContextInputTypes inputType; + + /** + * The following is only needed for rendering and handling "option" input types, + * in System app. + */ + + /** + * Current value of the input. + */ + readonly attribute DOMString? value; + /** + * An object representing all the <optgroup> and <option> elements + * in the <select> element. + */ + [Pure, Cached, Frozen] + readonly attribute MozInputContextChoicesInfo? choices; + /** + * Max/min value of <input> + */ + readonly attribute DOMString? min; + readonly attribute DOMString? max; +}; + +/** + * Information about the options within the <select> element. + */ +dictionary MozInputContextChoicesInfo { + boolean multiple; + sequence<MozInputMethodChoiceDict> choices; +}; + +/** + * Content of the option header (<optgroup>) or an option (<option>). + */ +dictionary MozInputMethodChoiceDict { + boolean group; + DOMString text; + boolean disabled; + boolean? inGroup; + boolean? selected; + long? optionIndex; +}; + +/** + * detail of addinputrequest or removeinputrequest event. + */ +[JSImplementation="@mozilla.org/b2g-imm-input-registry;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputRegistryEventDetail { + /** + * Manifest URL of the requesting app. + */ + readonly attribute DOMString manifestURL; + /** + * ID of the input + */ + readonly attribute DOMString inputId; + /** + * Input manifest of the input to add. + * Null for removeinputrequest event. + */ + [Pure, Cached, Frozen] + readonly attribute MozInputMethodInputManifest? inputManifest; + /** + * Resolve or Reject the addInput() or removeInput() call when the passed + * promises are resolved. + */ + [Throws] + void waitUntil(Promise<any> p); +}; + +/** + * The input context, which consists of attributes and information of current + * input field. It also hosts the methods available to the keyboard app to + * mutate the input field represented. An "input context" gets void when the + * app is no longer allowed to interact with the text field, + * e.g., the text field does no longer exist, the app is being switched to + * background, and etc. + */ +[JSImplementation="@mozilla.org/b2g-inputcontext;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputContext: EventTarget { + /** + * Type of the InputContext. See MozInputMethodInputContextTypes + */ + readonly attribute MozInputMethodInputContextTypes? type; + + /** + * InputType of the InputContext. See MozInputMethodInputContextInputTypes. + */ + readonly attribute MozInputMethodInputContextInputTypes? inputType; + + /** + * The inputmode string, representing the inputmode of the input. + * See http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#input-modalities:-the-inputmode-attribute + */ + readonly attribute DOMString? inputMode; + + /** + * The primary language for the input field. + * It is the value of HTMLElement.lang. + * See http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement + */ + readonly attribute DOMString? lang; + + /** + * Get the whole text content of the input field. + * @return DOMString + */ + Promise<DOMString> getText(optional long offset, optional long length); + + /** + * The start and stop position of the current selection. + */ + readonly attribute long selectionStart; + readonly attribute long selectionEnd; + + /** + * The text in the current input. + */ + readonly attribute DOMString? text; + + /** + * The text before and after the begining of the selected text. + * + * You should use the text property instead because these properties are + * truncated at 100 characters. + */ + readonly attribute DOMString? textBeforeCursor; + readonly attribute DOMString? textAfterCursor; + + /** + * Set the selection range of the the editable text. + * Note: This method cannot be used to move the cursor during composition. Calling this + * method will cancel composition. + * @param start The beginning of the selected text. + * @param length The length of the selected text. + * + * Note that the start position should be less or equal to the end position. + * To move the cursor, set the start and end position to the same value. + * + * @return boolean + */ + Promise<boolean> setSelectionRange(long start, long length); + + /* User moves the cursor, or changes the selection with other means. If the text around + * cursor has changed, but the cursor has not been moved, the IME won't get notification. + * + * evt.detail is defined by MozInputContextSelectionChangeEventDetail. + */ + attribute EventHandler onselectionchange; + + /** + * Commit text to current input field and replace text around + * cursor position. It will clear the current composition. + * + * @param text The string to be replaced with. + * @param offset The offset from the cursor position where replacing starts. Defaults to 0. + * @param length The length of text to replace. Defaults to 0. + * @return boolean + */ + Promise<boolean> replaceSurroundingText(DOMString text, optional long offset, optional long length); + + /** + * Delete text around the cursor. + * @param offset The offset from the cursor position where deletion starts. + * @param length The length of text to delete. + * TODO: maybe updateSurroundingText(DOMString beforeText, DOMString afterText); ? + * @return boolean + */ + Promise<boolean> deleteSurroundingText(long offset, long length); + + /** + * Notifies when the text around the cursor is changed, due to either text + * editing or cursor movement. If the cursor has been moved, but the text around has not + * changed, the IME won't get notification. + * + * evt.detail is defined by MozInputContextSurroundingTextChangeEventDetail. + */ + attribute EventHandler onsurroundingtextchange; + + /** + * Send a string/character with its key events. There are two ways of invocating + * the method for backward compability purpose. + * + * (1) The recommended way, allow specifying DOM level 3 properties like |code|. + * @param dictOrKeyCode See MozInputMethodKeyboardEventDict. + * @param charCode disregarded + * @param modifiers disregarded + * @param repeat disregarded + * + * (2) Deprecated, reserved for backward compability. + * @param dictOrKeyCode keyCode of the key to send, should be one of the DOM_VK_ value in KeyboardEvent. + * @param charCode charCode of the character, should be 0 for non-printable keys. + * @param modifiers this paramater is no longer honored. + * @param repeat indicates whether a key would be sent repeatedly. + * + * @return A promise. Resolve to true if succeeds. + * Rejects to a string indicating the error. + * + * Note that, if you want to send a key n times repeatedly, make sure set + * parameter repeat to true and invoke sendKey n times, and invoke keyup + * after the end of the input. + */ + Promise<boolean> sendKey((MozInputMethodRequiredKeyboardEventDict or long) dictOrKeyCode, + optional long charCode, + optional long modifiers, + optional boolean repeat); + + /** + * Send a string/character with keydown, and keypress events. + * keyup should be called afterwards to ensure properly sequence. + * + * @param dict See MozInputMethodKeyboardEventDict. + * + * @return A promise. Resolve to true if succeeds. + * Rejects to a string indicating the error. + */ + Promise<boolean> keydown(MozInputMethodRequiredKeyboardEventDict dict); + + /** + * Send a keyup event. keydown should be called first to ensure properly sequence. + * + * @param dict See MozInputMethodKeyboardEventDict. + * + * @return A promise. Resolve to true if succeeds. + * Rejects to a string indicating the error. + */ + Promise<boolean> keyup(MozInputMethodRequiredKeyboardEventDict dict); + + /** + * Set current composing text. This method will start composition or update + * composition if it has started. The composition will be started right + * before the cursor position and any selected text will be replaced by the + * composing text. When the composition is started, calling this method can + * update the text and move cursor winthin the range of the composing text. + * @param text The new composition text to show. + * @param cursor The new cursor position relative to the start of the + * composition text. The cursor should be positioned within the composition + * text. This means the value should be >= 0 and <= the length of + * composition text. Defaults to the lenght of composition text, i.e., the + * cursor will be positioned after the composition text. + * @param clauses The array of composition clause information. If not set, + * only one clause is supported. + * @param dict The properties of the keyboard event that cause the composition + * to set. keydown or keyup event will be fired if it's necessary. + * For compatibility, we recommend that you should always set this argument + * if it's caused by a key operation. + * + * The composing text, which is shown with underlined style to distinguish + * from the existing text, is used to compose non-ASCII characters from + * keystrokes, e.g. Pinyin or Hiragana. The composing text is the + * intermediate text to help input complex character and is not committed to + * current input field. Therefore if any text operation other than + * composition is performed, the composition will automatically end. Same + * apply when the inputContext is lost during an unfinished composition + * session. + * + * To finish composition and commit text to current input field, an IME + * should call |endComposition|. + */ + Promise<boolean> setComposition(DOMString text, + optional long cursor, + optional sequence<CompositionClauseParameters> clauses, + optional MozInputMethodKeyboardEventDict dict); + + /** + * End composition, clear the composing text and commit given text to + * current input field. The text will be committed before the cursor + * position. + * @param text The text to commited before cursor position. If empty string + * is given, no text will be committed. + * @param dict The properties of the keyboard event that cause the composition + * to end. keydown or keyup event will be fired if it's necessary. + * For compatibility, we recommend that you should always set this argument + * if it's caused by a key operation. + * + * Note that composition always ends automatically with nothing to commit if + * the composition does not explicitly end by calling |endComposition|, but + * is interrupted by |sendKey|, |setSelectionRange|, + * |replaceSurroundingText|, |deleteSurroundingText|, user moving the + * cursor, changing the focus, etc. + */ + Promise<boolean> endComposition(optional DOMString text, + optional MozInputMethodKeyboardEventDict dict); + + /** + * The interface used to receive the native events from hardware keyboard + */ + readonly attribute MozHardwareInput? hardwareinput; +}; + +/* + * This interface will be added into inputcontext and used to receive the + * events from the hardware keyboard. + * Example: + * mozInputMethod.inputcontext.hardwareinput.addEventListener('keyup', this); + * mozInputMethod.inputcontext.hardwareinput.removeEventListener('keyup', this); + */ +[JSImplementation="@mozilla.org/b2g-hardwareinput;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozHardwareInput: EventTarget { +}; + +/** + * Detail of the selectionchange event. + */ +[JSImplementation="@mozilla.org/b2g-imm-selectionchange;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputContextSelectionChangeEventDetail { + /** + * Indicate whether or not the change is due to our own action from, + * for example, sendKey() call. + * + * Note: this property is untrustworthy because it would still be true even + * if script in the page changed the text synchronously upon responding to + * events trigger by the call. + */ + readonly attribute boolean ownAction; + + /** + * The start and stop position of the current selection. + */ + readonly attribute long selectionStart; + readonly attribute long selectionEnd; +}; + +/** + * Detail of the surroundingtextchange event. + */ +[JSImplementation="@mozilla.org/b2g-imm-surroundingtextchange;1", + Pref="dom.mozInputMethod.enabled", + ChromeOnly] +interface MozInputContextSurroundingTextChangeEventDetail { + /** + * Indicate whether or not the change is due to our own action from, + * for example, sendKey() call. + * + * Note: this property is untrustworthy because it would still be true even + * if script in the page changed the text synchronously upon responding to + * events trigger by the call. + */ + readonly attribute boolean ownAction; + + /** + * The text in the current input. + */ + readonly attribute DOMString? text; + + /** + * The text before and after the begining of the selected text. + * + * You should use the text property instead because these properties are + * truncated at 100 characters. + */ + readonly attribute DOMString? textBeforeCursor; + readonly attribute DOMString? textAfterCursor; +}; + +enum CompositionClauseSelectionType { + "raw-input", + "selected-raw-text", + "converted-text", + "selected-converted-text" +}; + +dictionary CompositionClauseParameters { + CompositionClauseSelectionType selectionType = "raw-input"; + long length; +}; + +/** + * Types are HTML tag names of the inputs that is explosed with InputContext, + * *and* the special keyword "contenteditable" for contenteditable element. + */ +enum MozInputMethodInputContextTypes { + "input", "textarea", "contenteditable", + /** + * <select> is managed by the API but it is handled by the System app only, + * so this value is only accessible by System app from inputcontextfocus event. + */ + "select" +}; + +/** + * InputTypes of the input that InputContext is representing. The value + * is inferred from the type attribute of element. + * + * See https://html.spec.whatwg.org/multipage/forms.html#states-of-the-type-attribute + * for types of HTMLInputElement. + * + * They are divided into groups -- an layout/input capable of handling one type + * in the group is considered as capable of handling all of the types in the + * same group. + * The layout/input that could handle type "text" is considered as the fallback + * if none of layout/input installed can handle a specific type. + * + * Groups and fallbacks is enforced in Gaia System app currently. + * + * Noted that the actual virtual keyboard to show, for example in the case of + * Gaia Keyboard app, will also depend on the inputMode of the input element. + */ +enum MozInputMethodInputContextInputTypes { + /** + * Group "text". Be reminded that contenteditable element is assigned with + * an input type of "textarea". + */ + "text", "search", "textarea", + /** + * Group "number" + */ + "number", "tel", + /** + * Group "url" + */ + "url", + /** + * Group "email" + */ + "email", + /** + * Group "password". + * An non-Latin alphabet layout/input should not be able to handle this type. + */ + "password", + /** + * Group "option". These types are handled by System app itself currently, so + * no input app will be set to active for these input types. + * System app access these types from inputcontextfocus event. + * ("select-one" and "select-multiple" are valid HTMLSelectElement#type.) + */ + "datetime", "date", "month", "week", "time", "datetime-local", "color", + "select-one", "select-multiple" + /** + * These types are ignored by the API even though they are valid + * HTMLInputElement#type. + */ + //"checkbox", "radio", "file", "submit", "image", "range", "reset", "button" +}; + +/** + * An input app can host multiple inputs (a.k.a. layouts) and the capability of + * the input is described by the input manifest. + */ +dictionary MozInputMethodInputManifest { + required DOMString launch_path; + required DOMString name; + DOMString? description; + sequence<MozInputMethodInputContextInputTypes> types; +}; + +/** + * A MozInputMethodKeyboardEventDictBase contains the following properties, + * indicating the properties of the keyboard event caused. + * + * This is the base dictionary type for us to create two child types that could + * be used as argument type in two types of methods, as WebIDL parser required. + * + */ +dictionary MozInputMethodKeyboardEventDictBase { + /** + * String/character to output, or a registered name of non-printable key. + * (To be defined in the inheriting dictionary types.) + */ + // DOMString key; + /** + * String/char indicating the virtual hardware key pressed. Optional. + * Must be a value defined in + * http://www.w3.org/TR/DOM-Level-3-Events-code/#keyboard-chording-virtual + * If your keyboard app emulates physical keyboard layout, this value should + * not be empty string. Otherwise, it should be empty string. + */ + DOMString code = ""; + /** + * keyCode of the keyboard event. Optional. + * To be disregarded if |key| is an alphanumeric character. + * If the key causes inputting a character and if your keyboard app emulates + * a physical keyboard layout, this value should be same as the value used + * by Firefox for desktop. If the key causes inputting an ASCII character + * but if your keyboard app doesn't emulate any physical keyboard layouts, + * the value should be proper value for the key value. + */ + long? keyCode; + /** + * Indicates whether a key would be sent repeatedly. Optional. + */ + boolean repeat = false; + /** + * Optional. True if |key| property is explicitly referring to a printable key. + * When this is set, key will be printable even if the |key| value matches any + * of the registered name of non-printable keys. + */ + boolean printable = false; +}; + +/** + * For methods like setComposition() and endComposition(), the optional + * dictionary type argument is really optional when all of it's property + * are optional. + * This dictionary type is used to denote that argument. + */ +dictionary MozInputMethodKeyboardEventDict : MozInputMethodKeyboardEventDictBase { + DOMString? key; +}; + +/** + * For methods like keydown() and keyup(), the dictionary type argument is + * considered required only if at least one of it's property is required. + * This dictionary type is used to denote that argument. + */ +dictionary MozInputMethodRequiredKeyboardEventDict : MozInputMethodKeyboardEventDictBase { + required DOMString key; +}; |