Audacity  2.2.0
UndoManager.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  UndoManager.h
6 
7  Dominic Mazzoni
8 
9  After each operation, call UndoManager's PushState, pass it
10  the entire track hierarchy. The UndoManager makes a duplicate
11  of every single track using its Duplicate method, which should
12  increment reference counts. If we were not at the top of
13  the stack when this is called, DELETE above first.
14 
15  If a minor change is made, for example changing the visual
16  display of a track or changing the selection, you can call
17  ModifyState, which replaces the current state with the
18  one you give it, without deleting everything above it.
19 
20  Each action has a long description and a short description
21  associated with it. The long description appears in the
22  History window and should be a complete sentence in the
23  past tense, for example, "Deleted 2 seconds.". The short
24  description should be one or two words at most, all
25  capitalized, and should represent the name of the command.
26  It will be appended on the end of the word "Undo" or "Redo",
27  for example the short description of "Deleted 2 seconds."
28  would just be "Delete", resulting in menu titles
29  "Undo Delete" and "Redo Delete".
30 
31  UndoManager can also automatically consolidate actions into
32  a single state change. If the "consolidate" argument to
33  PushState is true, then NEW changes may accumulate into the most
34  recent Undo state, if descriptions match and if no Undo or Redo or rollback
35  operation intervened since that state was pushed.
36 
37  Undo() temporarily moves down one state and returns the track
38  hierarchy. If another PushState is called, the redo information
39  is lost.
40 
41  Redo()
42 
43  UndoAvailable()
44 
45  RedoAvailable()
46 
47 **********************************************************************/
48 
49 #ifndef __AUDACITY_UNDOMANAGER__
50 #define __AUDACITY_UNDOMANAGER__
51 
52 #include "MemoryX.h"
53 #include <vector>
54 #include <wx/string.h>
55 #include "ondemand/ODTaskThread.h"
56 #include "SelectedRegion.h"
57 
58 class Tags;
59 class Track;
60 class TrackList;
61 
62 struct UndoStackElem;
63 struct UndoState {
64  UndoState(std::shared_ptr<TrackList> &&tracks_,
65  const std::shared_ptr<Tags> &tags_,
66  const SelectedRegion &selectedRegion_)
67  : tracks(std::move(tracks_)), tags(tags_), selectedRegion(selectedRegion_)
68  {}
69 
70  std::shared_ptr<TrackList> tracks;
71  std::shared_ptr<Tags> tags;
73 };
74 
75 using UndoStack = std::vector <movable_ptr<UndoStackElem>>;
76 
77 using SpaceArray = std::vector <unsigned long long> ;
78 
79 // These flags control what extra to do on a PushState
80 // Default is AUTOSAVE
81 // Frequent/faster actions use CONSOLIDATE
82 enum class UndoPush : unsigned char {
83  MINIMAL = 0,
84  CONSOLIDATE = 1 << 0,
85  AUTOSAVE = 1 << 1
86 };
87 
89 { return static_cast<UndoPush>(static_cast<int>(a) | static_cast<int>(b)); }
91 { return static_cast<UndoPush>(static_cast<int>(a) & static_cast<int>(b)); }
92 
93 class AUDACITY_DLL_API UndoManager {
94  public:
95  UndoManager();
96  ~UndoManager();
97 
98  void PushState(const TrackList * l,
99  const SelectedRegion &selectedRegion,
100  const std::shared_ptr<Tags> &tags,
101  const wxString &longDescription, const wxString &shortDescription,
102  UndoPush flags = UndoPush::AUTOSAVE);
103  void ModifyState(const TrackList * l,
104  const SelectedRegion &selectedRegion, const std::shared_ptr<Tags> &tags);
105  void ClearStates();
106  void RemoveStates(int num); // removes the 'num' oldest states
107  void RemoveStateAt(int n); // removes the n'th state (1 is oldest)
108  unsigned int GetNumStates();
109  unsigned int GetCurrentState();
110 
111  void StopConsolidating() { mayConsolidate = false; }
112 
113  void GetShortDescription(unsigned int n, wxString *desc);
114  // Return value must first be calculated by CalculateSpaceUsage():
115  wxLongLong_t GetLongDescription(unsigned int n, wxString *desc, wxString *size);
116  void SetLongDescription(unsigned int n, const wxString &desc);
117 
118  const UndoState &SetStateTo(unsigned int n, SelectedRegion *selectedRegion);
119  const UndoState &Undo(SelectedRegion *selectedRegion);
120  const UndoState &Redo(SelectedRegion *selectedRegion);
121 
122  bool UndoAvailable();
123  bool RedoAvailable();
124 
125  bool UnsavedChanges();
126  void StateSaved();
127 
128  // Return value must first be calculated by CalculateSpaceUsage():
129  // The clipboard is global, not specific to this project, but it is
130  // convenient to combine the space usage calculations in one class:
131  wxLongLong_t GetClipboardSpaceUsage() const
132  { return mClipboardSpaceUsage; }
133 
134  void CalculateSpaceUsage();
135 
136  // void Debug(); // currently unused
137 
139  void SetODChangesFlag();
140  bool HasODChangesFlag();
141  void ResetODChangesFlag();
142 
143  private:
144  int current;
145  int saved;
147 
148  wxString lastAction;
149  bool mayConsolidate { false };
150 
152  unsigned long long mClipboardSpaceUsage {};
153 
155  ODLock mODChangesMutex;//mODChanges is accessed from many threads.
156 
157 };
158 
159 #endif
std::shared_ptr< TrackList > tracks
Definition: UndoManager.h:70
wxLongLong_t GetClipboardSpaceUsage() const
Definition: UndoManager.h:131
A list of TrackListNode items.
Definition: Track.h:532
const wxChar * desc
Definition: ExportPCM.cpp:58
int current
Definition: UndoManager.h:144
UndoState(std::shared_ptr< TrackList > &&tracks_, const std::shared_ptr< Tags > &tags_, const SelectedRegion &selectedRegion_)
Definition: UndoManager.h:64
int saved
Definition: UndoManager.h:145
std::vector< movable_ptr< UndoStackElem >> UndoStack
Definition: UndoManager.h:75
void StopConsolidating()
Definition: UndoManager.h:111
std::shared_ptr< Tags > tags
Definition: UndoManager.h:71
std::vector< unsigned long long > SpaceArray
Definition: UndoManager.h:77
Definition: UndoManager.h:63
Defines a selected portion of a project.
Definition: SelectedRegion.h:37
SpaceArray space
Definition: UndoManager.h:151
UndoPush
Definition: UndoManager.h:82
Fundamental data object of Audacity, placed in the TrackPanel. Classes derived form it include the Wa...
Definition: Track.h:85
bool mODChanges
Definition: UndoManager.h:154
UndoPush operator|(UndoPush a, UndoPush b)
Definition: UndoManager.h:88
ODLock mODChangesMutex
Definition: UndoManager.h:155
ID3 Tags (for MP3)
Definition: Tags.h:76
Definition: ODTaskThread.h:150
wxString lastAction
Definition: UndoManager.h:148
Holds one item with description and time range for the UndoManager.
Definition: UndoManager.cpp:42
SelectedRegion selectedRegion
Definition: UndoManager.h:72
UndoPush operator&(UndoPush a, UndoPush b)
Definition: UndoManager.h:90
Works with HistoryWindow to provide the Undo functionality.
Definition: UndoManager.h:93
UndoStack stack
Definition: UndoManager.h:146