1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/editor/txmgr/idl/nsITransactionManager.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,168 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +#include "nsITransaction.idl"
1.11 +#include "nsITransactionList.idl"
1.12 +#include "nsITransactionListener.idl"
1.13 +
1.14 +%{ C++
1.15 +
1.16 +#define NS_TRANSACTIONMANAGER_CONTRACTID "@mozilla.org/transactionmanager;1"
1.17 +
1.18 +%} C++
1.19 +
1.20 +/**
1.21 + * The nsITransactionManager interface.
1.22 + * <P>
1.23 + * This interface is implemented by an object that wants to
1.24 + * manage/track transactions.
1.25 + */
1.26 +[scriptable, builtinclass, uuid(c77763df-0fb9-41a8-8074-8e882f605755)]
1.27 +interface nsITransactionManager : nsISupports
1.28 +{
1.29 + /**
1.30 + * Calls a transaction's doTransaction() method, then pushes it on the
1.31 + * undo stack.
1.32 + * <P>
1.33 + * This method calls the transaction's AddRef() method.
1.34 + * The transaction's Release() method will be called when the undo or redo
1.35 + * stack is pruned or when the transaction manager is destroyed.
1.36 + * @param aTransaction the transaction to do.
1.37 + */
1.38 + void doTransaction(in nsITransaction aTransaction);
1.39 +
1.40 + /**
1.41 + * Pops the topmost transaction on the undo stack, calls its
1.42 + * undoTransaction() method, then pushes it on the redo stack.
1.43 + */
1.44 + void undoTransaction();
1.45 +
1.46 + /**
1.47 + * Pops the topmost transaction on the redo stack, calls its
1.48 + * redoTransaction() method, then pushes it on the undo stack.
1.49 + */
1.50 + void redoTransaction();
1.51 +
1.52 + /**
1.53 + * Clears the undo and redo stacks.
1.54 + */
1.55 + void clear();
1.56 +
1.57 + /**
1.58 + * Clears the undo stack only.
1.59 + */
1.60 + void clearUndoStack();
1.61 +
1.62 + /**
1.63 + * Clears the redo stack only.
1.64 + */
1.65 + void clearRedoStack();
1.66 +
1.67 + /**
1.68 + * Turns on the transaction manager's batch mode, forcing all transactions
1.69 + * executed by the transaction manager's doTransaction() method to be
1.70 + * aggregated together until EndBatch() is called. This mode allows an
1.71 + * application to execute and group together several independent transactions
1.72 + * so they can be undone with a single call to undoTransaction().
1.73 + * @param aData An arbitrary nsISupports object that is associated with the
1.74 + * batch. Can be retrieved from nsITransactionList.
1.75 + */
1.76 + void beginBatch(in nsISupports aData);
1.77 +
1.78 + /**
1.79 + * Turns off the transaction manager's batch mode.
1.80 + * @param aAllowEmpty If true, a batch containing no children will be
1.81 + * pushed onto the undo stack. Otherwise, ending a batch with no
1.82 + * children will result in no transactions being pushed on the undo stack.
1.83 + */
1.84 + void endBatch(in boolean aAllowEmpty);
1.85 +
1.86 + /**
1.87 + * The number of items on the undo stack.
1.88 + */
1.89 + readonly attribute long numberOfUndoItems;
1.90 +
1.91 + /**
1.92 + * The number of items on the redo stack.
1.93 + */
1.94 + readonly attribute long numberOfRedoItems;
1.95 +
1.96 + /**
1.97 + * Sets the maximum number of transaction items the transaction manager will
1.98 + * maintain at any time. This is commonly referred to as the number of levels
1.99 + * of undo.
1.100 + * @param aMaxCount A value of -1 means no limit. A value of zero means the
1.101 + * transaction manager will execute each transaction, then immediately release
1.102 + * all references it has to the transaction without pushing it on the undo
1.103 + * stack. A value greater than zero indicates the max number of transactions
1.104 + * that can exist at any time on both the undo and redo stacks. This method
1.105 + * will prune the necessary number of transactions on the undo and redo
1.106 + * stacks if the value specified is less than the number of items that exist
1.107 + * on both the undo and redo stacks.
1.108 + */
1.109 + attribute long maxTransactionCount;
1.110 +
1.111 + /**
1.112 + * Combines the transaction at the top of the undo stack (if any) with the
1.113 + * preceding undo transaction (if any) into a batch transaction. Thus,
1.114 + * a call to undoTransaction() will undo both transactions.
1.115 + */
1.116 + void batchTopUndo();
1.117 +
1.118 + /**
1.119 + * Removes the transaction at the top of the undo stack (if any) without
1.120 + * transacting.
1.121 + */
1.122 + void removeTopUndo();
1.123 +
1.124 + /**
1.125 + * Returns an AddRef'd pointer to the transaction at the top of the
1.126 + * undo stack. Callers should be aware that this method could return
1.127 + * return a null in some implementations if there is a batch at the top
1.128 + * of the undo stack.
1.129 + */
1.130 + nsITransaction peekUndoStack();
1.131 +
1.132 + /**
1.133 + * Returns an AddRef'd pointer to the transaction at the top of the
1.134 + * redo stack. Callers should be aware that this method could return
1.135 + * return a null in some implementations if there is a batch at the top
1.136 + * of the redo stack.
1.137 + */
1.138 + nsITransaction peekRedoStack();
1.139 +
1.140 + /**
1.141 + * Returns the list of transactions on the undo stack. Note that the
1.142 + * transaction at the top of the undo stack will actually be at the
1.143 + * index 'n-1' in the list, where 'n' is the number of items in the list.
1.144 + */
1.145 + nsITransactionList getUndoList();
1.146 +
1.147 + /**
1.148 + * Returns the list of transactions on the redo stack. Note that the
1.149 + * transaction at the top of the redo stack will actually be at the
1.150 + * index 'n-1' in the list, where 'n' is the number of items in the list.
1.151 + */
1.152 + nsITransactionList getRedoList();
1.153 +
1.154 + /**
1.155 + * Adds a listener to the transaction manager's notification list. Listeners
1.156 + * are notified whenever a transaction is done, undone, or redone.
1.157 + * <P>
1.158 + * The listener's AddRef() method is called.
1.159 + * @param aListener the lister to add.
1.160 + */
1.161 + void AddListener(in nsITransactionListener aListener);
1.162 +
1.163 + /**
1.164 + * Removes a listener from the transaction manager's notification list.
1.165 + * <P>
1.166 + * The listener's Release() method is called.
1.167 + * @param aListener the lister to remove.
1.168 + */
1.169 + void RemoveListener(in nsITransactionListener aListener);
1.170 +};
1.171 +
