nsITextInputProcessorCallback.idl (10177B)
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsITextInputProcessor; 9 10 /** 11 * nsITextInputProcessorNotification stores the type of notification to IME and 12 * its detail. See each explanation of attribute for the detail. 13 */ 14 15 [scriptable, builtinclass, uuid(c0ce1add-82bb-45ab-b99a-42cfba7fd5d7)] 16 interface nsITextInputProcessorNotification : nsISupports 17 { 18 /** 19 * type attribute represents what's notified or requested. Value must be 20 * one of following values: 21 * 22 * "request-to-commit" (required to be handled) 23 * This is requested when Gecko believes that active composition should be 24 * committed. nsITextInputProcessorCallback::onNotify() has to handle this 25 * notification. 26 * 27 * "request-to-cancel" (required to be handled) 28 * This is requested when Gecko believes that active composition should be 29 * canceled. I.e., composition should be committed with empty string. 30 * nsITextInputProcessorCallback::onNotify() has to handle this 31 * notification. 32 * 33 * "notify-end-input-transaction" (optional) 34 * This is notified when the callback is detached from 35 * nsITextInputProcessor. I.e., the TextInputProcessor lost the rights 36 * to input text and needs to call .beginInputTransaction() before next 37 * input. 38 * 39 * "notify-focus" (optional) 40 * This is notified when an editable editor gets focus and Gecko starts 41 * to observe changes in the content. E.g., selection changes. 42 * IME shouldn't change DOM tree, focus nor something when this is notified. 43 * 44 * "notify-blur" (optional) 45 * This is notified when an editable editor loses focus and Gecko stops 46 * observing the changes in the content. 47 * 48 * "notify-text-change" (optional) 49 * This is notified when text in the focused editor is modified. 50 * Some attributes below are available to retrieve the detail. 51 * IME shouldn't change DOM tree, focus nor something when this is notified. 52 * Note that when there is no chance to notify you of some text changes 53 * safely, this represents all changes as a change. 54 * 55 * "notify-selection-change" (optional) 56 * This is notified when selection in the focused editor is changed. 57 * Some attributes below are available to retrieve the detail. 58 * IME shouldn't change DOM tree, focus nor something when this is notified. 59 * Note that when there was no chance to notify you of this safely, this 60 * represents the latest selection change. 61 * 62 * "notify-position-change" (optional) 63 * This is notified when layout is changed in the editor or the window 64 * is moved. 65 * IME shouldn't change DOM tree, focus nor something when this is notified. 66 * Note that when there was no chance to notify you of this safely, this 67 * represents the latest layout change. 68 */ 69 readonly attribute ACString type; 70 71 /** 72 * This attribute has a vaild value when type is "notify-selection-change". 73 * This is true if selection has a range. Otherwise, i.e., there is no 74 * range such as after calling Selection.removeAllRanges, this is false. 75 */ 76 readonly attribute boolean hasRange; 77 78 /** 79 * Be careful, line breakers in the editor are treated as native line 80 * breakers. I.e., on Windows, a line breaker is "\r\n" (CRLF). On the 81 * others, it is "\n" (LF). If you want TextInputProcessor to treat line 82 * breakers on Windows as XP line breakers (LF), please file a bug with 83 * the reason why you need the behavior. 84 */ 85 86 /** 87 * This attribute has a valid value when type is "notify-text-change", or 88 * is "notify-selection-change" and hasRange is true. 89 * This is offset of the start of modified text range if type is 90 * "notify-text-change". Or offset of start of selection if type is 91 * "notify-selection-change". 92 */ 93 readonly attribute unsigned long offset; 94 95 /** 96 * This attribute has a valid value when type is "notify-selection-change" 97 * and hasRange is true. 98 * This is selected text. I.e., the length is selected length and 99 * it's empty if the selection is collapsed. 100 */ 101 readonly attribute AString text; 102 103 /** 104 * This attribute has a valid value when type is "notify-selection-change". 105 * This is set to true when the selection is collapsed or no range. 106 * Otherwise, false. 107 */ 108 readonly attribute boolean collapsed; 109 110 /** 111 * This attribute has a valid value when type is "notify-selection-change" 112 * and hasRange is true. 113 * This is selected length. I.e., if this is 0, collapsed is set to true. 114 */ 115 readonly attribute uint32_t length; 116 117 /** 118 * This attribute has a valid value when type is "notify-selection-change" 119 * and hasRange is true. 120 * When selection is created from latter point to former point, this is 121 * set to true. Otherwise, false. 122 * I.e., if this is true, offset + length is the anchor of selection. 123 */ 124 readonly attribute boolean reversed; 125 126 /** 127 * This attribute has a valid value when type is "notify-selection-change". 128 * This indicates the start of the selection's writing mode. 129 * The value can be "horizontal-tb", "vertical-rl" or "vertical-lr". 130 */ 131 readonly attribute ACString writingMode; 132 133 /** 134 * This attribute has a valid value when type is "notify-selection-change". 135 * If the selection change was caused by composition, this is set to true. 136 * Otherwise, false. 137 */ 138 readonly attribute boolean causedByComposition; 139 140 /** 141 * This attribute has a valid value when type is "notify-selection-change". 142 * If the selection change was caused by selection event, this is set to true. 143 * Otherwise, false. 144 */ 145 readonly attribute boolean causedBySelectionEvent; 146 147 /** 148 * This attribute has a valid value when type is "notify-selection-change". 149 * If the selection change occurred during composition, this is set to true. 150 * Otherwise, false. 151 */ 152 readonly attribute boolean occurredDuringComposition; 153 154 /** 155 * This attribute has a valid value when type is "notify-text-change". 156 * This is removed text length by the change(s). If this is empty, new text 157 * was just inserted. Otherwise, the text is replaced with new text. 158 */ 159 readonly attribute unsigned long removedLength; 160 161 /** 162 * This attribute has a valid value when type is "notify-text-change". 163 * This is added text length by the change(s). If this is empty, old text 164 * was just deleted. Otherwise, the text replaces the old text. 165 */ 166 readonly attribute unsigned long addedLength; 167 168 /** 169 * This attribute has a valid value when type is "notify-text-change". 170 * If the text change(s) was caused only by composition, this is set to true. 171 * Otherwise, false. I.e., if one of text changes are caused by JS or 172 * modifying without composition, this is set to false. 173 */ 174 readonly attribute boolean causedOnlyByComposition; 175 176 /** 177 * This attribute has a valid value when type is "notify-text-change". 178 * If at least one text change not caused by composition occurred during 179 * composition, this is set to true. Otherwise, false. 180 * Note that this is set to false when new change is caused by neither 181 * composition nor occurred during composition because it's outdated for 182 * new composition. 183 * In other words, when text changes not caused by composition occurred 184 * during composition and it may cause committing composition, this is 185 * set to true. 186 */ 187 readonly attribute boolean includingChangesDuringComposition; 188 189 /** 190 * This attribute has a valid value when type is "notify-text-change". 191 * If at least one text change occurred when there was no composition, this 192 * is set to true. Otherwise, false. 193 */ 194 readonly attribute boolean includingChangesWithoutComposition; 195 }; 196 197 /** 198 * nsITextInputProcessorCallback is a callback interface for JS to implement 199 * IME. IME implemented by JS can implement onNotify() function and must send 200 * it to nsITextInputProcessor at initializing. Then, onNotify() will be 201 * called with nsITextInputProcessorNotification instance. 202 * The reason why onNotify() uses string simply is that if we will support 203 * other notifications such as text changes and selection changes, we need to 204 * notify IME of some other information. Then, only changing 205 * nsITextInputProcessorNotification interface is better for compatibility. 206 */ 207 208 [scriptable, function, uuid(23d5f242-adb5-46f1-8766-90d1bf0383df)] 209 interface nsITextInputProcessorCallback : nsISupports 210 { 211 /** 212 * When Gecko notifies IME of something or requests something to IME, 213 * this is called. 214 * 215 * @param aTextInputProcessor Reference to the nsITextInputProcessor service 216 * which is the original receiver of the request 217 * or notification. 218 * @param aNotification Stores type of notifications and additional 219 * information. 220 * @return Return true if it succeeded or does nothing. 221 * Otherwise, return false. 222 * 223 * Example #1 The simplest implementation of nsITextInputProcessorCallback is: 224 * 225 * function simpleCallback(aTIP, aNotification) 226 * { 227 * try { 228 * switch (aNotification.type) { 229 * case "request-to-commit": 230 * aTIP.commitComposition(); 231 * break; 232 * case "request-to-cancel": 233 * aTIP.cancelComposition(); 234 * break; 235 * } 236 * } catch (e) { 237 * return false; 238 * } 239 * return true; 240 * } 241 * 242 * var TIP = Components.classes["@mozilla.org/text-input-processor;1"]. 243 * createInstance(Components.interfaces.nsITextInputProcessor); 244 * if (!TIP.init(window, simpleCallback)) { 245 * return; 246 * } 247 */ 248 boolean onNotify(in nsITextInputProcessor aTextInputProcessor, 249 in nsITextInputProcessorNotification aNotification); 250 };