/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #include "nsISupports.idl" #include "nsITransaction.idl" #include "nsITransactionListener.idl" %{C++ namespace mozilla { class TransactionManager; } // namespace mozilla %} /** * The nsITransactionManager interface. *

* This interface is implemented by an object that wants to * manage/track transactions. */ [scriptable, builtinclass, uuid(c77763df-0fb9-41a8-8074-8e882f605755)] interface nsITransactionManager : nsISupports { /** * Calls a transaction's doTransaction() method, then pushes it on the * undo stack. *

* This method calls the transaction's AddRef() method. * The transaction's Release() method will be called when the undo or redo * stack is pruned or when the transaction manager is destroyed. * @param aTransaction the transaction to do. */ [can_run_script] void doTransaction(in nsITransaction aTransaction); /** * Pops the topmost transaction on the undo stack, calls its * undoTransaction() method, then pushes it on the redo stack. */ [can_run_script] void undoTransaction(); /** * Pops the topmost transaction on the redo stack, calls its * redoTransaction() method, then pushes it on the undo stack. */ [can_run_script] void redoTransaction(); /** * Clears the undo and redo stacks. */ void clear(); /** * Clears the undo stack only. */ void clearUndoStack(); /** * Clears the redo stack only. */ void clearRedoStack(); /** * Turns on the transaction manager's batch mode, forcing all transactions * executed by the transaction manager's doTransaction() method to be * aggregated together until EndBatch() is called. This mode allows an * application to execute and group together several independent transactions * so they can be undone with a single call to undoTransaction(). * @param aData An arbitrary nsISupports object that is associated with the * batch. Can be retrieved from the undo or redo stacks. */ [can_run_script] void beginBatch(in nsISupports aData); /** * Turns off the transaction manager's batch mode. * @param aAllowEmpty If true, a batch containing no children will be * pushed onto the undo stack. Otherwise, ending a batch with no * children will result in no transactions being pushed on the undo stack. */ void endBatch(in boolean aAllowEmpty); /** * The number of items on the undo stack. */ readonly attribute long numberOfUndoItems; /** * The number of items on the redo stack. */ readonly attribute long numberOfRedoItems; /** * Sets the maximum number of transaction items the transaction manager will * maintain at any time. This is commonly referred to as the number of levels * of undo. * @param aMaxCount A value of -1 means no limit. A value of zero means the * transaction manager will execute each transaction, then immediately release * all references it has to the transaction without pushing it on the undo * stack. A value greater than zero indicates the max number of transactions * that can exist at any time on both the undo and redo stacks. This method * will prune the necessary number of transactions on the undo and redo * stacks if the value specified is less than the number of items that exist * on both the undo and redo stacks. */ attribute long maxTransactionCount; /** * Combines the transaction at the top of the undo stack (if any) with the * preceding undo transaction (if any) into a batch transaction. Thus, * a call to undoTransaction() will undo both transactions. */ void batchTopUndo(); /** * Removes the transaction at the top of the undo stack (if any) without * transacting. */ void removeTopUndo(); /** * Returns an AddRef'd pointer to the transaction at the top of the * undo stack. Callers should be aware that this method could return * return a null in some implementations if there is a batch at the top * of the undo stack. */ nsITransaction peekUndoStack(); /** * Returns an AddRef'd pointer to the transaction at the top of the * redo stack. Callers should be aware that this method could return * return a null in some implementations if there is a batch at the top * of the redo stack. */ nsITransaction peekRedoStack(); /** * Adds a listener to the transaction manager's notification list. Listeners * are notified whenever a transaction is done, undone, or redone. *

* The listener's AddRef() method is called. * @param aListener the lister to add. */ void AddListener(in nsITransactionListener aListener); /** * Removes a listener from the transaction manager's notification list. *

* The listener's Release() method is called. * @param aListener the lister to remove. */ void RemoveListener(in nsITransactionListener aListener); %{C++ /** * AsTransactionManager() returns a pointer to TransactionManager class. * * In order to avoid circular dependency issues, this method is defined * in mozilla/TransactionManager.h. Consumers need to #include that header. */ inline mozilla::TransactionManager* AsTransactionManager(); %} };