diff options
Diffstat (limited to 'dom/interfaces/base/nsITextInputProcessorCallback.idl')
| -rw-r--r-- | dom/interfaces/base/nsITextInputProcessorCallback.idl | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/dom/interfaces/base/nsITextInputProcessorCallback.idl b/dom/interfaces/base/nsITextInputProcessorCallback.idl new file mode 100644 index 0000000000..8cee842108 --- /dev/null +++ b/dom/interfaces/base/nsITextInputProcessorCallback.idl @@ -0,0 +1,250 @@ +/* -*- 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); +}; |