Audacity 3.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.
10
11 If a minor change is made, for example changing the visual
12 display of a track or changing the selection, you can call
13 ModifyState, which replaces the current state with the
14 one you give it, without deleting everything above it.
15
16 Each action has a long description and a short description
17 associated with it. The long description appears in the
18 History window and should be a complete sentence in the
19 past tense, for example, "Deleted 2 seconds.". The short
20 description should be one or two words at most, all
21 capitalized, and should represent the name of the command.
22 It will be appended on the end of the word "Undo" or "Redo",
23 for example the short description of "Deleted 2 seconds."
24 would just be "Delete", resulting in menu titles
25 "Undo Delete" and "Redo Delete".
26
27 UndoManager can also automatically consolidate actions into
28 a single state change. If the "consolidate" argument to
29 PushState is true, then NEW changes may accumulate into the most
30 recent Undo state, if descriptions match and if no Undo or Redo or rollback
31 operation intervened since that state was pushed.
32
33 Undo() temporarily moves down one state.
34 If another PushState is called, the redo information is lost.
35
36 Redo()
37
38 UndoAvailable()
39
40 RedoAvailable()
41
42**********************************************************************/
43
44#ifndef __AUDACITY_UNDOMANAGER__
45#define __AUDACITY_UNDOMANAGER__
46
47#include <functional>
48#include <memory>
49#include <vector>
50#include "ClientData.h"
51#include "Observer.h"
52
54
56 const enum Type {
57 Pushed,
59 Modified,
61 Renamed,
66 Reset,
70
71 // Eagerly sent messages (not waiting for idle time)
75
77 const size_t begin = 0, end = 0;
78};
79
80class AudacityProject;
81
83class PROJECT_HISTORY_API UndoStateExtension {
84public:
86
89
91 virtual bool CanUndoOrRedo(const AudacityProject &project);
92};
93
94class PROJECT_HISTORY_API UndoRedoExtensionRegistry {
95public:
97
98 using Saver =
99 std::function<std::shared_ptr<UndoStateExtension>(AudacityProject&)>;
100
102 struct PROJECT_HISTORY_API Entry {
103 Entry(const Saver &saver);
104 };
105};
106
107struct UndoState {
108 using Extensions = std::vector<std::shared_ptr<UndoStateExtension>>;
109
111 : extensions(std::move(extensions))
112 {}
113
115};
116
118
120 const TranslatableString &description_,
121 const TranslatableString &shortDescription_)
122 : state(std::move(extensions))
123 , description(description_)
124 , shortDescription(shortDescription_)
125 {
126 }
127
131};
132
133using UndoStack = std::vector <std::unique_ptr<UndoStackElem>>;
134
135// These flags control what extra to do on a PushState
136// Default is AUTOSAVE
137// Frequent/faster actions use CONSOLIDATE
138enum class UndoPush : unsigned char {
139 NONE = 0,
140 CONSOLIDATE = 1 << 0,
141 NOAUTOSAVE = 1 << 1
142};
143
145{ return static_cast<UndoPush>(static_cast<int>(a) | static_cast<int>(b)); }
147{ return static_cast<UndoPush>(static_cast<int>(a) & static_cast<int>(b)); }
148
150
151class PROJECT_HISTORY_API UndoManager final
152 : public ClientData::Base
153 , public Observer::Publisher<UndoRedoMessage>
154 , public std::enable_shared_from_this<UndoManager>
155{
156 public:
158 static const UndoManager &Get( const AudacityProject &project );
159
160 explicit
162 ~UndoManager();
163
164 UndoManager( const UndoManager& ) = delete;
165 UndoManager& operator = ( const UndoManager& ) = delete;
166
167 void PushState(const TranslatableString &longDescription,
168 const TranslatableString &shortDescription,
169 UndoPush flags = UndoPush::NONE);
170 void ModifyState();
171 void RenameState( int state,
172 const TranslatableString &longDescription,
173 const TranslatableString &shortDescription);
174 void AbandonRedo();
175 void ClearStates();
176 void RemoveStates(
177 size_t begin,
178 size_t end
179 );
180 unsigned int GetNumStates();
181 unsigned int GetCurrentState();
182
183 void StopConsolidating() { mayConsolidate = false; }
184
185 void GetShortDescription(unsigned int n, TranslatableString *desc);
186 void SetLongDescription(unsigned int n, const TranslatableString &desc);
187
188 // These functions accept a callback that uses the state,
189 // and then they send to the project Reset or UndoOrRedo when
190 // that has finished.
191 using Consumer = std::function< void( const UndoStackElem & ) >;
192 void SetStateTo(unsigned int n, const Consumer &consumer);
193 void Undo(const Consumer &consumer);
194 void Redo(const Consumer &consumer);
195
197 void VisitStates( const Consumer &consumer, bool newestFirst );
199
200 void VisitStates(
201 const Consumer &consumer, size_t begin, size_t end );
202
203 bool UndoAvailable();
204 bool RedoAvailable();
205
206 void MarkUnsaved();
207 bool UnsavedChanges() const;
208 int GetSavedState() const;
209 void StateSaved();
210
211 // void Debug(); // currently unused
212
213 private:
214 bool CheckAvailable(int index);
215
216 void EnqueueMessage(UndoRedoMessage message);
217 void RemoveStateAt(int n);
218
220
222 int saved;
223
225
227 bool mayConsolidate { false };
228};
229
230#endif
Utility ClientData::Site to register hooks into a host class that attach client data.
const auto project
UndoPush operator&(UndoPush a, UndoPush b)
Definition: UndoManager.h:146
UndoPush
Definition: UndoManager.h:138
UndoPush operator|(UndoPush a, UndoPush b)
Definition: UndoManager.h:144
std::vector< std::unique_ptr< UndoStackElem > > UndoStack
Definition: UndoManager.h:133
The top-level handle to an Audacity project. It serves as a source of events that other objects can b...
Definition: Project.h:90
An object that sends messages to an open-ended list of subscribed callbacks.
Definition: Observer.h:108
Holds a msgid for the translation catalog; may also bind format arguments.
Maintain a non-persistent list of states of the project, to support undo and redo commands.
Definition: UndoManager.h:155
AudacityProject & mProject
Definition: UndoManager.h:219
UndoManager(const UndoManager &)=delete
void StopConsolidating()
Definition: UndoManager.h:183
TranslatableString lastAction
Definition: UndoManager.h:226
UndoStack stack
Definition: UndoManager.h:224
std::function< void(const UndoStackElem &) > Consumer
Definition: UndoManager.h:191
std::function< std::shared_ptr< UndoStateExtension >(AudacityProject &)> Saver
Type of function that produces an UndoStateExtension object when saving state of a project.
Definition: UndoManager.h:99
Base class for extra information attached to undo/redo states.
Definition: UndoManager.h:83
virtual void RestoreUndoRedoState(AudacityProject &project)=0
Modify the project when undoing or redoing to some state in history.
virtual ~UndoStateExtension()
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:202
const TranslatableString desc
Definition: ExportPCM.cpp:51
const char * end(const char *str) noexcept
Definition: StringUtils.h:106
const char * begin(const char *str) noexcept
Definition: StringUtils.h:101
STL namespace.
A convenient default parameter for class template Site.
Definition: ClientData.h:29
Typically statically constructed.
Definition: UndoManager.h:102
Type of message published by UndoManager.
Definition: UndoManager.h:55
const size_t end
Definition: UndoManager.h:77
const size_t begin
Only significant for BeginPurge messages.
Definition: UndoManager.h:77
@ EndPurge
End elimination of old undo states.
Definition: UndoManager.h:73
@ Purge
Undo or redo states eliminated.
Definition: UndoManager.h:69
@ BeginPurge
Begin elimination of old undo states.
Definition: UndoManager.h:72
enum UndoRedoMessage::Type type
Holds one item with description and time range for the UndoManager.
Definition: UndoManager.h:117
UndoStackElem(UndoState::Extensions extensions, const TranslatableString &description_, const TranslatableString &shortDescription_)
Definition: UndoManager.h:119
TranslatableString description
Definition: UndoManager.h:129
TranslatableString shortDescription
Definition: UndoManager.h:130
UndoState state
Definition: UndoManager.h:128
std::vector< std::shared_ptr< UndoStateExtension > > Extensions
Definition: UndoManager.h:108
UndoState(Extensions extensions)
Definition: UndoManager.h:110
Extensions extensions
Definition: UndoManager.h:114