nsIEditor.idl (25739B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #include "nsISupports.idl" 8 #include "nsIClipboard.idl" 9 #include "domstubs.idl" 10 11 %{C++ 12 #include "mozilla/Debug.h" 13 %} 14 15 interface nsISelectionController; 16 interface nsIDocumentStateListener; 17 interface nsIEditActionListener; 18 interface nsIInlineSpellChecker; 19 interface nsITransferable; 20 21 webidl Document; 22 webidl Element; 23 webidl Node; 24 webidl Selection; 25 26 %{C++ 27 namespace mozilla { 28 class EditorBase; 29 class HTMLEditor; 30 class TextEditor; 31 } // namespace mozilla 32 %} 33 34 [scriptable, builtinclass, uuid(094be624-f0bf-400f-89e2-6a84baab9474)] 35 interface nsIEditor : nsISupports 36 { 37 %{C++ 38 typedef short EDirection; 39 typedef short EStripWrappers; 40 %} 41 const short eNone = 0; 42 const short eNext = 1; 43 const short ePrevious = 2; 44 const short eNextWord = 3; 45 const short ePreviousWord = 4; 46 const short eToBeginningOfLine = 5; 47 const short eToEndOfLine = 6; 48 49 %{C++ 50 static bool EDirectionIsValid(EDirection aDirectionAndAmount) { 51 return aDirectionAndAmount == nsIEditor::eNone || 52 aDirectionAndAmount == nsIEditor::eNext || 53 aDirectionAndAmount == nsIEditor::ePrevious || 54 aDirectionAndAmount == nsIEditor::eNextWord || 55 aDirectionAndAmount == nsIEditor::ePreviousWord || 56 aDirectionAndAmount == nsIEditor::eToBeginningOfLine || 57 aDirectionAndAmount == nsIEditor::eToEndOfLine; 58 } 59 static bool EDirectionIsValidExceptNone(EDirection aDirectionAndAmount) { 60 return aDirectionAndAmount != nsIEditor::eNone && 61 EDirectionIsValid(aDirectionAndAmount); 62 } 63 64 /** 65 * Return true if nsIEditor::EDirection value means the direction of pressing 66 * `Backspace` key. 67 */ 68 [[nodiscard]] static bool DirectionIsBackspace( 69 EDirection aDirectionAndAmount) { 70 MOZ_ASSERT(EDirectionIsValid(aDirectionAndAmount)); 71 return aDirectionAndAmount == nsIEditor::ePrevious || 72 aDirectionAndAmount == nsIEditor::ePreviousWord || 73 aDirectionAndAmount == nsIEditor::eToBeginningOfLine; 74 } 75 76 /** 77 * Return true if nsIEditor::EDirection value means the direction of pressing 78 * `Delete` key (forwardDelete). 79 */ 80 [[nodiscard]] static bool DirectionIsDelete( 81 EDirection aDirectionAndAmount) { 82 MOZ_ASSERT(EDirectionIsValid(aDirectionAndAmount)); 83 return aDirectionAndAmount == nsIEditor::eNext || 84 aDirectionAndAmount == nsIEditor::eNextWord || 85 aDirectionAndAmount == nsIEditor::eToEndOfLine; 86 } 87 %} 88 89 const short eStrip = 0; 90 const short eNoStrip = 1; 91 92 // If you want an HTML editor to behave as a plaintext editor, specify this 93 // flag. This is currently used only with plaintext email composer. 94 const long eEditorPlaintextMask = 0x0001; 95 // We don't support single line editor mode with HTML editors. Therefore, 96 // don't specify this for HTML editor. 97 const long eEditorSingleLineMask = 0x0002; 98 // We don't support password editor mode with HTML editors. Therefore, 99 // don't specify this for HTML editor. 100 const long eEditorPasswordMask = 0x0004; 101 // When the editor should be in readonly mode (currently, same as "disabled"), 102 // you can specify this flag with any editor instances. 103 // NOTE: Setting this flag does not change the style of editor. This just 104 // changes the internal editor's readonly state. 105 // NOTE: The readonly mode does NOT block XPCOM APIs which modify the editor 106 // content. This just blocks edit operations from user input and editing 107 // commands (both HTML Document.execCommand and the XUL commands). 108 // FIXME: XPCOM methods of TextEditor may be blocked by this flag. If you 109 // find it, file a bug. 110 const long eEditorReadonlyMask = 0x0008; 111 // If you want an HTML editor to work as an email composer, specify this flag. 112 // And you can specify this to text editor too for making spellchecker for 113 // the text editor should work exactly same as email composer's. 114 const long eEditorMailMask = 0x0020; 115 // allow the editor to set font: monospace on the root node 116 const long eEditorEnableWrapHackMask = 0x0040; 117 // If you want to move focus from an HTML editor with tab navigation, 118 // specify this flag. This is not available with text editors becase 119 // it's always tabbable. 120 // Note that if this is not specified, link navigation is also enabled in 121 // the editable content. 122 const long eEditorAllowInteraction = 0x0200; 123 // when this flag is set, the internal direction of the editor is RTL. 124 // if neither of the direction flags are set, the direction is determined 125 // from the text control's content node. 126 const long eEditorRightToLeft = 0x0800; 127 // when this flag is set, the internal direction of the editor is LTR. 128 const long eEditorLeftToRight = 0x1000; 129 // when this flag is set, the editor's text content is not spell checked. 130 const long eEditorSkipSpellCheck = 0x2000; 131 132 /* 133 * The valid values for newlines handling. 134 * Can't change the values unless we remove 135 * use of the pref. 136 */ 137 const long eNewlinesPasteIntact = 0; 138 const long eNewlinesPasteToFirst = 1; 139 const long eNewlinesReplaceWithSpaces = 2; 140 const long eNewlinesStrip = 3; 141 const long eNewlinesReplaceWithCommas = 4; 142 const long eNewlinesStripSurroundingWhitespace = 5; 143 144 readonly attribute Selection selection; 145 146 [can_run_script] 147 void setAttributeOrEquivalent(in Element element, 148 in AString sourceAttrName, 149 in AString sourceAttrValue, 150 in boolean aSuppressTransaction); 151 [can_run_script] 152 void removeAttributeOrEquivalent(in Element element, 153 in AString sourceAttrName, 154 in boolean aSuppressTransaction); 155 156 /** edit flags for this editor. May be set at any time. */ 157 [setter_can_run_script] attribute unsigned long flags; 158 159 /** 160 * the MimeType of the document 161 */ 162 attribute AString contentsMIMEType; 163 164 /** Returns true if we have a document that is not marked read-only */ 165 readonly attribute boolean isDocumentEditable; 166 167 /** Returns true if the current selection anchor is editable */ 168 readonly attribute boolean isSelectionEditable; 169 170 /** 171 * the DOM Document this editor is associated with, refcounted. 172 */ 173 readonly attribute Document document; 174 175 /** the body element, i.e. the root of the editable document. 176 */ 177 readonly attribute Element rootElement; 178 179 /** 180 * the selection controller for the current presentation, refcounted. 181 */ 182 readonly attribute nsISelectionController selectionController; 183 184 185 /* ------------ Selected content removal -------------- */ 186 187 /** 188 * DeleteSelection removes all nodes in the current selection. 189 * @param aDir if eNext, delete to the right (for example, the DEL key) 190 * if ePrevious, delete to the left (for example, the BACKSPACE key) 191 * @param stripWrappers If eStrip, strip any empty inline elements left 192 * behind after the deletion; if eNoStrip, don't. If in 193 * doubt, pass eStrip -- eNoStrip is only for if you're 194 * about to insert text or similar right after. 195 */ 196 [can_run_script] 197 void deleteSelection(in short action, in short stripWrappers); 198 199 200 /* ------------ Document info and file methods -------------- */ 201 202 /** Returns true if the document has no *meaningful* content */ 203 readonly attribute boolean documentIsEmpty; 204 205 /** Returns true if the document is modifed and needs saving */ 206 readonly attribute boolean documentModified; 207 208 /** 209 * Sets document's character set. This is available only when the editor 210 * instance is an HTMLEditor since it's odd to change character set of 211 * parent document of `<input>` and `<textarea>`. 212 */ 213 [setter_can_run_script] 214 attribute ACString documentCharacterSet; 215 216 /** to be used ONLY when we need to override the doc's modification 217 * state (such as when it's saved). 218 */ 219 [can_run_script] 220 void resetModificationCount(); 221 222 /** Gets the modification count of the document we are editing. 223 * @return the modification count of the document being edited. 224 * Zero means unchanged. 225 */ 226 long getModificationCount(); 227 228 /** called each time we modify the document. 229 * Increments the modification count of the document. 230 * @param aModCount the number of modifications by which 231 * to increase or decrease the count 232 */ 233 [can_run_script] 234 void incrementModificationCount(in long aModCount); 235 236 /* ------------ Transaction methods -------------- */ 237 238 /** turn the undo system on or off 239 * @param aEnable if PR_TRUE, the undo system is turned on if available 240 * if PR_FALSE the undo system is turned off if it 241 * was previously on 242 * @return if aEnable is PR_TRUE, returns NS_OK if 243 * the undo system could be initialized properly 244 * if aEnable is PR_FALSE, returns NS_OK. 245 */ 246 void enableUndo(in boolean enable); 247 248 /** 249 * Returns true when undo/redo is enabled (by default). 250 */ 251 [infallible] readonly attribute boolean undoRedoEnabled; 252 253 /** 254 * Retruns true when undo/redo is enabled and there is one or more transaction 255 * in the undo stack. 256 */ 257 [infallible] readonly attribute boolean canUndo; 258 259 /** 260 * Returns true when undo/redo is enabled and there is one or more transaction 261 * in the redo stack. 262 */ 263 [infallible] readonly attribute boolean canRedo; 264 265 /** 266 * Clears the transactions both for undo and redo. 267 * This may fail if you call this while editor is handling something, i.e., 268 * don't call this from a legacy mutation event listeners, then, you won't 269 * see any exceptions. 270 */ 271 [binaryname(ClearUndoRedoXPCOM)] 272 void clearUndoRedo(); 273 274 /** 275 * Undo the topmost transaction in the undo stack. 276 * This may throw exception when this is called while editor is handling 277 * transactions. 278 */ 279 [can_run_script] 280 void undo(); 281 282 /** 283 * Undo all transactions in the undo stack. 284 * This may throw exception when this is called while editor is handling 285 * transactions. 286 */ 287 [can_run_script] 288 void undoAll(); 289 290 /** 291 * Redo the topmost transaction in the redo stack. 292 * This may throw exception when this is called while editor is handling 293 * transactions. 294 */ 295 [can_run_script] 296 void redo(); 297 298 /** beginTransaction is a signal from the caller to the editor that 299 * the caller will execute multiple updates to the content tree 300 * that should be treated as a single logical operation, 301 * in the most efficient way possible.<br> 302 * All transactions executed between a call to beginTransaction and 303 * endTransaction will be undoable as an atomic action.<br> 304 * endTransaction must be called after beginTransaction.<br> 305 * Calls to beginTransaction can be nested, as long as endTransaction 306 * is called once per beginUpdate. 307 */ 308 [can_run_script] 309 void beginTransaction(); 310 311 /** endTransaction is a signal to the editor that the caller is 312 * finished updating the content model.<br> 313 * beginUpdate must be called before endTransaction is called.<br> 314 * Calls to beginTransaction can be nested, as long as endTransaction 315 * is called once per beginTransaction. 316 */ 317 [can_run_script] 318 void endTransaction(); 319 320 /* ------------ Inline Spell Checking methods -------------- */ 321 322 /** Returns the inline spell checker associated with this object. The spell 323 * checker is lazily created, so this function may create the object for 324 * you during this call. 325 * @param autoCreate If true, this will create a spell checker object 326 * if one does not exist yet for this editor. If false 327 * and the object has not been created, this function 328 * WILL RETURN NULL. 329 */ 330 nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate); 331 332 /** Called when the user manually overrides the spellchecking state for this 333 * editor. 334 * @param enable The new state of spellchecking in this editor, as 335 * requested by the user. 336 */ 337 void setSpellcheckUserOverride(in boolean enable); 338 339 /* ------------ Clipboard methods -------------- */ 340 341 /** cut the currently selected text, putting it into the OS clipboard 342 * What if no text is selected? 343 * What about mixed selections? 344 * What are the clipboard formats? 345 */ 346 [can_run_script] 347 void cut(); 348 349 /** 350 * canCut() returns true if selected content is allowed to be copied to the 351 * clipboard and to be removed. 352 * Note that this always returns true if the editor is in a non-chrome 353 * HTML/XHTML document. 354 * FYI: Current user in script is only BlueGriffon. 355 */ 356 [can_run_script] 357 boolean canCut(); 358 359 /** copy the currently selected text, putting it into the OS clipboard 360 * What if no text is selected? 361 * What about mixed selections? 362 * What are the clipboard formats? 363 */ 364 [can_run_script] 365 void copy(); 366 367 /** 368 * canCopy() returns true if selected content is allowed to be copied to 369 * the clipboard. 370 * Note that this always returns true if the editor is in a non-chrome 371 * HTML/XHTML document. 372 * FYI: Current user in script is only BlueGriffon. 373 */ 374 [can_run_script] 375 boolean canCopy(); 376 377 /** paste the text in the OS clipboard at the cursor position, replacing 378 * the selected text (if any) 379 */ 380 [can_run_script] 381 void paste(in nsIClipboard_ClipboardType aClipboardType); 382 383 /** Paste the text in |aTransferable| at the cursor position, replacing the 384 * selected text (if any). 385 */ 386 [can_run_script] 387 void pasteTransferable(in nsITransferable aTransferable); 388 389 /** Can we paste? True if the doc is modifiable, and we have 390 * pasteable data in the clipboard. 391 */ 392 boolean canPaste(in nsIClipboard_ClipboardType aClipboardType); 393 394 /* ------------ Selection methods -------------- */ 395 396 /** sets the document selection to the entire contents of the document */ 397 [can_run_script] 398 void selectAll(); 399 400 /** 401 * Collapses selection at start of the document. If it's an HTML editor, 402 * collapses selection at start of current editing host (<body> element if 403 * it's in designMode) instead. If there is a non-editable node before any 404 * editable text nodes or inline elements which can have text nodes as their 405 * children, collapses selection at start of the editing host. If there is 406 * an editable text node which is not collapsed, collapses selection at 407 * start of the text node. If there is an editable inline element which 408 * cannot have text nodes as its child, collapses selection at before the 409 * element node. Otherwise, collapses selection at start of the editing 410 * host. 411 */ 412 [can_run_script] 413 void beginningOfDocument(); 414 415 /** 416 * Sets the selection to the end of the last leaf child/descendant or the root 417 * element. 418 */ 419 [can_run_script] 420 void endOfDocument(); 421 422 /* ------------ Node manipulation methods -------------- */ 423 424 /** 425 * setAttribute() sets the attribute of aElement. 426 * No checking is done to see if aAttribute is a legal attribute of the node, 427 * or if aValue is a legal value of aAttribute. 428 * 429 * @param aElement the content element to operate on 430 * @param aAttribute the string representation of the attribute to set 431 * @param aValue the value to set aAttribute to 432 */ 433 [can_run_script] 434 void setAttribute(in Element aElement, in AString attributestr, 435 in AString attvalue); 436 437 /** 438 * removeAttribute() deletes aAttribute from the attribute list of aElement. 439 * If aAttribute is not an attribute of aElement, nothing is done. 440 * 441 * @param aElement the content element to operate on 442 * @param aAttribute the string representation of the attribute to get 443 */ 444 [can_run_script] 445 void removeAttribute(in Element aElement, 446 in AString aAttribute); 447 448 /** 449 * cloneAttributes() is similar to Node::cloneNode(), 450 * it assures the attribute nodes of the destination are identical 451 * with the source node by copying all existing attributes from the 452 * source and deleting those not in the source. 453 * This is used when the destination element already exists 454 * 455 * @param aDestNode the destination element to operate on 456 * @param aSourceNode the source element to copy attributes from 457 */ 458 [can_run_script] 459 void cloneAttributes(in Element aDestElement, in Element aSourceElement); 460 461 /** 462 * insertNode inserts aNode into aParent at aPosition and this operation is 463 * undoable. 464 * No checking is done to verify the legality of the insertion. 465 * That is the responsibility of the caller. 466 * TODO: Move this method to nsIHTMLEditor, TextEditor does not allow chrome 467 * script to customize its anonymous subtree. 468 * 469 * @param aNode The DOM Node to insert. 470 * @param aParent The node to insert the new object into 471 * @param aPosition The place in aParent to insert the new node 472 * 0=first child, 1=second child, etc. 473 * If larger than number of children of aParent, 474 * this will append aNode into aParent. 475 * @param aPreseveSelection The default value is false. If set to true, 476 * the insert node handler does not update 477 * Selection. 478 * FYI: If somebody handles `beforeinput` event or 479 * `input` event caused by this and it does 480 * something undoable, selection may be changed by 481 * that. 482 */ 483 [optional_argc, can_run_script] 484 void insertNode(in Node node, 485 in Node parent, 486 in unsigned long aPosition, 487 [optional] in boolean aPreserveSelection); 488 489 490 /** 491 * deleteNode removes aChild from aParent and this operation is undobable. 492 * TODO: Move this method to nsIHTMLEditor, TextEditor does not allow chrome 493 * script to customize its anonymous subtree. 494 * 495 * @param aChild The node to delete 496 * @param aPreseveSelection The default value is false. If set to true, 497 * the insert node handler does not update 498 * Selection. 499 * FYI: If somebody handles `beforeinput` event or 500 * `input` event caused by this and it does 501 * something undoable, selection may be changed by 502 * that. 503 */ 504 [optional_argc, can_run_script] 505 void deleteNode(in Node child, [optional] in boolean aPreserveSelection); 506 507 /* ------------ Output methods -------------- */ 508 509 /** 510 * Output methods: 511 * aFormatType is a mime type, like text/plain. 512 */ 513 AString outputToString(in AString formatType, 514 in unsigned long flags); 515 516 /* ------------ Various listeners methods -------------- 517 * nsIEditor holds strong references to the editor observers, action listeners 518 * and document state listeners. 519 */ 520 521 /** add an EditActionListener to the editors list of listeners. */ 522 void addEditActionListener(in nsIEditActionListener listener); 523 524 /** Remove an EditActionListener from the editor's list of listeners. */ 525 void removeEditActionListener(in nsIEditActionListener listener); 526 527 /** Add a DocumentStateListener to the editors list of doc state listeners. */ 528 void addDocumentStateListener(in nsIDocumentStateListener listener); 529 530 /** Remove a DocumentStateListener to the editors list of doc state listeners. */ 531 void removeDocumentStateListener(in nsIDocumentStateListener listener); 532 533 /** 534 * forceCompositionEnd() force the composition end 535 */ 536 void forceCompositionEnd(); 537 538 /** 539 * whether this editor has active IME transaction 540 */ 541 readonly attribute boolean composing; 542 543 /** 544 * unmask() is available only when the editor is a passwrod field. This 545 * unmasks characters in specified by aStart and aEnd. If there have 546 * already unmasked characters, they are masked when this is called. 547 * Note that if you calls this without non-zero `aTimeout`, you bear 548 * responsibility for masking password with calling `mask()`. I.e., 549 * user inputting password won't be masked automacitally. If user types 550 * a new character and echo is enabled, unmasked range is expanded to 551 * including it. 552 * 553 * @param aStart Optional, first index to show the character. If you 554 * specify middle of a surrogate pair, this expands the 555 * range to include the prceding high surrogate 556 * automatically. 557 * If omitted, it means that all characters of the 558 * password becomes unmasked. 559 * @param aEnd Optional, next index of last unmasked character. If 560 * you specify middle of a surrogate pair, the expands 561 * the range to include the following low surrogate. 562 * If omitted or negative value, it means unmasking all 563 * characters after aStart. Specifying same index 564 * throws an exception. 565 * @param aTimeout Optional, specify milliseconds to hide the unmasked 566 * characters if you want to show them temporarily. 567 * If omitted or 0, it means this won't mask the characters 568 * automatically. 569 */ 570 [can_run_script, optional_argc] void unmask( 571 [optional] in unsigned long aStart, 572 [optional] in long long aEnd, 573 [optional] in unsigned long aTimeout); 574 575 /** 576 * mask() is available only when the editor is a password field. This masks 577 * all unmasked characters immediately. 578 */ 579 [can_run_script] void mask(); 580 581 /** 582 * These attributes are available only when the editor is a password field. 583 * unmaskedStart is first unmasked character index, or 0 if there is no 584 * unmasked characters. 585 * unmaskedEnd is next index of the last unmasked character. 0 means there 586 * is no unmasked characters. 587 */ 588 readonly attribute unsigned long unmaskedStart; 589 readonly attribute unsigned long unmaskedEnd; 590 591 /** 592 * autoMaskingEnabled is true if unmasked range and newly inputted characters 593 * are masked automatically. That's the default state. If false, until 594 * `mask()` is called, unmasked range and newly inputted characters are 595 * unmasked. 596 */ 597 readonly attribute boolean autoMaskingEnabled; 598 599 /** 600 * passwordMask attribute is a mask character which is used to mask password. 601 */ 602 readonly attribute AString passwordMask; 603 604 /** 605 * The length of the contents in characters. 606 */ 607 readonly attribute unsigned long textLength; 608 609 /** Get and set newline handling. 610 * 611 * Values are the constants defined above. 612 */ 613 attribute long newlineHandling; 614 615 /** 616 * Inserts a string at the current location, 617 * given by the selection. 618 * If the selection is not collapsed, the selection is deleted 619 * and the insertion takes place at the resulting collapsed selection. 620 * 621 * @param aString the string to be inserted 622 */ 623 [can_run_script] 624 void insertText(in AString aStringToInsert); 625 626 /** 627 * Insert a line break into the content model. 628 * The interpretation of a break is up to the implementation: 629 * it may enter a character, split a node in the tree, etc. 630 * This may be more efficient than calling InsertText with a newline. 631 */ 632 [can_run_script] 633 void insertLineBreak(); 634 635 %{C++ 636 inline bool IsHTMLEditor() const; 637 inline bool IsTextEditor() const; 638 639 /** 640 * AsEditorBase() returns a pointer to EditorBase class. 641 * 642 * In order to avoid circular dependency issues, this method is defined 643 * in mozilla/EditorBase.h. Consumers need to #include that header. 644 */ 645 inline mozilla::EditorBase* AsEditorBase(); 646 inline const mozilla::EditorBase* AsEditorBase() const; 647 648 /** 649 * AsTextEditor() and GetTextEditor() return a pointer to TextEditor class. 650 * AsTextEditor() does not check the concrete class type. So, it never 651 * returns nullptr. GetAsTextEditor() does check the concrete class type. 652 * So, it may return nullptr. 653 * 654 * In order to avoid circular dependency issues, this method is defined 655 * in mozilla/TextEditor.h. Consumers need to #include that header. 656 */ 657 inline mozilla::TextEditor* AsTextEditor(); 658 inline const mozilla::TextEditor* AsTextEditor() const; 659 inline mozilla::TextEditor* GetAsTextEditor(); 660 inline const mozilla::TextEditor* GetAsTextEditor() const; 661 662 /** 663 * AsHTMLEditor() and GetHTMLEditor() return a pointer to HTMLEditor class. 664 * AsHTMLEditor() does not check the concrete class type. So, it never 665 * returns nullptr. GetAsHTMLEditor() does check the concrete class type. 666 * So, it may return nullptr. 667 * 668 * In order to avoid circular dependency issues, this method is defined 669 * in mozilla/HTMLEditor.h. Consumers need to #include that header. 670 */ 671 inline mozilla::HTMLEditor* AsHTMLEditor(); 672 inline const mozilla::HTMLEditor* AsHTMLEditor() const; 673 inline mozilla::HTMLEditor* GetAsHTMLEditor(); 674 inline const mozilla::HTMLEditor* GetAsHTMLEditor() const; 675 %} 676 };