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