editor/txmgr/idl/nsITransactionManager.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 "nsITransaction.idl"
  40 #include "nsITransactionList.idl"
  41 #include "nsITransactionListener.idl"
  42
  43 %{ C++
  44
  45 #define NS_TRANSACTIONMANAGER_CONTRACTID "@mozilla.org/transactionmanager;1"
  46
  47 %} C++
  48
  49 /**
  50  * The nsITransactionManager interface.
  51  * <P>
  52  * This interface is implemented by an object that wants to
  53  * manage/track transactions.
  54  */
  55 [scriptable, uuid(58e330c2-7b48-11d2-98b9-00805f297d89)]
  56 interface nsITransactionManager : nsISupports
  57 {
  58   /**
  59    * Calls a transaction's doTransaction() method, then pushes it on the
  60    * undo stack.
  61    * <P>
  62    * This method calls the transaction's AddRef() method.
  63    * The transaction's Release() method will be called when the undo or redo
  64    * stack is pruned or when the transaction manager is destroyed.
  65    * @param aTransaction the transaction to do.
  66    */
  67   void doTransaction(in nsITransaction aTransaction);
  68
  69   /**
  70    * Pops the topmost transaction on the undo stack, calls it's
  71    * undoTransaction() method, then pushes it on the redo stack.
  72    */
  73   void undoTransaction();
  74
  75   /**
  76    * Pops the topmost transaction on the redo stack, calls it's
  77    * redoTransaction() method, then pushes it on the undo stack.
  78    */
  79   void redoTransaction();
  80
  81   /**
  82    * Clears the undo and redo stacks.
  83    */
  84   void clear();
  85
  86   /**
  87    * Turns on the transaction manager's batch mode, forcing all transactions
  88    * executed by the transaction manager's doTransaction() method to be
  89    * aggregated together until EndBatch() is called.  This mode allows an
  90    * application to execute and group together several independent transactions
  91    * so they can be undone with a single call to undoTransaction().
  92    */
  93   void beginBatch();
  94
  95   /**
  96    * Turns off the transaction manager's batch mode.
  97    */
  98   void endBatch();
  99
 100   /**
 101    * The number of items on the undo stack.
 102    */
 103   readonly attribute long numberOfUndoItems;
 104
 105   /**
 106    * The number of items on the redo stack.
 107    */
 108   readonly attribute long numberOfRedoItems;
 109
 110   /**
 111    * Sets the maximum number of transaction items the transaction manager will
 112    * maintain at any time. This is commonly referred to as the number of levels
 113    * of undo.
 114    * @param aMaxCount A value of -1 means no limit. A value of zero means the
 115    * transaction manager will execute each transaction, then immediately release
 116    * all references it has to the transaction without pushing it on the undo
 117    * stack. A value greater than zero indicates the max number of transactions
 118    * that can exist at any time on both the undo and redo stacks. This method
 119    * will prune the necessary number of transactions on the undo and redo
 120    * stacks if the value specified is less than the number of items that exist
 121    * on both the undo and redo stacks.
 122    */
 123   attribute long maxTransactionCount;
 124
 125   /**
 126    * Returns an AddRef'd pointer to the transaction at the top of the
 127    * undo stack. Callers should be aware that this method could return
 128    * return a null in some implementations if there is a batch at the top
 129    * of the undo stack.
 130    */
 131   nsITransaction peekUndoStack();
 132
 133   /**
 134    * Returns an AddRef'd pointer to the transaction at the top of the
 135    * redo stack. Callers should be aware that this method could return
 136    * return a null in some implementations if there is a batch at the top
 137    * of the redo stack.
 138    */
 139   nsITransaction peekRedoStack();
 140
 141   /**
 142    * Returns the list of transactions on the undo stack. Note that the
 143    * transaction at the top of the undo stack will actually be at the
 144    * index 'n-1' in the list, where 'n' is the number of items in the list.
 145    */
 146   nsITransactionList getUndoList();
 147
 148   /**
 149    * Returns the list of transactions on the redo stack. Note that the
 150    * transaction at the top of the redo stack will actually be at the
 151    * index 'n-1' in the list, where 'n' is the number of items in the list.
 152    */
 153   nsITransactionList getRedoList();
 154
 155   /**
 156    * Adds a listener to the transaction manager's notification list. Listeners
 157    * are notified whenever a transaction is done, undone, or redone.
 158    * <P>
 159    * The listener's AddRef() method is called.
 160    * @param aListener the lister to add.
 161    */
 162   void AddListener(in nsITransactionListener aListener);
 163
 164   /**
 165    * Removes a listener from the transaction manager's notification list.
 166    * <P>
 167    * The listener's Release() method is called.
 168    * @param aListener the lister to remove.
 169    */
 170   void RemoveListener(in nsITransactionListener aListener);
 171 };
 172