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