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