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