diff -r 000000000000 -r 6474c204b198 dom/webidl/InputMethod.webidl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dom/webidl/InputMethod.webidl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,248 @@ +/* -*- 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/. + */ + +[JSImplementation="@mozilla.org/b2g-inputmethod;1", + NavigatorProperty="mozInputMethod", + Func="Navigator::HasInputMethodSupport"] +interface MozInputMethod : EventTarget { + // Input Method Manager contain a few global methods expose to 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; + + [ChromeOnly] + // Activate or decactive current input method window. + void setActive(boolean isActive); + + // The following are internal methods for Firefox OS system app only. + + // 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. + [Throws] + void setValue(DOMString value); + + // Select the 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. + [Throws] + void setSelectedOption(long index); + + // Select the that does not support multiple + // selection, then the last index specified in indexes will be selected. + [Throws] + void setSelectedOptions(sequence indexes); + + [Throws] + void removeFocus(); +}; + +// Manages the list of IMEs, enables/disables IME and switches to an +// IME. +[JSImplementation="@mozilla.org/b2g-imm;1", + Pref="dom.mozInputMethod.enabled"] +interface MozInputMethodManager { + // Ask the OS to show a list of available IMEs for users to switch from. + // OS should ignore this request if the app is currently not the active one. + void showAll(); + + // Ask the OS to switch away from the current active Keyboard app. + // OS should ignore this request if the app is currently not the active one. + void next(); + + // To know if the OS supports IME switching or not. + // Use case: let the keyboard app knows if it is necessary to show the "IME switching" + // (globe) button. We have a use case that when there is only one IME enabled, we + // should not show the globe icon. + boolean supportsSwitching(); + + // Ask the OS to hide the current active Keyboard app. (was: |removeFocus()|) + // OS should ignore this request if the app is currently not the active one. + // The OS will void the current input context (if it exists). + // This method belong to |mgmt| because we would like to allow Keyboard to access to + // this method w/o a input context. + void hide(); +}; + +// 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"] +interface MozInputContext: EventTarget { + // The tag name of input field, which is enum of "input", "textarea", or "contenteditable" + readonly attribute DOMString? type; + // The type of the input field, which is enum of text, number, password, url, search, email, and so on. + // See http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#states-of-the-type-attribute + readonly attribute DOMString? inputType; + /* + * The inputmode string, representing the input mode. + * 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 getText(optional long offset, optional long length); + // The start and stop position of the selection. + readonly attribute long selectionStart; + readonly attribute long selectionEnd; + + // The text before and after the begining of the selected text. + 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 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. + */ + 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 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 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. + * + * The event handler function is specified as: + * @param beforeString Text before and including cursor position. + * @param afterString Text after and excluing cursor position. + * function(DOMString beforeText, DOMString afterText) { + * ... + * } + */ + attribute EventHandler onsurroundingtextchange; + + /* + * send a character with its key events. + * @param modifiers see http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/base/nsIDOMWindowUtils.idl#206 + * @param repeat indicates whether a key would be sent repeatedly. + * @return true if succeeds. Otherwise false if the input context becomes void. + * Alternative: sendKey(KeyboardEvent event), but we will likely + * waste memory for creating the KeyboardEvent object. + * Note that, if you want to send a key n times repeatedly, make sure set + * parameter repeat to true and invoke sendKey n-1 times, and then set + * repeat to false in the last invoke. + */ + Promise sendKey(long keyCode, long charCode, long modifiers, optional boolean repeat); + + /* + * 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. + * + * 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 setComposition(DOMString text, optional long cursor, + optional sequence clauses); + + /* + * 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. + * + * 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 endComposition(optional DOMString text); +}; + +enum CompositionClauseSelectionType { + "raw-input", + "selected-raw-text", + "converted-text", + "selected-converted-text" +}; + +dictionary CompositionClauseParameters { + DOMString selectionType = "raw-input"; + long length; +};