editor/nsIEditActionListener.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include "domstubs.idl"
   8
   9 interface nsISelection;
  10
  11
  12 /*
  13 Editor Action Listener interface to outside world
  14 */
  15
  16
  17 /**
  18  * A generic editor action listener interface.
  19  * <P>
  20  * nsIEditActionListener is the interface used by applications wishing to be notified
  21  * when the editor modifies the DOM tree.
  22  *
  23  * Note:  this is the wrong class to implement if you are interested in generic
  24  * change notifications.  For generic notifications, you should implement
  25  * nsIDocumentObserver.
  26  */
  27 [scriptable, uuid(b22907b1-ee93-11d2-8d50-000064657374)]
  28
  29 interface nsIEditActionListener : nsISupports{
  30
  31   /**
  32    * Called before the editor creates a node.
  33    * @param aTag      The tag name of the DOM Node to create.
  34    * @param aParent   The node to insert the new object into
  35    * @param aPosition The place in aParent to insert the new node
  36    *                  0=first child, 1=second child, etc.
  37    *                  any number > number of current children = last child
  38    */
  39   void WillCreateNode(in DOMString aTag,
  40                             in nsIDOMNode   aParent,
  41                             in long aPosition);
  42
  43   /**
  44    * Called after the editor creates a node.
  45    * @param aTag      The tag name of the DOM Node to create.
  46    * @param aNode     The DOM Node that was created.
  47    * @param aParent   The node to insert the new object into
  48    * @param aPosition The place in aParent to insert the new node
  49    *                  0=first child, 1=second child, etc.
  50    *                  any number > number of current children = last child
  51    * @param aResult   The result of the create node operation.
  52    */
  53   void DidCreateNode(in DOMString aTag,
  54                            in nsIDOMNode aNode,
  55                            in nsIDOMNode aParent,
  56                            in long          aPosition,
  57                            in nsresult      aResult);
  58
  59   /**
  60    * Called before the editor inserts a node.
  61    * @param aNode     The DOM Node to insert.
  62    * @param aParent   The node to insert the new object into
  63    * @param aPosition The place in aParent to insert the new node
  64    *                  0=first child, 1=second child, etc.
  65    *                  any number > number of current children = last child
  66    */
  67   void WillInsertNode(in nsIDOMNode aNode,
  68                             in nsIDOMNode aParent,
  69                             in long      aPosition);
  70
  71   /**
  72    * Called after the editor inserts a node.
  73    * @param aNode     The DOM Node to insert.
  74    * @param aParent   The node to insert the new object into
  75    * @param aPosition The place in aParent to insert the new node
  76    *                  0=first child, 1=second child, etc.
  77    *                  any number > number of current children = last child
  78    * @param aResult   The result of the insert node operation.
  79    */
  80   void DidInsertNode(in nsIDOMNode aNode,
  81                            in nsIDOMNode aParent,
  82                            in long      aPosition,
  83                            in nsresult    aResult);
  84
  85   /**
  86    * Called before the editor deletes a node.
  87    * @param aChild    The node to delete
  88    */
  89   void WillDeleteNode(in nsIDOMNode aChild);
  90
  91   /**
  92    * Called after the editor deletes a node.
  93    * @param aChild    The node to delete
  94    * @param aResult   The result of the delete node operation.
  95    */
  96   void DidDeleteNode(in nsIDOMNode aChild, in nsresult aResult);
  97
  98   /**
  99    * Called before the editor splits a node.
 100    * @param aExistingRightNode   the node to split.  It will become the new node's next sibling.
 101    * @param aOffset              the offset of aExistingRightNode's content|children to do the split at
 102    * @param aNewLeftNode         [OUT] the new node resulting from the split, becomes aExistingRightNode's previous sibling.
 103    */
 104   void WillSplitNode(in nsIDOMNode aExistingRightNode,
 105                            in long      aOffset);
 106
 107   /**
 108    * Called after the editor splits a node.
 109    * @param aExistingRightNode   the node to split.  It will become the new node's next sibling.
 110    * @param aOffset              the offset of aExistingRightNode's content|children to do the split at
 111    * @param aNewLeftNode         [OUT] the new node resulting from the split, becomes aExistingRightNode's previous sibling.
 112    */
 113   void DidSplitNode(in nsIDOMNode aExistingRightNode,
 114                           in long      aOffset,
 115                           in nsIDOMNode aNewLeftNode,
 116                           in nsresult    aResult);
 117
 118   /**
 119    * Called before the editor joins 2 nodes.
 120    * @param aLeftNode   This node will be merged into the right node
 121    * @param aRightNode  The node that will be merged into.
 122    *                    There is no requirement that the two nodes be of
 123    *                    the same type.
 124    * @param aParent     The parent of aRightNode
 125    */
 126   void WillJoinNodes(in nsIDOMNode aLeftNode,
 127                            in nsIDOMNode aRightNode,
 128                            in nsIDOMNode aParent);
 129
 130   /**
 131    * Called after the editor joins 2 nodes.
 132    * @param aLeftNode   This node will be merged into the right node
 133    * @param aRightNode  The node that will be merged into.
 134    *                    There is no requirement that the two nodes be of
 135    *                    the same type.
 136    * @param aParent     The parent of aRightNode
 137    * @param aResult     The result of the join operation.
 138    */
 139   void DidJoinNodes(in nsIDOMNode aLeftNode,
 140                           in nsIDOMNode aRightNode,
 141                           in nsIDOMNode aParent,
 142                           in nsresult    aResult);
 143
 144   /**
 145    * Called before the editor inserts text.
 146    * @param aTextNode   This node getting inserted text
 147    * @param aOffset     The offset in aTextNode to insert at.
 148    * @param aString     The string that gets inserted.
 149    */
 150   void WillInsertText(in nsIDOMCharacterData aTextNode,
 151                             in long          aOffset,
 152                             in DOMString     aString);
 153
 154   /**
 155    * Called after the editor inserts text.
 156    * @param aTextNode   This node getting inserted text
 157    * @param aOffset     The offset in aTextNode to insert at.
 158    * @param aString     The string that gets inserted.
 159    * @param aResult     The result of the insert text operation.
 160    */
 161   void DidInsertText(in nsIDOMCharacterData aTextNode,
 162                            in long                aOffset,
 163                            in DOMString           aString,
 164                            in nsresult            aResult);
 165
 166   /**
 167    * Called before the editor deletes text.
 168    * @param aTextNode   This node getting text deleted
 169    * @param aOffset     The offset in aTextNode to delete at.
 170    * @param aLength     The amount of text to delete.
 171    */
 172   void WillDeleteText(in nsIDOMCharacterData aTextNode,
 173                             in long                aOffset,
 174                             in long                aLength);
 175
 176   /**
 177    * Called before the editor deletes text.
 178    * @param aTextNode   This node getting text deleted
 179    * @param aOffset     The offset in aTextNode to delete at.
 180    * @param aLength     The amount of text to delete.
 181    * @param aResult     The result of the delete text operation.
 182    */
 183   void DidDeleteText(in nsIDOMCharacterData aTextNode,
 184                            in long                aOffset,
 185                            in long                aLength,
 186                            in nsresult              aResult);
 187
 188   /**
 189    * Called before the editor deletes the selection.
 190    * @param aSelection   The selection to be deleted
 191    */
 192   void WillDeleteSelection(in nsISelection aSelection);
 193
 194   /**
 195    * Called after the editor deletes the selection.
 196    * @param aSelection   The selection, after deletion
 197    */
 198   void DidDeleteSelection(in nsISelection aSelection);
 199 };