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