editor/nsIEditor.idl

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