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   readonly attribute Selection selection;
  54
  55   void setAttributeOrEquivalent(in Element element,
  56                                 in AString sourceAttrName,
  57                                 in AString sourceAttrValue,
  58                                 in boolean aSuppressTransaction);
  59   void removeAttributeOrEquivalent(in Element element,
  60                                    in DOMString sourceAttrName,
  61                                    in boolean aSuppressTransaction);
  62
  63   /** edit flags for this editor.  May be set at any time. */
  64   attribute unsigned long flags;
  65
  66   /**
  67    * the MimeType of the document
  68    */
  69   attribute string contentsMIMEType;
  70
  71   /** Returns true if we have a document that is not marked read-only */
  72   readonly attribute boolean isDocumentEditable;
  73
  74   /** Returns true if the current selection anchor is editable */
  75   readonly attribute boolean isSelectionEditable;
  76
  77   /**
  78    * the DOM Document this editor is associated with, refcounted.
  79    */
  80   readonly attribute Document document;
  81
  82   /** the body element, i.e. the root of the editable document.
  83    */
  84   readonly attribute Element rootElement;
  85
  86   /**
  87    * the selection controller for the current presentation, refcounted.
  88    */
  89   readonly attribute nsISelectionController selectionController;
  90
  91
  92   /* ------------ Selected content removal -------------- */
  93
  94   /**
  95    * DeleteSelection removes all nodes in the current selection.
  96    * @param aDir  if eNext, delete to the right (for example, the DEL key)
  97    *              if ePrevious, delete to the left (for example, the BACKSPACE key)
  98    * @param stripWrappers If eStrip, strip any empty inline elements left
  99    *                      behind after the deletion; if eNoStrip, don't.  If in
 100    *                      doubt, pass eStrip -- eNoStrip is only for if you're
 101    *                      about to insert text or similar right after.
 102    */
 103   void deleteSelection(in short action, in short stripWrappers);
 104
 105
 106   /* ------------ Document info and file methods -------------- */
 107
 108   /** Returns true if the document has no *meaningful* content */
 109   readonly attribute boolean documentIsEmpty;
 110
 111   /** Returns true if the document is modifed and needs saving */
 112   readonly attribute boolean documentModified;
 113
 114   /** Sets the current 'Save' document character set */
 115   attribute ACString documentCharacterSet;
 116
 117   /** to be used ONLY when we need to override the doc's modification
 118     * state (such as when it's saved).
 119     */
 120   void resetModificationCount();
 121
 122   /** Gets the modification count of the document we are editing.
 123     * @return the modification count of the document being edited.
 124     *         Zero means unchanged.
 125     */
 126   long getModificationCount();
 127
 128   /** called each time we modify the document.
 129     * Increments the modification count of the document.
 130     * @param  aModCount  the number of modifications by which
 131     *                    to increase or decrease the count
 132     */
 133   void incrementModificationCount(in long aModCount);
 134
 135   /* ------------ Transaction methods -------------- */
 136
 137   /** transactionManager Get the transaction manager the editor is using.
 138     */
 139   readonly attribute nsITransactionManager transactionManager;
 140
 141   /** doTransaction() fires a transaction.
 142     * It is provided here so clients can create their own transactions.
 143     * If a transaction manager is present, it is used.
 144     * Otherwise, the transaction is just executed directly.
 145     *
 146     * @param aTxn the transaction to execute
 147     */
 148   void doTransaction(in nsITransaction txn);
 149
 150
 151   /** turn the undo system on or off
 152     * @param aEnable  if PR_TRUE, the undo system is turned on if available
 153     *                 if PR_FALSE the undo system is turned off if it
 154     *                 was previously on
 155     * @return         if aEnable is PR_TRUE, returns NS_OK if
 156     *                 the undo system could be initialized properly
 157     *                 if aEnable is PR_FALSE, returns NS_OK.
 158     */
 159   void enableUndo(in boolean enable);
 160
 161   /** undo reverses the effects of the last Do operation,
 162     * if Undo is enabled in the editor.
 163     * It is provided here so clients need no knowledge of whether
 164     * the editor has a transaction manager or not.
 165     * If a transaction manager is present, it is told to undo,
 166     * and the result of that undo is returned.
 167     * Otherwise, the Undo request is ignored and an
 168     * error NS_ERROR_NOT_AVAILABLE is returned.
 169     *
 170     */
 171   void undo(in unsigned long count);
 172
 173   /** returns state information about the undo system.
 174     * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
 175     * @param aCanUndo   [OUT] PR_TRUE if at least one transaction is
 176     *                         currently ready to be undone.
 177     */
 178   void canUndo(out boolean isEnabled, out boolean canUndo);
 179
 180   /** redo reverses the effects of the last Undo operation
 181     * It is provided here so clients need no knowledge of whether
 182     * the editor has a transaction manager or not.
 183     * If a transaction manager is present, it is told to redo and the
 184     * result of the previously undone transaction is reapplied to the document.
 185     * If no transaction is available for Redo, or if the document
 186     * has no transaction manager, the Redo request is ignored and an
 187     * error NS_ERROR_NOT_AVAILABLE is returned.
 188     *
 189     */
 190   void redo(in unsigned long count);
 191
 192   /** returns state information about the redo system.
 193     * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
 194     * @param aCanRedo   [OUT] PR_TRUE if at least one transaction is
 195                               currently ready to be redone.
 196     */
 197   void canRedo(out boolean isEnabled, out boolean canRedo);
 198
 199   /** beginTransaction is a signal from the caller to the editor that
 200     * the caller will execute multiple updates to the content tree
 201     * that should be treated as a single logical operation,
 202     * in the most efficient way possible.<br>
 203     * All transactions executed between a call to beginTransaction and
 204     * endTransaction will be undoable as an atomic action.<br>
 205     * endTransaction must be called after beginTransaction.<br>
 206     * Calls to beginTransaction can be nested, as long as endTransaction
 207     * is called once per beginUpdate.
 208     */
 209   void beginTransaction();
 210
 211   /** endTransaction is a signal to the editor that the caller is
 212     * finished updating the content model.<br>
 213     * beginUpdate must be called before endTransaction is called.<br>
 214     * Calls to beginTransaction can be nested, as long as endTransaction
 215     * is called once per beginTransaction.
 216     */
 217   void endTransaction();
 218
 219   /**
 220    * While setting the flag with this method to false, CreateElementTransaction,
 221    * DeleteRangeTransaction, DeleteTextTransaction, InsertNodeTransaction,
 222    * InsertTextTransaction and SplitNodeTransaction won't change Selection
 223    * after modifying the DOM tree.
 224    * Note that calling this with false does not guarantee that Selection won't
 225    * be changed because other transaction may ignore this flag, editor itself
 226    * may change selection, and current selection may become invalid after
 227    * changing the DOM tree, etc.
 228    * After calling this method with true, the caller should guarantee that
 229    * Selection should be positioned where user expects.
 230    *
 231    * @param should    false if you don't want above transactions to modify
 232    *                  Selection automatically after modifying the DOM tree.
 233    *                  Note that calling this with false does not guarantee
 234    *                  that Selection is never changed.
 235    */
 236   void setShouldTxnSetSelection(in boolean should);
 237
 238   /* ------------ Inline Spell Checking methods -------------- */
 239
 240   /** Returns the inline spell checker associated with this object. The spell
 241     * checker is lazily created, so this function may create the object for
 242     * you during this call.
 243     * @param  autoCreate  If true, this will create a spell checker object
 244     *                     if one does not exist yet for this editor. If false
 245     *                     and the object has not been created, this function
 246     *                     WILL RETURN NULL.
 247     */
 248   nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);
 249
 250   /** Called when the user manually overrides the spellchecking state for this
 251     * editor.
 252     * @param  enable  The new state of spellchecking in this editor, as
 253     *                 requested by the user.
 254     */
 255   void setSpellcheckUserOverride(in boolean enable);
 256
 257   /* ------------ Clipboard methods -------------- */
 258
 259   /** cut the currently selected text, putting it into the OS clipboard
 260     * What if no text is selected?
 261     * What about mixed selections?
 262     * What are the clipboard formats?
 263     */
 264   void cut();
 265
 266   /** Can we cut? True if the doc is modifiable, and we have a non-
 267     * collapsed selection.
 268     */
 269   boolean canCut();
 270
 271   /** copy the currently selected text, putting it into the OS clipboard
 272     * What if no text is selected?
 273     * What about mixed selections?
 274     * What are the clipboard formats?
 275     */
 276   void copy();
 277
 278   /** Can we copy? True if we have a non-collapsed selection.
 279     */
 280   boolean canCopy();
 281
 282   /** Can we delete? True if we have a non-collapsed selection.
 283     */
 284   boolean canDelete();
 285
 286   /** paste the text in the OS clipboard at the cursor position, replacing
 287     * the selected text (if any)
 288     */
 289   void paste(in long aSelectionType);
 290
 291   /** Paste the text in |aTransferable| at the cursor position, replacing the
 292     * selected text (if any).
 293     */
 294   void pasteTransferable(in nsITransferable aTransferable);
 295
 296   /** Can we paste? True if the doc is modifiable, and we have
 297     * pasteable data in the clipboard.
 298     */
 299   boolean canPaste(in long aSelectionType);
 300
 301   /* ------------ Selection methods -------------- */
 302
 303   /** sets the document selection to the entire contents of the document */
 304   void selectAll();
 305
 306   /**
 307    * Collapses selection at start of the document.  If it's an HTML editor,
 308    * collapses selection at start of current editing host (<body> element if
 309    * it's in designMode) instead.  If there is a non-editable node before any
 310    * editable text nodes or inline elements which can have text nodes as their
 311    * children, collapses selection at start of the editing host.  If there is
 312    * an editable text node which is not collapsed, collapses selection at
 313    * start of the text node.  If there is an editable inline element which
 314    * cannot have text nodes as its child, collapses selection at before the
 315    * element node.  Otherwise, collapses selection at start of the editing
 316    * host.
 317    */
 318   void beginningOfDocument();
 319
 320   /** sets the document selection to the end of the document */
 321   void endOfDocument();
 322
 323   /* ------------ Node manipulation methods -------------- */
 324
 325   /**
 326    * setAttribute() sets the attribute of aElement.
 327    * No checking is done to see if aAttribute is a legal attribute of the node,
 328    * or if aValue is a legal value of aAttribute.
 329    *
 330    * @param aElement    the content element to operate on
 331    * @param aAttribute  the string representation of the attribute to set
 332    * @param aValue      the value to set aAttribute to
 333    */
 334   void setAttribute(in Element aElement, in AString attributestr,
 335                     in AString attvalue);
 336
 337   /**
 338    * getAttributeValue() retrieves the attribute's value for aElement.
 339    *
 340    * @param aElement      the content element to operate on
 341    * @param aAttribute    the string representation of the attribute to get
 342    * @param aResultValue  [OUT] the value of aAttribute.
 343    *                      Only valid if aResultIsSet is PR_TRUE
 344    * @return              PR_TRUE if aAttribute is set on the current node,
 345    *                      PR_FALSE if it is not.
 346    */
 347   boolean getAttributeValue(in Element aElement,
 348                             in AString attributestr,
 349                             out AString resultValue);
 350
 351   /**
 352    * removeAttribute() deletes aAttribute from the attribute list of aElement.
 353    * If aAttribute is not an attribute of aElement, nothing is done.
 354    *
 355    * @param aElement      the content element to operate on
 356    * @param aAttribute    the string representation of the attribute to get
 357    */
 358   void removeAttribute(in Element aElement,
 359                        in AString aAttribute);
 360
 361   /**
 362    * cloneAttribute() copies the attribute from the source node to
 363    * the destination node and delete those not in the source.
 364    *
 365    * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
 366    * @param aAttribute     the name of the attribute to copy
 367    * @param aDestElement   the destination element to operate on
 368    * @param aSourceElement the source element to copy attributes from
 369    * @exception NS_ERROR_NULL_POINTER at least one of the elements is null
 370    */
 371   void cloneAttribute(in AString aAttribute,
 372                       in Element aDestElement, in Element aSourceElement);
 373
 374   /**
 375    * cloneAttributes() is similar to Node::cloneNode(),
 376    *   it assures the attribute nodes of the destination are identical
 377    *   with the source node by copying all existing attributes from the
 378    *   source and deleting those not in the source.
 379    *   This is used when the destination element already exists
 380    *
 381    * @param aDestNode     the destination element to operate on
 382    * @param aSourceNode   the source element to copy attributes from
 383    */
 384   void cloneAttributes(in Element aDestElement, in Element aSourceElement);
 385
 386   /**
 387    * insertNode inserts aNode into aParent at aPosition.
 388    * No checking is done to verify the legality of the insertion.
 389    * That is the responsibility of the caller.
 390    * @param aNode     The DOM Node to insert.
 391    * @param aParent   The node to insert the new object into
 392    * @param aPosition The place in aParent to insert the new node
 393    *                  0=first child, 1=second child, etc.
 394    *                  any number > number of current children = last child
 395    */
 396   void insertNode(in Node node,
 397                   in Node parent,
 398                   in long aPosition);
 399
 400
 401   /**
 402    * splitNode() creates a new node identical to an existing node,
 403    * and split the contents between the two nodes
 404    * @param aExistingRightNode   the node to split.
 405    *                             It will become the new node's next sibling.
 406    * @param aOffset              the offset of aExistingRightNode's
 407    *                             content|children to do the split at
 408    * @param aNewLeftNode         [OUT] the new node resulting from the split,
 409    *                             becomes aExistingRightNode's previous sibling.
 410    */
 411   void splitNode(in Node existingRightNode,
 412                  in long offset,
 413                  out Node newLeftNode);
 414
 415   /**
 416    * joinNodes() takes 2 nodes and merge their content|children.
 417    * @param aLeftNode     The left node.  It will be deleted.
 418    * @param aRightNode    The right node. It will remain after the join.
 419    * @param aParent       The parent of aExistingRightNode
 420    *
 421    *                      There is no requirement that the two nodes be
 422    *                      of the same type.  However, a text node can be
 423    *                      merged only with another text node.
 424    */
 425   void joinNodes(in Node leftNode,
 426                  in Node rightNode,
 427                  in Node parent);
 428
 429   /**
 430    * deleteNode removes aChild from aParent.
 431    * @param aChild    The node to delete
 432    */
 433   void deleteNode(in Node child);
 434
 435   /**
 436    * markNodeDirty() sets a special dirty attribute on the node.
 437    * Usually this will be called immediately after creating a new node.
 438    * @param aNode      The node for which to insert formatting.
 439    */
 440   void markNodeDirty(in Node node);
 441
 442 /* ------------ Output methods -------------- */
 443
 444   /**
 445    * Output methods:
 446    * aFormatType is a mime type, like text/plain.
 447    */
 448   AString outputToString(in AString formatType,
 449                          in unsigned long flags);
 450
 451   /* ------------ Various listeners methods --------------
 452    * nsIEditor holds strong references to the editor observers, action listeners
 453    * and document state listeners.
 454    */
 455
 456   /** add an EditorObserver to the editors list of observers. */
 457   void addEditorObserver(in nsIEditorObserver observer);
 458
 459   /** Remove an EditorObserver from the editor's list of observers. */
 460   void removeEditorObserver(in nsIEditorObserver observer);
 461
 462   /** add an EditActionListener to the editors list of listeners. */
 463   void addEditActionListener(in nsIEditActionListener listener);
 464
 465   /** Remove an EditActionListener from the editor's list of listeners. */
 466   void removeEditActionListener(in nsIEditActionListener listener);
 467
 468   /** Add a DocumentStateListener to the editors list of doc state listeners. */
 469   void addDocumentStateListener(in nsIDocumentStateListener listener);
 470
 471   /** Remove a DocumentStateListener to the editors list of doc state listeners. */
 472   void removeDocumentStateListener(in nsIDocumentStateListener listener);
 473
 474
 475   /* ------------ Debug methods -------------- */
 476
 477   /**
 478    * And a debug method -- show us what the tree looks like right now
 479    */
 480   void dumpContentTree();
 481
 482   /** Dumps a text representation of the content tree to standard out */
 483   void debugDumpContent() ;
 484
 485   /* Run unit tests. Noop in optimized builds */
 486   void debugUnitTests(out long outNumTests, out long  outNumTestsFailed);
 487
 488   /**
 489    * forceCompositionEnd() force the composition end
 490    */
 491   void forceCompositionEnd();
 492
 493   /**
 494    * whether this editor has active IME transaction
 495    */
 496   readonly attribute boolean composing;
 497
 498 %{C++
 499   /**
 500    * AsEditorBase() returns a pointer to EditorBase class.
 501    *
 502    * In order to avoid circular dependency issues, this method is defined
 503    * in mozilla/EditorBase.h.  Consumers need to #include that header.
 504    */
 505   inline mozilla::EditorBase* AsEditorBase();
 506   inline const mozilla::EditorBase* AsEditorBase() const;
 507
 508   /**
 509    * AsTextEditor() returns a pointer to TextEditor class.
 510    *
 511    * In order to avoid circular dependency issues, this method is defined
 512    * in mozilla/TextEditor.h.  Consumers need to #include that header.
 513    */
 514   inline mozilla::TextEditor* AsTextEditor();
 515   inline const mozilla::TextEditor* AsTextEditor() const;
 516
 517   /**
 518    * AsHTMLEditor() returns a pointer to HTMLEditor class.
 519    *
 520    * In order to avoid circular dependency issues, this method is defined
 521    * in mozilla/HTMLEditor.h.  Consumers need to #include that header.
 522    */
 523   inline mozilla::HTMLEditor* AsHTMLEditor();
 524   inline const mozilla::HTMLEditor* AsHTMLEditor() const;
 525 %}
 526 };