OpenShot Library | OpenShotAudio 0.2.2
juce_UndoManager.h
1
2/** @weakgroup juce_data_structures-undomanager
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 By using JUCE, you agree to the terms of both the JUCE 5 End-User License
15 Agreement and JUCE 5 Privacy Policy (both updated and effective as of the
16 27th April 2017).
17
18 End User License Agreement: www.juce.com/juce-5-licence
19 Privacy Policy: www.juce.com/juce-5-privacy-policy
20
21 Or: You may also use this code under the terms of the GPL v3 (see
22 www.gnu.org/licenses).
23
24 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
25 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
26 DISCLAIMED.
27
28 ==============================================================================
29*/
30
31namespace juce
32{
33
34//==============================================================================
35/**
36 Manages a list of undo/redo commands.
37
38 An UndoManager object keeps a list of past actions and can use these actions
39 to move backwards and forwards through an undo history.
40
41 To use it, create subclasses of UndoableAction which perform all the
42 actions you need, then when you need to actually perform an action, create one
43 and pass it to the UndoManager's perform() method.
44
45 The manager also uses the concept of 'transactions' to group the actions
46 together - all actions performed between calls to beginNewTransaction() are
47 grouped together and are all undone/redone as a group.
48
49 The UndoManager is a ChangeBroadcaster, so listeners can register to be told
50 when actions are performed or undone.
51
52 @see UndoableAction
53
54 @tags{DataStructures}
55*/
57{
58public:
59 //==============================================================================
60 /** Creates an UndoManager.
61
62 @param maxNumberOfUnitsToKeep each UndoableAction object returns a value
63 to indicate how much storage it takes up
64 (UndoableAction::getSizeInUnits()), so this
65 lets you specify the maximum total number of
66 units that the undomanager is allowed to
67 keep in memory before letting the older actions
68 drop off the end of the list.
69 @param minimumTransactionsToKeep this specifies the minimum number of transactions
70 that will be kept, even if this involves exceeding
71 the amount of space specified in maxNumberOfUnitsToKeep
72 */
73 UndoManager (int maxNumberOfUnitsToKeep = 30000,
74 int minimumTransactionsToKeep = 30);
75
76 /** Destructor. */
77 ~UndoManager() override;
78
79 //==============================================================================
80 /** Deletes all stored actions in the list. */
81 void clearUndoHistory();
82
83 /** Returns the current amount of space to use for storing UndoableAction objects.
84 @see setMaxNumberOfStoredUnits
85 */
86 int getNumberOfUnitsTakenUpByStoredCommands() const;
87
88 /** Sets the amount of space that can be used for storing UndoableAction objects.
89
90 @param maxNumberOfUnitsToKeep each UndoableAction object returns a value
91 to indicate how much storage it takes up
92 (UndoableAction::getSizeInUnits()), so this
93 lets you specify the maximum total number of
94 units that the undomanager is allowed to
95 keep in memory before letting the older actions
96 drop off the end of the list.
97 @param minimumTransactionsToKeep this specifies the minimum number of transactions
98 that will be kept, even if this involves exceeding
99 the amount of space specified in maxNumberOfUnitsToKeep
100 @see getNumberOfUnitsTakenUpByStoredCommands
101 */
102 void setMaxNumberOfStoredUnits (int maxNumberOfUnitsToKeep,
103 int minimumTransactionsToKeep);
104
105 //==============================================================================
106 /** Performs an action and adds it to the undo history list.
107
108 @param action the action to perform - this object will be deleted by
109 the UndoManager when no longer needed
110 @returns true if the command succeeds - see UndoableAction::perform
111 @see beginNewTransaction
112 */
113 bool perform (UndoableAction* action);
114
115 /** Performs an action and also gives it a name.
116
117 @param action the action to perform - this object will be deleted by
118 the UndoManager when no longer needed
119 @param actionName if this string is non-empty, the current transaction will be
120 given this name; if it's empty, the current transaction name will
121 be left unchanged. See setCurrentTransactionName()
122 @returns true if the command succeeds - see UndoableAction::perform
123 @see beginNewTransaction
124 */
125 bool perform (UndoableAction* action, const String& actionName);
126
127 /** Starts a new group of actions that together will be treated as a single transaction.
128
129 All actions that are passed to the perform() method between calls to this
130 method are grouped together and undone/redone together by a single call to
131 undo() or redo().
132 */
133 void beginNewTransaction();
134
135 /** Starts a new group of actions that together will be treated as a single transaction.
136
137 All actions that are passed to the perform() method between calls to this
138 method are grouped together and undone/redone together by a single call to
139 undo() or redo().
140
141 @param actionName a description of the transaction that is about to be
142 performed
143 */
144 void beginNewTransaction (const String& actionName);
145
146 /** Changes the name stored for the current transaction.
147
148 Each transaction is given a name when the beginNewTransaction() method is
149 called, but this can be used to change that name without starting a new
150 transaction.
151 */
152 void setCurrentTransactionName (const String& newName);
153
154 /** Returns the name of the current transaction.
155 @see setCurrentTransactionName
156 */
157 String getCurrentTransactionName() const;
158
159 //==============================================================================
160 /** Returns true if there's at least one action in the list to undo.
161 @see getUndoDescription, undo, canRedo
162 */
163 bool canUndo() const;
164
165 /** Tries to roll-back the last transaction.
166 @returns true if the transaction can be undone, and false if it fails, or
167 if there aren't any transactions to undo
168 @see undoCurrentTransactionOnly
169 */
170 bool undo();
171
172 /** Tries to roll-back any actions that were added to the current transaction.
173
174 This will perform an undo() only if there are some actions in the undo list
175 that were added after the last call to beginNewTransaction().
176
177 This is useful because it lets you call beginNewTransaction(), then
178 perform an operation which may or may not actually perform some actions, and
179 then call this method to get rid of any actions that might have been done
180 without it rolling back the previous transaction if nothing was actually
181 done.
182
183 @returns true if any actions were undone.
184 */
185 bool undoCurrentTransactionOnly();
186
187 /** Returns the name of the transaction that will be rolled-back when undo() is called.
188 @see undo, canUndo, getUndoDescriptions
189 */
190 String getUndoDescription() const;
191
192 /** Returns the names of the sequence of transactions that will be performed if undo()
193 is repeatedly called. Note that for transactions where no name was provided, the
194 corresponding string will be empty.
195 @see undo, canUndo, getUndoDescription
196 */
197 StringArray getUndoDescriptions() const;
198
199 /** Returns the time to which the state would be restored if undo() was to be called.
200 If an undo isn't currently possible, it'll return Time().
201 */
202 Time getTimeOfUndoTransaction() const;
203
204 /** Returns a list of the UndoableAction objects that have been performed during the
205 transaction that is currently open.
206
207 Effectively, this is the list of actions that would be undone if undoCurrentTransactionOnly()
208 were to be called now.
209
210 The first item in the list is the earliest action performed.
211 */
212 void getActionsInCurrentTransaction (Array<const UndoableAction*>& actionsFound) const;
213
214 /** Returns the number of UndoableAction objects that have been performed during the
215 transaction that is currently open.
216 @see getActionsInCurrentTransaction
217 */
218 int getNumActionsInCurrentTransaction() const;
219
220 //==============================================================================
221 /** Returns true if there's at least one action in the list to redo.
222 @see getRedoDescription, redo, canUndo
223 */
224 bool canRedo() const;
225
226 /** Tries to redo the last transaction that was undone.
227 @returns true if the transaction can be redone, and false if it fails, or
228 if there aren't any transactions to redo
229 */
230 bool redo();
231
232 /** Returns the name of the transaction that will be redone when redo() is called.
233 @see redo, canRedo, getRedoDescriptions
234 */
235 String getRedoDescription() const;
236
237 /** Returns the names of the sequence of transactions that will be performed if redo()
238 is repeatedly called. Note that for transactions where no name was provided, the
239 corresponding string will be empty.
240 @see redo, canRedo, getRedoDescription
241 */
242 StringArray getRedoDescriptions() const;
243
244 /** Returns the time to which the state would be restored if redo() was to be called.
245 If a redo isn't currently possible, it'll return Time::getCurrentTime().
246 @see redo, canRedo
247 */
248 Time getTimeOfRedoTransaction() const;
249
250 /** Returns true if the caller code is in the middle of an undo or redo action. */
251 bool isPerformingUndoRedo() const;
252
253private:
254 //==============================================================================
255 struct ActionSet;
256 OwnedArray<ActionSet> transactions, stashedFutureTransactions;
257 String newTransactionName;
258 int totalUnitsStored = 0, maxNumUnitsToKeep = 0, minimumTransactionsToKeep = 0, nextIndex = 0;
259 bool newTransaction = true, isInsideUndoRedoCall = false;
260 ActionSet* getCurrentSet() const;
261 ActionSet* getNextSet() const;
262 void moveFutureTransactionsToStash();
263 void restoreStashedFutureTransactions();
264 void dropOldTransactionsIfTooLarge();
265
266 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (UndoManager)
267};
268
269} // namespace juce
270
271/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:60
Holds a list of ChangeListeners, and sends messages to them when instructed.
An array designed for holding objects.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:43
Holds an absolute date and time.
Definition: juce_Time.h:41
Manages a list of undo/redo commands.
Used by the UndoManager class to store an action which can be done and undone.
#define JUCE_API
This macro is added to all JUCE public class declarations.