Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 674 insertions, 0 deletions

diff --git a/dom/interfaces/base/nsITextInputProcessor.idl b/dom/interfaces/base/nsITextInputProcessor.idl
new file mode 100644
index 0000000000..6d702af385
--- /dev/null
+++ b/dom/interfaces/base/nsITextInputProcessor.idl
@@ -0,0 +1,674 @@
+/* -*- 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/. */
+
+#include "nsISupports.idl"
+
+interface mozIDOMWindow;
+interface nsITextInputProcessorCallback;
+
+webidl Event;
+
+/**
+ * An nsITextInputProcessor instance is associated with a top level widget which
+ * handles native IME.  It's associated by calling beginInputTransaction() or
+ * beginInputTransactionForTests().  While an instance has composition, nobody
+ * can steal the rights to make composition on the top level widget.  In other
+ * words, if another instance is composing on a top level widget, either
+ * beginInputTransaction() or beginInputTransactionForTests() returns false
+ * (i.e., not throws an exception).
+ *
+ * NOTE: See nsITextInputProcessorCallback.idl for examples of |callback| in
+ *       following examples,
+ *
+ * Example #1 JS-IME can start composition like this:
+ *
+ *   var TIP = Components.classes["@mozilla.org/text-input-processor;1"].
+ *               createInstance(Components.interfaces.nsITextInputProcessor);
+ *   if (!TIP.beginInputTransaction(window, callback)) {
+ *     return; // You failed to get the rights to make composition
+ *   }
+ *   // Create a keyboard event if the following compositionc change is caused
+ *   // by a key event.
+ *   var keyEvent =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // Set new composition string first
+ *   TIP.setPendingCompositionString("some-words-are-inputted");
+ *   // Set clause information.
+ *   TIP.appendClauseToPendingComposition(23, TIP.ATTR_RAW_CLAUSE);
+ *   // Set caret position, this is optional.
+ *   TIP.setCaretInPendingComposition(23);
+ *   // Flush the pending composition
+ *   if (!TIP.flushPendingComposition(keyEvent)) {
+ *     // If it returns false, it fails to start composition.
+ *     return;
+ *   }
+ *
+ * Example #2 JS-IME can separate composition string to two or more clauses:
+ *
+ *   // Create a keyboard event if the following compositionc change is caused
+ *   // by a key event.
+ *   var keyEvent =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // First, set composition string again
+ *   TIP.setPendingCompositionString("some-words-are-inputted");
+ *   // Then, if "are" is selected to convert, there are 3 clauses:
+ *   TIP.appendClauseToPendingComposition(11, TIP.ATTR_CONVERTED_CLAUSE);
+ *   TIP.appendClauseToPendingComposition(3,  TIP.ATTR_SELECTED_CLAUSE);
+ *   TIP.appendClauseToPendingComposition(9,  TIP.ATTR_CONVERTED_CLAUSE);
+ *   // Show caret at the beginning of the selected clause
+ *   TIP.setCaretInPendingComposition(11);
+ *   // Flush the pending composition.  Note that if there is a composition,
+ *   // flushPendingComposition() won't return false.
+ *   TIP.flushPendingComposition(keyEvent);
+ *
+ * Example #3 JS-IME can commit composition with specific string with this:
+ *
+ *   // Create a keyboard event if the following compositionc change is caused
+ *   // by a key event.
+ *   var keyEvent1 =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // First, there is a composition.
+ *   TIP.setPendingCompositionString("some-words-directly-inputted");
+ *   TIP.appendClauseToPendingComposition(28, TIP.ATTR_RAW_CLAUSE);
+ *   TIP.flushPendingComposition(keyEvent1);
+ *   // Create a keyboard event if the following commit composition is caused
+ *   // by a key event.
+ *   var keyEvent2 =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // This is useful when user selects a commit string from candidate list UI
+ *   // which is provided by JS-IME.
+ *   TIP.commitCompositionWith("selected-words-from-candidate-list", keyEvent2);
+ *
+ * Example #4 JS-IME can commit composition with the last composition string
+ *            without specifying commit string:
+ *
+ *   // Create a keyboard event if the following compositionc change is caused
+ *   // by a key event.
+ *   var keyEvent1 =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // First, there is a composition.
+ *   TIP.setPendingCompositionString("some-words-will-be-commited");
+ *   TIP.appendClauseToPendingComposition(27, TIP.ATTR_RAW_CLAUSE);
+ *   TIP.flushPendingComposition(keyEvent1);
+ *   // Create a keyboard event if the following commit is caused by a key
+ *   // event.
+ *   var keyEvent2 =
+ *     new KeyboardEvent("", { key: "Enter", code: "Enter",
+                               keyCode: KeyboardEvent.DOM_VK_RETURN });
+ *   // This is useful when user just type Enter key.
+ *   TIP.commitComposition(keyEvent2);
+ *
+ * Example #5 JS-IME can cancel composition with this:
+ *
+ *   // Create a keyboard event if the following composition change is caused
+ *   // by a key event.
+ *   var keyEvent1 =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // First, there is a composition.
+ *   TIP.setPendingCompositionString("some-words-will-be-canceled");
+ *   TIP.appendClauseToPendingComposition(27, TIP.ATTR_RAW_CLAUSE);
+ *   TIP.flushPendingComposition(keyEvent1);
+ *   // Create a keyboard event if the following canceling composition is
+ *   // caused by a key event.
+ *   var keyEvent2 =
+ *     new KeyboardEvent("", { key: "Escape", code: "Escape",
+                               keyCode: KeyboardEvent.DOM_VK_ESCAPE });
+ *   // This is useful when user doesn't want to commit the composition.
+ *   // FYI: This is same as TIP.commitCompositionWith("") for now.
+ *   TIP.cancelComposition(keyEvent2);
+ *
+ * Example #6 JS-IME can insert text only with commitCompositionWith():
+ *
+ *   // Create a keyboard event if the following inserting text is caused by a
+ *   // key event.
+ *   var keyEvent1 =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   if (!TIP.beginInputTransaction(window, callback)) {
+ *     return; // You failed to get the rights to make composition
+ *   }
+ *   TIP.commitCompositionWith("Some words", keyEvent1);
+ *
+ * Example #7 JS-IME can start composition explicitly:
+ *
+ *   if (!TIP.beginInputTransaction(window, callback)) {
+ *     return; // You failed to get the rights to make composition
+ *   }
+ *   // Create a keyboard event if the following starting composition is caused
+ *   // by a key event.
+ *   var keyEvent1 =
+ *     new KeyboardEvent("", { key: "foo", code: "bar", keyCode: buzz });
+ *   // If JS-IME don't want to show composing string in the focused editor,
+ *   // JS-IME can dispatch only compositionstart event with this.
+ *   if (!TIP.startComposition(keyEvent1)) {
+ *     // Failed to start composition.
+ *     return;
+ *   }
+ *   // And when user selects a result from UI of JS-IME, commit with it.
+ *   // Then, the key event should be null.
+ *   TIP.commitCompositionWith("selected-words");
+ *
+ * Example #8 JS-IME or JS-Keyboard should dispatch key events even during
+ *            composition (non-printable key case):
+ *
+ *   if (!TIP.beginInputTransaction(window, callback)) {
+ *     return; // You failed to get the rights to dispatch key events
+ *   }
+ *
+ *   // You don't need to specify .keyCode value if it's non-printable key
+ *   // because it can be computed from .key value.
+ *   // If you specify non-zero value to .keyCode, it'll be used.
+ *   var keyEvent = new KeyboardEvent("", { code: "Enter", key: "Enter" });
+ *   if (TIP.keydown(keyEvent)) {
+ *     // Handle its default action
+ *   }
+ *
+ *   // Even if keydown event was consumed, keyup event should be dispatched.
+ *   if (TIP.keyup(keyEvent)) {
+ *     // Handle its default action
+ *   }
+ *
+ * Example #9 JS-IME or JS-Keyboard should dispatch key events even during
+ *            composition (printable key case):
+ *
+ *   if (!TIP.beginInputTransaction(window, callback)) {
+ *     return; // You failed to get the rights to dispatch key events
+ *   }
+ *
+ *   // You need to specify .keyCode value if it's printable key.
+ *   // The rules of .keyCode value is documented in MDN:
+ *   //   https://developer.mozilla.org/docs/Web/API/KeyboardEvent.keyCode
+ *   //
+ *   //   #1 If the key location is DOM_KEY_LOCATION_NUMPAD and NumLock is
+ *   //      active, you should specify DOM_VK_NUMPAD[0-9], DOM_VK_MULTIPLY,
+ *   //      DOM_VK_ADD, DOM_VK_SEPARATOR, DOM_VK_SUBTRACT, DOM_VK_DECIMAL or
+ *   //      DOM_VK_DIVIDE.
+ *   //   #2 If the key is Spacebar, use DOM_VK_SPACE.
+ *   //
+ *   //   Following rules are printable keys in DOM_KEY_LOCATION_STANDARD.
+ *   //   .keyCode value for a key shouldn't be changed by modifier states:
+ *   //     #1 If the key can input [0-9] with any modifier state (except
+ *   //        NumLock state), the value should be DOM_VK_[0-9].
+ *   //     #2 Otherwise, and if the key inputs an ASCII alphabet with no
+ *   //        active modifiers, use DOM_VK_[A-Z].
+ *   //     #3 Otherwise, and if the key inputs an ASCII alphabet with no
+ *   //        active modifiers except Shift key state, use DOM_VK_[A-Z] for
+ *   //        the shifted character.  E.g., if a key causes non-alphabet
+ *   //        character such as "@" or a Unicode character without Shift key
+ *   //        but "a" is inputted when Shift key is pressed, the proper
+ *   //        keyCode is DOM_VK_A.
+ *   //     #4 Otherwise, and if the key inputs another ASCII character with
+ *   //        no modifier states, use a proper value for the character.  E.g.,
+ *   //        if the key inputs "*" without Shift key state, it should be
+ *   //        DOM_VK_ASTERISK.
+ *   //     #5 Otherwise, and if the key inputs another ASCII character with
+ *   //        Shift key state, use a proper value for the character.  E.g.,
+ *   //        if a key causes a Unicode character without Shift key but "&"
+ *   //        is inputted when Shift key is pressed, the proper keyCode is
+ *   //        DOM_VK_AMPERSAND.
+ *   //     See above document for the other cases.
+ *   //
+ *   // NOTE: If the software keyboard is 10-key like simple phone,
+ *   //       We don't have common rules to decide its .keyCode value.
+ *   //       Above rules should be used when the JS-Keyboard emulates PC
+ *   //       keyboard.
+ *   // .key value should be inputting character by the key with current
+ *   // modifier state.
+ *   // .code value should be empty string if the JS-Keyboard isn't emulating
+ *   // physical keyboard.  Otherwise, use same value with physical keyboard's
+ *   // same key.
+ *   var keyEvent = new KeyboardEvent("", { code: "KeyA", key: "a",
+ *                                          keyCode: KeyboardEvent.DOM_VK_A });
+ *   if (TIP.keydown(keyEvent)) {
+ *     // Handle its default action
+ *   }
+ *
+ *   // Even if keydown event was consumed, keyup event should be dispatched.
+ *   if (TIP.keyup(keyEvent)) {
+ *     // Handle its default action
+ *   }
+ *
+ * Example #10 JS-Keyboard doesn't need to initialize modifier states at
+ *             calling either keydown() or keyup().
+ *
+ *   // Neither beginInputTransaction() nor beginInputTransactionForTests()
+ *   // resets modifier state.
+ *   if (!TIP.beginInputTransaction(window, callback)) {
+ *     return; // You failed to get the rights to dispatch key events
+ *   }
+ *
+ *   var leftShift = new KeyboardEvent("", { code: "ShiftLeft", key: "Shift" });
+ *
+ *   // This causes following key events will be shifted automatically.
+ *   TIP.keydown(leftShift);
+ *
+ *   var rightShift =
+ *     new KeyboardEvent("", { code: "ShiftRight", key: "Shift" });
+ *
+ *   TIP.keydown(rightShift);
+ *
+ *   // keyup of one of shift key doesn't cause inactivating "Shift" state.
+ *   TIP.keyup(rightShift);
+ *
+ *   // This causes inactivating "Shift" state completely.
+ *   TIP.keyup(leftShift);
+ */
+
+[scriptable, builtinclass, uuid(47ae2181-2e98-4d58-84a2-b8db6764ce9a)]
+interface nsITextInputProcessor : nsISupports
+{
+  /**
+   * Returns true if this instance was dispatched compositionstart but hasn't
+   * dispatched compositionend yet.
+   */
+  readonly attribute boolean hasComposition;
+
+  /**
+   * When you create an instance, you must call beginInputTransaction() first
+   * except when you created the instance for automated tests.
+   *
+   * @param aWindow         A DOM window.  The instance will look for a top
+   *                        level widget from this.
+   * @param aCallback       Callback interface which handles requests to
+   *                        IME and notifications to IME.  This must not be
+   *                        null.
+   * @return                If somebody uses internal text input service for a
+   *                        composition, this returns false.  Otherwise, returns
+   *                        true.  I.e., only your TIP can create composition
+   *                        when this returns true.  If this returns false,
+   *                        your TIP should wait next chance.
+   */
+  boolean beginInputTransaction(in mozIDOMWindow aWindow,
+                                in nsITextInputProcessorCallback aCallback);
+
+  /**
+   * When you create an instance for automated test, you must call
+   * beginInputTransaction(), first.  See beginInputTransaction() for more
+   * detail of this.
+   * Note that aCallback can be null.  If it's null, nsITextInputProcessor
+   * implementation will handle them automatically.
+   */
+  [optional_argc] boolean
+    beginInputTransactionForTests(
+      in mozIDOMWindow aWindow,
+      [optional] in nsITextInputProcessorCallback aCallback);
+
+  /**
+   * startComposition() dispatches compositionstart event explicitly.
+   * IME does NOT need to call this typically since compositionstart event
+   * is automatically dispatched by sendPendingComposition() if
+   * compositionstart event hasn't been dispatched yet.  If this is called
+   * when compositionstart has already been dispatched, this throws an
+   * exception.
+   *
+   * @param aKeyboardEvent  Key event which causes starting composition.
+   *                        If its type value is "keydown", this method
+   *                        dispatches only keydown event first.  Otherwise,
+   *                        dispatches keydown first and keyup at last.
+   *                        key value and keyCode values of keydown event
+   *                        are set to "Process" and DOM_VK_PROCESSKEY
+   *                        automatically.  You can prevent this behavior
+   *                        with KEY_DONT_MARK_KEYDOWN_AS_PROCESSED.
+   * @param aKeyFlags       See KEY_* constants.
+   * @return                Returns true if composition starts normally.
+   *                        Otherwise, returns false because it might be
+   *                        canceled by the web application.
+   */
+  [can_run_script, optional_argc]
+    boolean startComposition([optional] in Event aKeyboardEvent,
+                             [optional] in unsigned long aKeyFlags);
+
+  /**
+   * Set new composition string.  Pending composition will be flushed by
+   * a call of flushPendingComposition().  However, if the new composition
+   * string isn't empty, you need to call appendClauseToPendingComposition() to
+   * fill all characters of aString with one or more clauses before flushing.
+   * Note that if you need to commit or cancel composition, use
+   * commitComposition(), commitCompositionWith() or cancelComposition().
+   */
+  void setPendingCompositionString(in AString aString);
+
+  // ATTR_RAW_CLAUSE means that the clause hasn't been selected nor converted
+  // yet.
+  const unsigned long ATTR_RAW_CLAUSE           = 0x02;
+  // ATTR_SELECTED_RAW_CLAUSE means that the clause hasn't been converted yet
+  // but is selected for converting to the other string.
+  const unsigned long ATTR_SELECTED_RAW_CLAUSE  = 0x03;
+  // ATTR_CONVERTED_CLAUSE means that the clause has already been converted but
+  // is not selected.  This does NOT mean that this clause isn't modifiable.
+  const unsigned long ATTR_CONVERTED_CLAUSE     = 0x04;
+  // ATTR_SELECTED_CLAUSE means that the clause has already been converted and
+  // is selected.  In other words, the clause is being converted.
+  const unsigned long ATTR_SELECTED_CLAUSE      = 0x05;
+
+  /**
+   * Append a clause to the pending composition.
+   *
+   * If you need to fill the pending composition string with a clause, you
+   * should call this once.  For example:
+   *   appendClauseToPendingComposition(compositionString.length,
+   *                                    ATTR_RAW_CLAUSE);
+   * is enough.  If you need to separate the pending composition string to
+   * multiple clauses, you need to call this multiple times. For example,
+   * if your pending composition string has three clauses and the second clause
+   * is being converted:
+   *  appendClauseToPendingComposition(firstClauseLength,
+   *                                   ATTR_CONVERTED_CLAUSE);
+   *  appendClauseToPendingComposition(secondClauseLength,
+   *                                   ATTR_SELECTED_CLAUSE);
+   *  appendClauseToPendingComposition(thirdClauseLength,
+   *                                   ATTR_CONVERTED_CLAUSE);
+   * Note that if sum of aLength mismatches length of the pending composition
+   * string, flushPendingComposition() will throw an exception.  I.e.,
+   * |firstClauseLength + secondClauseLength + thirdClauseLength| must be
+   * same as the length of pending composition string.
+   *
+   * TODO: Should be able to specify custom clause style.
+   *
+   * @param aLength         Length of the clause.
+   * @param aAttribute      One of ATTR_* constants.
+   */
+  void appendClauseToPendingComposition(in unsigned long aLength,
+                                        in unsigned long aAttribute);
+
+  /**
+   * Set caret offset in the pending composition string.  If you don't need to
+   * show a caret, you don't need to call this.
+   *
+   * @param aOffset         Caret offset in the pending composition string.
+   *                        This must be between 0 and length of the pending
+   *                        composition string.
+   */
+  void setCaretInPendingComposition(in unsigned long aOffset);
+
+  /**
+   * flushPendingComposition() must be called after
+   * setPendingCompositionString() and appendClauseToPendingComposition()
+   * (setCaretInPendingComposition() is optional) are called.
+   *
+   * Note that compositionstart will be automatically dispatched if this is
+   * called when there is no composition.
+   *
+   * Note that if sum of lengths of appended clauses are not same as composition
+   * string or caret offset is larger than the composition string length, this
+   * throws an exception.
+   *
+   * @param aKeyboardEvent  Key event which causes the composition string.
+   *                        If its type value is "keydown", this method
+   *                        dispatches only keydown event first.  Otherwise,
+   *                        dispatches keydown first and keyup at last.
+   *                        key value and keyCode values of keydown event
+   *                        are set to "Process" and DOM_VK_PROCESSKEY
+   *                        automatically.  You can prevent this behavior
+   *                        with KEY_DONT_MARK_KEYDOWN_AS_PROCESSED.
+   * @param aKeyFlags       See KEY_* constants.
+   * @return                Returns true if there is a composition already or
+   *                        starting composition automatically.
+   *                        Otherwise, i.e., if it cannot start composition
+   *                        automatically, e.g., canceled by web apps, returns
+   *                        false.
+   */
+  [can_run_script, optional_argc]
+    boolean flushPendingComposition(
+      [optional] in Event aKeyboardEvent,
+      [optional] in unsigned long aKeyFlags);
+
+  /**
+   * commitComposition() will commit composition with the last composition
+   * string.  If there is no composition, this will throw an exception.
+   *
+   * @param aKeyboardEvent  Key event which causes the commit composition.
+   *                        If its type value is "keydown", this method
+   *                        dispatches only keydown event first.  Otherwise,
+   *                        dispatches keydown first and keyup at last.
+   *                        key value and keyCode values of keydown event
+   *                        are set to "Process" and DOM_VK_PROCESSKEY
+   *                        automatically.  You can prevent this behavior
+   *                        with KEY_DONT_MARK_KEYDOWN_AS_PROCESSED.
+   * @param aKeyFlags       See KEY_* constants.
+   */
+  [can_run_script, optional_argc]
+    void commitComposition([optional] in Event aKeyboardEvent,
+                           [optional] in unsigned long aKeyFlags);
+
+  /**
+   * commitCompositionWith() will commit composition with the specific string.
+   * If there is no composition, this will start composition and commit it
+   * with the specified string.
+   *
+   * @param aCommitString   The string to be committed.
+   * @param aKeyboardEvent  Key event which causes the commit composition.
+   *                        If its type value is "keydown", this method
+   *                        dispatches only keydown event first.  Otherwise,
+   *                        dispatches keydown first and keyup at last.
+   *                        key value and keyCode values of keydown event
+   *                        are set to "Process" and DOM_VK_PROCESSKEY
+   *                        automatically.  You can prevent this behavior
+   *                        with KEY_DONT_MARK_KEYDOWN_AS_PROCESSED.
+   * @param aKeyFlags       See KEY_* constants.
+   * @return                Returns true if there is a composition already or
+   *                        starting composition automatically.
+   *                        Otherwise, i.e., if it cannot start composition
+   *                        automatically, e.g., canceled by web apps, returns
+   *                        false.
+   */
+  [can_run_script, optional_argc]
+    boolean commitCompositionWith(in AString aCommitString,
+                                  [optional] in Event aKeyboardEvent,
+                                  [optional] in unsigned long aKeyFlags);
+
+  /**
+   * cancelComposition() will cancel composition.  This is for now the same as
+   * calling commitComposition("").  However, in the future, this might work
+   * better.  If your IME needs to cancel composition, use this instead of
+   * commitComposition().
+   *
+   * Note that if you tries to cancel composition when there is no composition,
+   * this throws an exception.
+   *
+   * @param aKeyboardEvent  Key event which causes the canceling composition.
+   *                        If its type value is "keydown", this method
+   *                        dispatches only keydown event first.  Otherwise,
+   *                        dispatches keydown first and keyup at last.
+   *                        key value and keyCode values of keydown event
+   *                        are set to "Process" and DOM_VK_PROCESSKEY
+   *                        automatically.  You can prevent this behavior
+   *                        with KEY_DONT_MARK_KEYDOWN_AS_PROCESSED.
+   * @param aKeyFlags       See KEY_* constants.
+   */
+  [can_run_script, optional_argc]
+    void cancelComposition([optional] in Event aKeyboardEvent,
+                           [optional] in unsigned long aKeyFlags);
+
+  // Specifying KEY_DEFAULT_PREVENTED can dispatch key events whose
+  // defaultPrevented are true.  Note that if this is specified, keypress event
+  // won't be fired.
+  const unsigned long KEY_DEFAULT_PREVENTED                        = 0x00000001;
+  // If KEY_NON_PRINTABLE_KEY is specified and the .key value isn't valid
+  // key name, the methods will throws an exception.  In other words, this
+  // flag prevents to dispatch key events with wrong key values and to cause
+  // such key events input the key values as text.
+  const unsigned long KEY_NON_PRINTABLE_KEY                        = 0x00000002;
+  // If KEY_FORCE_PRINTABLE_KEY is specified and even if the .key value is a
+  // registered key name, it's treated as inputting text value.
+  const unsigned long KEY_FORCE_PRINTABLE_KEY                      = 0x00000004;
+  // If KEY_KEEP_KEY_LOCATION_STANDARD is specified when its .location is not
+  // initialized or initialized with 0, the value isn't computed with .code
+  // value.  Note that if .location is initialized with non-zero value,
+  // this flag causes throwing an exception.
+  // NOTE: This is not recommended to use except for tests.
+  const unsigned long KEY_KEEP_KEY_LOCATION_STANDARD               = 0x00000008;
+  // If KEY_KEEP_KEYCODE_ZERO is specified when its .keyCode is not initialized
+  // or initialized with 0, the value isn't computed with .key value when it
+  // represents non-printable key.  Note that if .keyCode is initialized with
+  // non-zero value, this flag causes throwing an exception.
+  const unsigned long KEY_KEEP_KEYCODE_ZERO                        = 0x00000010;
+  // If KEY_DONT_DISPATCH_MODIFIER_KEY_EVENT is specified when the key event is
+  // a modifier key's, keydown() and keyup() only modifies its modifier state
+  // without dispatching key events.  This is useful for testing odd behavior
+  // or emulating legacy API behavior.
+  const unsigned long KEY_DONT_DISPATCH_MODIFIER_KEY_EVENT         = 0x00000020;
+  // If KEY_DONT_MARK_KEYDOWN_AS_PROCESSED is specified, key value and keyCode
+  // value of keydown event are not changed to "Process" and DOM_VK_PROCESSKEY.
+  const unsigned long KEY_DONT_MARK_KEYDOWN_AS_PROCESSED           = 0x00000040;
+  // If KEY_MARK_KEYUP_AS_PROCESSED is specified, key value and keyCode value
+  // of keyup event are changed to "Process" and DOM_VK_PROCESSKEY.
+  const unsigned long KEY_MARK_KEYUP_AS_PROCESSED                  = 0x00000080;
+
+  // These values can be used to do bitwise operation with the return value of
+  // the keydown() method.
+  const unsigned long KEYEVENT_NOT_CONSUMED                        = 0x00000000;
+  const unsigned long KEYDOWN_IS_CONSUMED                          = 0x00000001;
+  const unsigned long KEYPRESS_IS_CONSUMED                         = 0x00000002;
+
+  /**
+   * keydown() may dispatch a keydown event and some keypress events if
+   * preceding keydown event isn't consumed and they are necessary.
+   * Note that even if this is called during composition, key events may not
+   * be dispatched.  In this case, this returns false.
+   *
+   * You should initialize at least .key value and .code value of the event.
+   * Additionally, if you try to emulate a printable key, .keyCode value should
+   * be specified if there is proper key value.  See the comment of above
+   * example how to decide .keyCode value of a printable key.  On the other
+   * hand, .keyCode value is automatically computed when you try to emulate
+   * non-printable key.  However, if you try to emulate physical keyboard of
+   * desktop platform, you need to specify proper value explicitly because
+   * the mapping table of this API isn't enough to emulate the behavior of
+   * Gecko for desktop platforms.
+   *
+   * NOTE: Even if this has composition, JS-Keyboard should call keydown() and
+   *       keyup().  Although, with the default preferences and normal
+   *       conditions, DOM key events won't be fired during composition.
+   *       However, they MAY be dispatched for some reasons, e.g., the web
+   *       content listens only key events, or if the standard DOM event spec
+   *       will be changed in the future.
+   *
+   * @param aKeyboardEvent  Must be a keyboard event which should be dispatched
+   *                        as a keydown event and keypress events.
+   *                        #1 Note that you don't need to set charCode value
+   *                        because it's computed from its key value.
+   *                        #2 If code value is set properly and location value
+   *                        isn't specified (i.e., 0), the location value will
+   *                        be guessed from the code value.
+   *                        #3 Non-defined code names are not allowed. If your
+   *                        key isn't registered, file a bug. If your key isn't
+   *                        defined by any standards, use "" (empty string).
+   *                        #4 .keyCode is guessed from .key value if the key
+   *                        name is registered and .keyCode isn't initialized.
+   *                        #5 modifier key states, e.g., .shiftKey, are
+   *                        ignored.  Instead, modifier states are managed by
+   *                        each instance and set automatically.
+   * @param aKeyFlags       Special flags.  The values can be some of KEY_*
+   *                        constants.
+   * @return                KEYEVENT_NOT_CONSUMED, if the keydown event nor
+   *                        the following keypress event(s) are consumed.
+   *                        KEYDOWN_IS_CONSUMED, if the keydown event is
+   *                        consumed. No keypress event will be dispatched in
+   *                        this case.
+   *                        KEYPRESS_IS_CONSUMED, if the keypress event(s) is
+   *                        consumed when dispatched.
+   *                        Note that keypress event is always consumed by
+   *                        native code for the printable keys (indicating the
+   *                        default action has been taken).
+   */
+  [can_run_script, optional_argc]
+    unsigned long keydown(in Event aKeyboardEvent,
+                          [optional] in unsigned long aKeyFlags);
+
+  /**
+   * Similar to keydown(), but this dispatches only a keyup event.
+   */
+  [optional_argc]
+    boolean keyup(in Event aKeyboardEvent,
+                  [optional] in unsigned long aKeyFlags);
+
+  /**
+   * getModifierState() returns modifier state managed by this instance.
+   *
+   * @param aModifier       One of modifier key names.  This doesn't support
+   *                        virtual modifiers like "Accel".
+   * @return                true if the modifier key is active.  Otherwise,
+   *                        false.
+   */
+  boolean getModifierState(in AString aModifierKey);
+
+  /**
+   * shareModifierStateOf() makes the instance shares modifier state of
+   * another instance.  When this is called, the instance refers the modifier
+   * state of another instance.  After that, changes to either this and the
+   * other instance's modifier state is synchronized.
+   *
+   * @param aOther          Another instance which will be referred by the
+   *                        instance.  If this is null, the instance restarts
+   *                        to manage modifier state independently.
+   */
+  void shareModifierStateOf(in nsITextInputProcessor aOther);
+
+  /**
+   * Helper method to get usual |.code| value of non-printable keys.
+   *
+   * @param aKeyValue       A predefined key value such as "Enter".
+   *                        If this is not a proper non-printable key value
+   *                        or a proper key value but not in usual keyboard of
+   *                        the platform, this returns empty string.
+   * @param aLocation       The |.location| value.  This is important if
+   *                        the key may be in different location.
+   *                        E.g., Left vs. Right or Standard vs. Numpad.
+   *                        If this is undefined or null, it'll be treated
+   *                        as Standard or Left.
+   * @return                One of a code value of well-known key on usual
+   *                        keyboard on the platform, or empty string.
+   */
+  [optional_argc]
+    AString computeCodeValueOfNonPrintableKey(
+              in AString aKeyValue,
+              [optional] in jsval aLocation);
+
+  /**
+   * Helper method to guess |.code| value of a printable key which is in usual
+   * keyboard of the platform and when active keyboard layout is US-English.
+   * Note that this is not aware of option key mapping on macOS.
+   *
+   * @param aKeyValue          The key value. Must be a character which can
+   *                           be inputted with US-English keyboard layout.
+   * @param aLocation          The location of the key.  This is important
+   *                           to distinguish whether the key is in Standard
+   *                           or Numpad. If this is undefined or null, will
+   *                           be treated as Standard.
+   * @return                   Returns empty string if there is no proper key.
+   */
+  [optional_argc]
+    AString guessCodeValueOfPrintableKeyInUSEnglishKeyboardLayout(
+              in AString aKeyValue,
+              [optional] in jsval aLocation);
+
+  /**
+   * Helper method to guess |.keyCode| value of a printable key which is in
+   * usual keyboard of the platform and when active keyboard layout is
+   * US-English.
+   * Note that this is not aware of option key mapping on macOS.
+   *
+   * @param aKeyValue          The key value.  Must be a character which can
+   *                           be inputted with US-English keyboard layout.
+   * @param aLocation          The location of the key.  This is important
+   *                           to distinguish whether the key is in Standard
+   *                           our Numpad.  If this is undefined or null,
+   *                           will be treated as Standard.
+   * @return                   Returns 0 if there is no proper key to input
+   *                           aKeyValue with US-English keyboard layout.
+   */
+  [optional_argc]
+    unsigned long guessKeyCodeValueOfPrintableKeyInUSEnglishKeyboardLayout(
+                    in AString aKeyValue,
+                    [optional] in jsval aLocation);
+};
+
+%{C++
+#define TEXT_INPUT_PROCESSOR_CID \
+  { 0xcaaab47f, 0x1e31, 0x478e, \
+    { 0x89, 0x19, 0x97, 0x09, 0x04, 0xe9, 0xcb, 0x72 } }
+#define TEXT_INPUT_PROCESSOR_CONTRACTID \
+  "@mozilla.org/text-input-processor;1"
+%}