editor/idl/nsIEditActionListener.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39 #include "domstubs.idl"
  40
  41 interface nsISelection;
  42
  43
  44 /*
  45 Editor Action Listener interface to outside world
  46 */
  47
  48
  49 /**
  50  * A generic editor action listener interface.
  51  * <P>
  52  * nsIEditActionListener is the interface used by applications wishing to be notified
  53  * when the editor modifies the DOM tree.
  54  *
  55  * Note:  this is the wrong class to implement if you are interested in generic
  56  * change notifications.  For generic notifications, you should implement
  57  * nsIDocumentObserver.
  58  */
  59 [scriptable, uuid(b22907b1-ee93-11d2-8d50-000064657374)]
  60
  61 interface nsIEditActionListener : nsISupports{
  62
  63   /**
  64    * Called before the editor creates a node.
  65    * @param aTag      The tag name of the DOM Node to create.
  66    * @param aParent   The node to insert the new object into
  67    * @param aPosition The place in aParent to insert the new node
  68    *                  0=first child, 1=second child, etc.
  69    *                  any number > number of current children = last child
  70    */
  71   void WillCreateNode(in DOMString aTag,
  72                             in nsIDOMNode   aParent,
  73                             in long aPosition);
  74
  75   /**
  76    * Called after the editor creates a node.
  77    * @param aTag      The tag name of the DOM Node to create.
  78    * @param aNode     The DOM Node that was created.
  79    * @param aParent   The node to insert the new object into
  80    * @param aPosition The place in aParent to insert the new node
  81    *                  0=first child, 1=second child, etc.
  82    *                  any number > number of current children = last child
  83    * @param aResult   The result of the create node operation.
  84    */
  85   void DidCreateNode(in DOMString aTag,
  86                            in nsIDOMNode aNode,
  87                            in nsIDOMNode aParent,
  88                            in long          aPosition,
  89                            in nsresult      aResult);
  90
  91   /**
  92    * Called before the editor inserts a node.
  93    * @param aNode     The DOM Node to insert.
  94    * @param aParent   The node to insert the new object into
  95    * @param aPosition The place in aParent to insert the new node
  96    *                  0=first child, 1=second child, etc.
  97    *                  any number > number of current children = last child
  98    */
  99   void WillInsertNode(in nsIDOMNode aNode,
 100                             in nsIDOMNode aParent,
 101                             in long      aPosition);
 102
 103   /**
 104    * Called after the editor inserts a node.
 105    * @param aNode     The DOM Node to insert.
 106    * @param aParent   The node to insert the new object into
 107    * @param aPosition The place in aParent to insert the new node
 108    *                  0=first child, 1=second child, etc.
 109    *                  any number > number of current children = last child
 110    * @param aResult   The result of the insert node operation.
 111    */
 112   void DidInsertNode(in nsIDOMNode aNode,
 113                            in nsIDOMNode aParent,
 114                            in long      aPosition,
 115                            in nsresult    aResult);
 116
 117   /**
 118    * Called before the editor deletes a node.
 119    * @param aChild    The node to delete
 120    */
 121   void WillDeleteNode(in nsIDOMNode aChild);
 122
 123   /**
 124    * Called after the editor deletes a node.
 125    * @param aChild    The node to delete
 126    * @param aResult   The result of the delete node operation.
 127    */
 128   void DidDeleteNode(in nsIDOMNode aChild, in nsresult aResult);
 129
 130   /**
 131    * Called before the editor splits a node.
 132    * @param aExistingRightNode   the node to split.  It will become the new node's next sibling.
 133    * @param aOffset              the offset of aExistingRightNode's content|children to do the split at
 134    * @param aNewLeftNode         [OUT] the new node resulting from the split, becomes aExistingRightNode's previous sibling.
 135    */
 136   void WillSplitNode(in nsIDOMNode aExistingRightNode,
 137                            in long      aOffset);
 138
 139   /**
 140    * Called after the editor splits a node.
 141    * @param aExistingRightNode   the node to split.  It will become the new node's next sibling.
 142    * @param aOffset              the offset of aExistingRightNode's content|children to do the split at
 143    * @param aNewLeftNode         [OUT] the new node resulting from the split, becomes aExistingRightNode's previous sibling.
 144    */
 145   void DidSplitNode(in nsIDOMNode aExistingRightNode,
 146                           in long      aOffset,
 147                           in nsIDOMNode aNewLeftNode,
 148                           in nsresult    aResult);
 149
 150   /**
 151    * Called before the editor joins 2 nodes.
 152    * @param aLeftNode   This node will be merged into the right node
 153    * @param aRightNode  The node that will be merged into.
 154    *                    There is no requirement that the two nodes be of
 155    *                    the same type.
 156    * @param aParent     The parent of aRightNode
 157    */
 158   void WillJoinNodes(in nsIDOMNode aLeftNode,
 159                            in nsIDOMNode aRightNode,
 160                            in nsIDOMNode aParent);
 161
 162   /**
 163    * Called after the editor joins 2 nodes.
 164    * @param aLeftNode   This node will be merged into the right node
 165    * @param aRightNode  The node that will be merged into.
 166    *                    There is no requirement that the two nodes be of
 167    *                    the same type.
 168    * @param aParent     The parent of aRightNode
 169    * @param aResult     The result of the join operation.
 170    */
 171   void DidJoinNodes(in nsIDOMNode aLeftNode,
 172                           in nsIDOMNode aRightNode,
 173                           in nsIDOMNode aParent,
 174                           in nsresult    aResult);
 175
 176   /**
 177    * Called before the editor inserts text.
 178    * @param aTextNode   This node getting inserted text
 179    * @param aOffset     The offset in aTextNode to insert at.
 180    * @param aString     The string that gets inserted.
 181    */
 182   void WillInsertText(in nsIDOMCharacterData aTextNode,
 183                             in long          aOffset,
 184                             in DOMString     aString);
 185
 186   /**
 187    * Called after the editor inserts text.
 188    * @param aTextNode   This node getting inserted text
 189    * @param aOffset     The offset in aTextNode to insert at.
 190    * @param aString     The string that gets inserted.
 191    * @param aResult     The result of the insert text operation.
 192    */
 193   void DidInsertText(in nsIDOMCharacterData aTextNode,
 194                            in long                aOffset,
 195                            in DOMString           aString,
 196                            in nsresult            aResult);
 197
 198   /**
 199    * Called before the editor deletes text.
 200    * @param aTextNode   This node getting text deleted
 201    * @param aOffset     The offset in aTextNode to delete at.
 202    * @param aLength     The amount of text to delete.
 203    */
 204   void WillDeleteText(in nsIDOMCharacterData aTextNode,
 205                             in long                aOffset,
 206                             in long                aLength);
 207
 208   /**
 209    * Called before the editor deletes text.
 210    * @param aTextNode   This node getting text deleted
 211    * @param aOffset     The offset in aTextNode to delete at.
 212    * @param aLength     The amount of text to delete.
 213    * @param aResult     The result of the delete text operation.
 214    */
 215   void DidDeleteText(in nsIDOMCharacterData aTextNode,
 216                            in long                aOffset,
 217                            in long                aLength,
 218                            in nsresult              aResult);
 219
 220   /**
 221    * Called before the editor deletes the selection.
 222    * @param aSelection   The selection to be deleted
 223    */
 224   void WillDeleteSelection(in nsISelection aSelection);
 225
 226   /**
 227    * Called after the editor deletes the selection.
 228    * @param aSelection   The selection, after deletion
 229    */
 230   void DidDeleteSelection(in nsISelection aSelection);
 231 };