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