Struct xpcom::interfaces::nsITextInputProcessor

#[repr(C)]
pub struct nsITextInputProcessor { /* fields omitted */ }

interface nsITextInputProcessor : nsISupports

/**
 * 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);
 */

Methods

impl nsITextInputProcessor

pub fn coerce<T: nsITextInputProcessorCoerce>(&self) -> &T

Cast this nsITextInputProcessor to one of its base interfaces.

impl nsITextInputProcessor

pub const ATTR_RAW_CLAUSE: i64

ATTR_RAW_CLAUSE: i64 = 2

pub const ATTR_SELECTED_RAW_CLAUSE: i64

ATTR_SELECTED_RAW_CLAUSE: i64 = 3

pub const ATTR_CONVERTED_CLAUSE: i64

ATTR_CONVERTED_CLAUSE: i64 = 4

pub const ATTR_SELECTED_CLAUSE: i64

ATTR_SELECTED_CLAUSE: i64 = 5

pub const KEY_DEFAULT_PREVENTED: i64

KEY_DEFAULT_PREVENTED: i64 = 1

pub const KEY_NON_PRINTABLE_KEY: i64

KEY_NON_PRINTABLE_KEY: i64 = 2

pub const KEY_FORCE_PRINTABLE_KEY: i64

KEY_FORCE_PRINTABLE_KEY: i64 = 4

pub const KEY_KEEP_KEY_LOCATION_STANDARD: i64

KEY_KEEP_KEY_LOCATION_STANDARD: i64 = 8

pub const KEY_KEEP_KEYCODE_ZERO: i64

KEY_KEEP_KEYCODE_ZERO: i64 = 16

pub const KEY_DONT_DISPATCH_MODIFIER_KEY_EVENT: i64

KEY_DONT_DISPATCH_MODIFIER_KEY_EVENT: i64 = 32

pub const KEYEVENT_NOT_CONSUMED: i64

KEYEVENT_NOT_CONSUMED: i64 = 0

pub const KEYDOWN_IS_CONSUMED: i64

KEYDOWN_IS_CONSUMED: i64 = 1

pub const KEYPRESS_IS_CONSUMED: i64

KEYPRESS_IS_CONSUMED: i64 = 2

pub unsafe fn GetHasComposition(&self, aHasComposition: *mut bool) -> nsresult

/**
   * Returns true if this instance was dispatched compositionstart but hasn't
   * dispatched compositionend yet.
   */

readonly attribute boolean hasComposition;

pub unsafe fn BeginInputTransaction(
    &self,
    aWindow: *const mozIDOMWindow,
    aCallback: *const nsITextInputProcessorCallback,
    _retval: *mut bool
) -> nsresult

/**
   * 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);

pub unsafe fn SetPendingCompositionString(
    &self,
    aString: &nsAString
) -> nsresult

/**
   * 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 DOMString aString);

pub unsafe fn AppendClauseToPendingComposition(
    &self,
    aLength: uint32_t,
    aAttribute: uint32_t
) -> nsresult

/**
   * 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);

pub unsafe fn SetCaretInPendingComposition(&self, aOffset: uint32_t) -> nsresult

/**
   * 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);

pub unsafe fn GetModifierState(
    &self,
    aModifierKey: &nsAString,
    _retval: *mut bool
) -> nsresult

/**
   * 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 DOMString aModifierKey);

pub unsafe fn ShareModifierStateOf(
    &self,
    aOther: *const nsITextInputProcessor
) -> nsresult

/**
   * 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);

Methods from Deref<Target = nsISupports>

pub fn coerce<T: nsISupportsCoerce>(&self) -> &T

Cast this nsISupports to one of its base interfaces.

pub unsafe fn QueryInterface(
    &self,
    uuid: &nsIID,
    result: *mut *mut c_void
) -> nsresult

void QueryInterface (in nsIIDRef uuid, [iid_is (uuid), retval] out nsQIResult result);

pub unsafe fn AddRef(&self) -> nsrefcnt

[noscript,notxpcom] nsrefcnt AddRef ();

pub unsafe fn Release(&self) -> nsrefcnt

[noscript,notxpcom] nsrefcnt Release ();

Trait Implementations

impl XpCom for nsITextInputProcessor

const IID: nsIID

IID: nsIID = nsID(1202594177, 11928, 19800, [132, 162, 184, 219, 103, 100, 206, 154])

fn query_interface<T: XpCom>(&self) -> Option<RefPtr<T>>

Perform a QueryInterface call on this object, attempting to dynamically cast it to the requested interface type. Returns Some(RefPtr) if the cast succeeded, and None otherwise.

impl RefCounted for nsITextInputProcessor

unsafe fn addref(&self)

Increment the reference count.

unsafe fn release(&self)

Decrement the reference count, potentially freeing backing memory.

impl Deref for nsITextInputProcessor

type Target = nsISupports

The resulting type after dereferencing.

fn deref(&self) -> &nsISupports

Dereferences the value.