Audacity  3.0.3
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 <vector>
53 #include <wx/event.h> // to declare custom event types
54 #include "ClientData.h"
55 #include "SelectedRegion.h"
56 
57 // Events emitted by AudacityProject for the use of listeners
58 
59 // Project state did not change, but a new state was copied into Undo history
60 // and any redo states were lost
61 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_PUSHED, wxCommandEvent);
62 
63 // Project state did not change, but current state was modified in Undo history
64 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_MODIFIED, wxCommandEvent);
65 
66 // Project state did not change, but current state was renamed in Undo history
67 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_RENAMED, wxCommandEvent);
68 
69 // Project state changed because of undo or redo; undo manager
70 // contents did not change other than the pointer to current state
71 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_OR_REDO, wxCommandEvent);
72 
73 // Project state changed other than for single-step undo/redo; undo manager
74 // contents did not change other than the pointer to current state
75 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_RESET, wxCommandEvent);
76 
77 // Undo or redo states discarded
78 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_PURGE, wxCommandEvent);
79 
80 class AudacityProject;
81 class Tags;
82 class Track;
83 class TrackList;
84 
85 struct UndoState {
86  UndoState(std::shared_ptr<TrackList> &&tracks_,
87  const std::shared_ptr<Tags> &tags_,
88  const SelectedRegion &selectedRegion_)
89  : tracks(std::move(tracks_)), tags(tags_), selectedRegion(selectedRegion_)
90  {}
91 
92  std::shared_ptr<TrackList> tracks;
93  std::shared_ptr<Tags> tags;
95 };
96 
97 struct UndoStackElem {
98 
99  UndoStackElem(std::shared_ptr<TrackList> &&tracks_,
100  const TranslatableString &description_,
101  const TranslatableString &shortDescription_,
102  const SelectedRegion &selectedRegion_,
103  const std::shared_ptr<Tags> &tags_)
104  : state(std::move(tracks_), tags_, selectedRegion_)
105  , description(description_)
106  , shortDescription(shortDescription_)
107  {
108  }
109 
113 };
114 
115 using UndoStack = std::vector <std::unique_ptr<UndoStackElem>>;
116 
117 using SpaceArray = std::vector <unsigned long long> ;
118 
119 // These flags control what extra to do on a PushState
120 // Default is AUTOSAVE
121 // Frequent/faster actions use CONSOLIDATE
122 enum class UndoPush : unsigned char {
123  NONE = 0,
124  CONSOLIDATE = 1 << 0,
125  NOAUTOSAVE = 1 << 1
126 };
127 
129 { return static_cast<UndoPush>(static_cast<int>(a) | static_cast<int>(b)); }
131 { return static_cast<UndoPush>(static_cast<int>(a) & static_cast<int>(b)); }
132 
134 
135 class AUDACITY_DLL_API UndoManager final
136  : public ClientData::Base
137 {
138  public:
139  static UndoManager &Get( AudacityProject &project );
140  static const UndoManager &Get( const AudacityProject &project );
141 
142  explicit
143  UndoManager( AudacityProject &project );
144  ~UndoManager();
145 
146  UndoManager( const UndoManager& ) = delete;
147  UndoManager& operator = ( const UndoManager& ) = delete;
148 
149  void PushState(const TrackList * l,
150  const SelectedRegion &selectedRegion,
151  const std::shared_ptr<Tags> &tags,
152  const TranslatableString &longDescription,
153  const TranslatableString &shortDescription,
154  UndoPush flags = UndoPush::NONE);
155  void ModifyState(const TrackList * l,
156  const SelectedRegion &selectedRegion, const std::shared_ptr<Tags> &tags);
157  void RenameState( int state,
158  const TranslatableString &longDescription,
159  const TranslatableString &shortDescription);
160  void AbandonRedo();
161  void ClearStates();
162  void RemoveStates(
163  size_t begin,
164  size_t end
165  );
166  unsigned int GetNumStates();
167  unsigned int GetCurrentState();
168 
169  void StopConsolidating() { mayConsolidate = false; }
170 
171  void GetShortDescription(unsigned int n, TranslatableString *desc);
172  // Return value must first be calculated by CalculateSpaceUsage():
173  wxLongLong_t GetLongDescription(
174  unsigned int n, TranslatableString *desc, TranslatableString *size);
175  void SetLongDescription(unsigned int n, const TranslatableString &desc);
176 
177  // These functions accept a callback that uses the state,
178  // and then they send to the project EVT_UNDO_RESET or EVT_UNDO_OR_REDO when
179  // that has finished.
180  using Consumer = std::function< void( const UndoStackElem & ) >;
181  void SetStateTo(unsigned int n, const Consumer &consumer);
182  void Undo(const Consumer &consumer);
183  void Redo(const Consumer &consumer);
184 
186  void VisitStates( const Consumer &consumer, bool newestFirst );
188 
189  void VisitStates(
190  const Consumer &consumer, size_t begin, size_t end );
191 
192  bool UndoAvailable();
193  bool RedoAvailable();
194 
195  bool UnsavedChanges() const;
196  int GetSavedState() const;
197  void StateSaved();
198 
199  // Return value must first be calculated by CalculateSpaceUsage():
200  // The clipboard is global, not specific to this project, but it is
201  // convenient to combine the space usage calculations in one class:
202  wxLongLong_t GetClipboardSpaceUsage() const
203  { return mClipboardSpaceUsage; }
204 
205  void CalculateSpaceUsage();
206 
207  // void Debug(); // currently unused
208 
209  private:
210  size_t EstimateRemovedBlocks(size_t begin, size_t end);
211 
212  void RemoveStateAt(int n);
213 
215 
216  int current;
217  int saved;
219 
221  bool mayConsolidate { false };
222 
224  unsigned long long mClipboardSpaceUsage {};
225 };
226 
227 #endif
size
size_t size
Definition: ffmpeg-2.3.6-single-header.h:412
UndoStackElem::UndoStackElem
UndoStackElem(std::shared_ptr< TrackList > &&tracks_, const TranslatableString &description_, const TranslatableString &shortDescription_, const SelectedRegion &selectedRegion_, const std::shared_ptr< Tags > &tags_)
Definition: UndoManager.h:99
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
UndoState::tracks
std::shared_ptr< TrackList > tracks
Definition: UndoManager.h:92
UndoManager::saved
int saved
Definition: UndoManager.h:217
UndoManager::Consumer
std::function< void(const UndoStackElem &) > Consumer
Definition: UndoManager.h:180
UndoManager::mProject
AudacityProject & mProject
Definition: UndoManager.h:214
UndoManager::lastAction
TranslatableString lastAction
Definition: UndoManager.h:220
Tags
ID3 Tags (for MP3)
Definition: Tags.h:74
TrackList
A flat linked list of tracks supporting Add, Remove, Clear, and Contains, serialization of the list o...
Definition: Track.h:1280
SelectedRegion.h
UndoPush::NONE
@ NONE
UndoStack
std::vector< std::unique_ptr< UndoStackElem > > UndoStack
Definition: UndoManager.h:115
ClientData::Base
A convenient default parameter for class template Site.
Definition: ClientData.h:28
ClientData.h
Utility ClientData::Site to register hooks into a host class that attach client data.
desc
const TranslatableString desc
Definition: ExportPCM.cpp:58
UndoPush::NOAUTOSAVE
@ NOAUTOSAVE
UndoStackElem::shortDescription
TranslatableString shortDescription
Definition: UndoManager.h:112
SpaceArray
std::vector< unsigned long long > SpaceArray
Definition: UndoManager.h:117
UndoManager::UndoManager
UndoManager(const UndoManager &)=delete
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
operator|
UndoPush operator|(UndoPush a, UndoPush b)
Definition: UndoManager.h:128
UndoManager::stack
UndoStack stack
Definition: UndoManager.h:218
UndoStackElem::state
UndoState state
Definition: UndoManager.h:110
UndoPush
UndoPush
Definition: UndoManager.h:122
UndoManager::current
int current
Definition: UndoManager.h:216
UndoManager::GetClipboardSpaceUsage
wxLongLong_t GetClipboardSpaceUsage() const
Definition: UndoManager.h:202
Track
Abstract base class for an object holding data associated with points on a time axis.
Definition: Track.h:239
AudacityProject
The top-level handle to an Audacity project. It serves as a source of events that other objects can b...
Definition: Project.h:92
operator&
UndoPush operator&(UndoPush a, UndoPush b)
Definition: UndoManager.h:130
UndoPush::CONSOLIDATE
@ CONSOLIDATE
UndoState::tags
std::shared_ptr< Tags > tags
Definition: UndoManager.h:93
UndoState
Definition: UndoManager.h:85
wxDECLARE_EXPORTED_EVENT
wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_UNDO_PUSHED, wxCommandEvent)
UndoStackElem::description
TranslatableString description
Definition: UndoManager.h:111
UndoManager
Maintain a non-persistent list of states of the project, to support undo and redo commands.
Definition: UndoManager.h:137
UndoState::selectedRegion
SelectedRegion selectedRegion
Definition: UndoManager.h:94
UndoState::UndoState
UndoState(std::shared_ptr< TrackList > &&tracks_, const std::shared_ptr< Tags > &tags_, const SelectedRegion &selectedRegion_)
Definition: UndoManager.h:86
UndoManager::StopConsolidating
void StopConsolidating()
Definition: UndoManager.h:169
UndoStackElem
Holds one item with description and time range for the UndoManager.
Definition: UndoManager.h:97
UndoManager::space
SpaceArray space
Definition: UndoManager.h:223
SelectedRegion
Defines a selected portion of a project.
Definition: SelectedRegion.h:35