summaryrefslogtreecommitdiff
path: root/editor/txmgr/nsITransactionManager.idl
blob: 0587d5ca1d5848f2d8a908aec9824aff04ec124c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/* -*- 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 "nsITransactionList.idl"
#include "nsITransactionListener.idl"

%{ C++

#define NS_TRANSACTIONMANAGER_CONTRACTID "@mozilla.org/transactionmanager;1"

%} C++

/**
 * The nsITransactionManager interface.
 * <P>
 * 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.
   * <P>
   * 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.
   */
  void doTransaction(in nsITransaction aTransaction);

  /**
   * Pops the topmost transaction on the undo stack, calls its
   * undoTransaction() method, then pushes it on the redo stack.
   */
  void undoTransaction();

  /**
   * Pops the topmost transaction on the redo stack, calls its
   * redoTransaction() method, then pushes it on the undo stack.
   */
  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 nsITransactionList.
   */
  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();

  /**
   * Returns the list of transactions on the undo stack. Note that the
   * transaction at the top of the undo stack will actually be at the
   * index 'n-1' in the list, where 'n' is the number of items in the list.
   */
  nsITransactionList getUndoList();

  /**
   * Returns the list of transactions on the redo stack. Note that the
   * transaction at the top of the redo stack will actually be at the
   * index 'n-1' in the list, where 'n' is the number of items in the list.
   */
  nsITransactionList getRedoList();

  /**
   * Adds a listener to the transaction manager's notification list. Listeners
   * are notified whenever a transaction is done, undone, or redone.
   * <P>
   * 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.
   * <P>
   * The listener's Release() method is called.
   * @param aListener the lister to remove.
   */
  void RemoveListener(in nsITransactionListener aListener);
};