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