/* -*- 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 nsITextInputProcessor; /** * nsITextInputProcessorNotification stores the type of notification to IME and * its detail. See each explanation of attribute for the detail. */ [scriptable, builtinclass, uuid(c0ce1add-82bb-45ab-b99a-42cfba7fd5d7)] interface nsITextInputProcessorNotification : nsISupports { /** * type attribute represents what's notified or requested. Value must be * one of following values: * * "request-to-commit" (required to be handled) * This is requested when Gecko believes that active composition should be * committed. nsITextInputProcessorCallback::onNotify() has to handle this * notification. * * "request-to-cancel" (required to be handled) * This is requested when Gecko believes that active composition should be * canceled. I.e., composition should be committed with empty string. * nsITextInputProcessorCallback::onNotify() has to handle this * notification. * * "notify-end-input-transaction" (optional) * This is notified when the callback is detached from * nsITextInputProcessor. I.e., the TextInputProcessor lost the rights * to input text and needs to call .beginInputTransaction() before next * input. * * "notify-focus" (optional) * This is notified when an editable editor gets focus and Gecko starts * to observe changes in the content. E.g., selection changes. * IME shouldn't change DOM tree, focus nor something when this is notified. * * "notify-blur" (optional) * This is notified when an editable editor loses focus and Gecko stops * observing the changes in the content. * * "notify-text-change" (optional) * This is notified when text in the focused editor is modified. * Some attributes below are available to retrieve the detail. * IME shouldn't change DOM tree, focus nor something when this is notified. * Note that when there is no chance to notify you of some text changes * safely, this represents all changes as a change. * * "notify-selection-change" (optional) * This is notified when selection in the focused editor is changed. * Some attributes below are available to retrieve the detail. * IME shouldn't change DOM tree, focus nor something when this is notified. * Note that when there was no chance to notify you of this safely, this * represents the latest selection change. * * "notify-position-change" (optional) * This is notified when layout is changed in the editor or the window * is moved. * IME shouldn't change DOM tree, focus nor something when this is notified. * Note that when there was no chance to notify you of this safely, this * represents the latest layout change. */ readonly attribute ACString type; /** * This attribute has a vaild value when type is "notify-selection-change". * This is true if selection has a range. Otherwise, i.e., there is no * range such as after calling Selection.removeAllRanges, this is false. */ readonly attribute bool hasRange; /** * Be careful, line breakers in the editor are treated as native line * breakers. I.e., on Windows, a line breaker is "\r\n" (CRLF). On the * others, it is "\n" (LF). If you want TextInputProcessor to treat line * breakers on Windows as XP line breakers (LF), please file a bug with * the reason why you need the behavior. */ /** * This attribute has a valid value when type is "notify-text-change", or * is "notify-selection-change" and hasRange is true. * This is offset of the start of modified text range if type is * "notify-text-change". Or offset of start of selection if type is * "notify-selection-change". */ readonly attribute unsigned long offset; /** * This attribute has a valid value when type is "notify-selection-change" * and hasRange is true. * This is selected text. I.e., the length is selected length and * it's empty if the selection is collapsed. */ readonly attribute AString text; /** * This attribute has a valid value when type is "notify-selection-change". * This is set to true when the selection is collapsed or no range. * Otherwise, false. */ readonly attribute boolean collapsed; /** * This attribute has a valid value when type is "notify-selection-change" * and hasRange is true. * This is selected length. I.e., if this is 0, collapsed is set to true. */ readonly attribute uint32_t length; /** * This attribute has a valid value when type is "notify-selection-change" * and hasRange is true. * When selection is created from latter point to former point, this is * set to true. Otherwise, false. * I.e., if this is true, offset + length is the anchor of selection. */ readonly attribute boolean reversed; /** * This attribute has a valid value when type is "notify-selection-change". * This indicates the start of the selection's writing mode. * The value can be "horizontal-tb", "vertical-rl" or "vertical-lr". */ readonly attribute ACString writingMode; /** * This attribute has a valid value when type is "notify-selection-change". * If the selection change was caused by composition, this is set to true. * Otherwise, false. */ readonly attribute boolean causedByComposition; /** * This attribute has a valid value when type is "notify-selection-change". * If the selection change was caused by selection event, this is set to true. * Otherwise, false. */ readonly attribute boolean causedBySelectionEvent; /** * This attribute has a valid value when type is "notify-selection-change". * If the selection change occurred during composition, this is set to true. * Otherwise, false. */ readonly attribute boolean occurredDuringComposition; /** * This attribute has a valid value when type is "notify-text-change". * This is removed text length by the change(s). If this is empty, new text * was just inserted. Otherwise, the text is replaced with new text. */ readonly attribute unsigned long removedLength; /** * This attribute has a valid value when type is "notify-text-change". * This is added text length by the change(s). If this is empty, old text * was just deleted. Otherwise, the text replaces the old text. */ readonly attribute unsigned long addedLength; /** * This attribute has a valid value when type is "notify-text-change". * If the text change(s) was caused only by composition, this is set to true. * Otherwise, false. I.e., if one of text changes are caused by JS or * modifying without composition, this is set to false. */ readonly attribute boolean causedOnlyByComposition; /** * This attribute has a valid value when type is "notify-text-change". * If at least one text change not caused by composition occurred during * composition, this is set to true. Otherwise, false. * Note that this is set to false when new change is caused by neither * composition nor occurred during composition because it's outdated for * new composition. * In other words, when text changes not caused by composition occurred * during composition and it may cause committing composition, this is * set to true. */ readonly attribute boolean includingChangesDuringComposition; /** * This attribute has a valid value when type is "notify-text-change". * If at least one text change occurred when there was no composition, this * is set to true. Otherwise, false. */ readonly attribute boolean includingChangesWithoutComposition; }; /** * nsITextInputProcessorCallback is a callback interface for JS to implement * IME. IME implemented by JS can implement onNotify() function and must send * it to nsITextInputProcessor at initializing. Then, onNotify() will be * called with nsITextInputProcessorNotification instance. * The reason why onNotify() uses string simply is that if we will support * other notifications such as text changes and selection changes, we need to * notify IME of some other information. Then, only changing * nsITextInputProcessorNotification interface is better for compatibility. */ [scriptable, function, uuid(23d5f242-adb5-46f1-8766-90d1bf0383df)] interface nsITextInputProcessorCallback : nsISupports { /** * When Gecko notifies IME of something or requests something to IME, * this is called. * * @param aTextInputProcessor Reference to the nsITextInputProcessor service * which is the original receiver of the request * or notification. * @param aNotification Stores type of notifications and additional * information. * @return Return true if it succeeded or does nothing. * Otherwise, return false. * * Example #1 The simplest implementation of nsITextInputProcessorCallback is: * * function simpleCallback(aTIP, aNotification) * { * try { * switch (aNotification.type) { * case "request-to-commit": * aTIP.commitComposition(); * break; * case "request-to-cancel": * aTIP.cancelComposition(); * break; * } * } catch (e) { * return false; * } * return true; * } * * var TIP = Components.classes["@mozilla.org/text-input-processor;1"]. * createInstance(Components.interfaces.nsITextInputProcessor); * if (!TIP.init(window, simpleCallback)) { * return; * } */ boolean onNotify(in nsITextInputProcessor aTextInputProcessor, in nsITextInputProcessorNotification aNotification); };