OpenShot Library | libopenshot-audio  0.1.9
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 
31 namespace 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 {
58 public:
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 
253 private:
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 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:42
Holds a list of ChangeListeners, and sends messages to them when instructed.
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59
Used by the UndoManager class to store an action which can be done and undone.
Manages a list of undo/redo commands.
An array designed for holding objects.
Holds an absolute date and time.
Definition: juce_Time.h:40