nsITransactionManager.idl (4889B)
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 };