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