Maintain a non-persistent list of states of the project, to support undo and redo commands. More...

#include <UndoManager.h>

Inheritance diagram for UndoManager:

Collaboration diagram for UndoManager:

Public Types
using	Consumer = std::function< void(const UndoStackElem &) >

Public Types inherited from Observer::Publisher< UndoRedoMessage >
using	message_type = UndoRedoMessage

using	CallbackReturn = std::conditional_t< true, void, bool >

using	Callback = std::function< CallbackReturn(const UndoRedoMessage &) >
	Type of functions that can be connected to the Publisher. More...

Public Member Functions
	UndoManager (AudacityProject &project)

	~UndoManager ()

	UndoManager (const UndoManager &)=delete

UndoManager &	operator= (const UndoManager &)=delete

void	PushState (const TrackList &l, const SelectedRegion &selectedRegion, const TranslatableString &longDescription, const TranslatableString &shortDescription, UndoPush flags=UndoPush::NONE)

void	ModifyState (const TrackList &l, const SelectedRegion &selectedRegion)

void	RenameState (int state, const TranslatableString &longDescription, const TranslatableString &shortDescription)

void	AbandonRedo ()

void	ClearStates ()

void	RemoveStates (size_t begin, size_t end)

unsigned int	GetNumStates ()

unsigned int	GetCurrentState ()

void	StopConsolidating ()

void	GetShortDescription (unsigned int n, TranslatableString *desc)

void	SetLongDescription (unsigned int n, const TranslatableString &desc)

void	SetStateTo (unsigned int n, const Consumer &consumer)

void	Undo (const Consumer &consumer)

void	Redo (const Consumer &consumer)

void	VisitStates (const Consumer &consumer, bool newestFirst)
	Give read-only access to all states. More...

void	VisitStates (const Consumer &consumer, size_t begin, size_t end)
	Visit a specified range of states. More...

bool	UndoAvailable ()

bool	RedoAvailable ()

bool	UnsavedChanges () const

int	GetSavedState () const

void	StateSaved ()

Public Member Functions inherited from ClientData::Base
virtual	~Base ()

Public Member Functions inherited from Observer::Publisher< UndoRedoMessage >
	Publisher (ExceptionPolicy *pPolicy=nullptr, Alloc a={})
	Constructor supporting type-erased custom allocation/deletion. More...

	Publisher (Publisher &&)=default

Publisher &	operator= (Publisher &&)=default

Subscription	Subscribe (Callback callback)
	Connect a callback to the Publisher; later-connected are called earlier. More...

Subscription	Subscribe (Object &obj, Return(Object::*callback)(Args...))
	Overload of Subscribe takes an object and pointer-to-member-function. More...

Static Public Member Functions
static UndoManager &	Get (AudacityProject &project)

static const UndoManager &	Get (const AudacityProject &project)

Private Member Functions
void	EnqueueMessage (UndoRedoMessage message)

void	RemoveStateAt (int n)

Private Attributes
AudacityProject &	mProject

int	current

int	saved

UndoStack	stack

TranslatableString	lastAction

bool	mayConsolidate { false }

Additional Inherited Members
Static Public Attributes inherited from Observer::Publisher< UndoRedoMessage >
static constexpr bool	notifies_all

Protected Member Functions inherited from Observer::Publisher< UndoRedoMessage >
CallbackReturn	Publish (const UndoRedoMessage &message)
	Send a message to connected callbacks. More...

Detailed Description

Maintain a non-persistent list of states of the project, to support undo and redo commands.

Works with HistoryDialog to provide the Undo functionality.

The history should be cleared before destruction

Definition at line 163 of file UndoManager.h.

Member Typedef Documentation

◆ Consumer

using UndoManager::Consumer = std::function< void( const UndoStackElem & ) >

Definition at line 206 of file UndoManager.h.

Constructor & Destructor Documentation

◆ UndoManager() [1/2]

UndoManager::UndoManager ( AudacityProject & project )

explicit

Definition at line 77 of file UndoManager.cpp.

   : mProject{ project }
{
   current = -1;
   saved = -1;
}

References current, and saved.

◆ ~UndoManager()

UndoManager::~UndoManager ( )

Definition at line 84 of file UndoManager.cpp.

{
   wxASSERT( stack.empty() );
}

References stack.

◆ UndoManager() [2/2]

UndoManager::UndoManager ( const UndoManager & )

delete

Member Function Documentation

◆ AbandonRedo()

void UndoManager::AbandonRedo ( )

Definition at line 265 of file UndoManager.cpp.

{
   if (saved > current) {
      saved = -1;
   }
   RemoveStates( current + 1, stack.size() );
}

References current, RemoveStates(), saved, and stack.

Referenced by PushState().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ClearStates()

void UndoManager::ClearStates ( )

Definition at line 151 of file UndoManager.cpp.

{
   RemoveStates(0, stack.size());
   current = -1;
   saved = -1;
}

References current, RemoveStates(), saved, and stack.

Referenced by ProjectManager::OnCloseWindow().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ EnqueueMessage()

void UndoManager::EnqueueMessage ( UndoRedoMessage message )

private

Definition at line 118 of file UndoManager.cpp.

{
   BasicUI::CallAfter([wThis = weak_from_this(), message]{
      if (auto pThis = wThis.lock())
         pThis->Publish(message);
   });
}

References BasicUI::CallAfter().

Referenced by ModifyState(), PushState(), Redo(), RemoveStates(), RenameState(), SetStateTo(), and Undo().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Get() [1/2]

UndoManager & UndoManager::Get ( AudacityProject & project )

static

Definition at line 67 of file UndoManager.cpp.

{
   return project.AttachedObjects::Get< UndoManager >( key );
}

References key.

Referenced by MacroCommands::ApplyMacro(), ProjectFileManager::Compact(), ProjectFileManager::CompactProjectOnClose(), anonymous_namespace{ClipMenus.cpp}::DoClipLeftOrRight(), ProjectFileManager::DoSave(), EstimateRemovedBlocks(), ViewActions::Handler::Handler(), HistoryDialog::HistoryDialog(), ProjectHistory::InitialState(), LyricsPanel::LyricsPanel(), MenuManager::MenuManager(), ProjectHistory::ModifyState(), MenuManager::ModifyUndoMenuItems(), PluginActions::Handler::OnApplyMacroDirectlyByName(), ProjectManager::OnCloseWindow(), EditActions::Handler::OnRedo(), TrackActions::Handler::OnResample(), TransportActions::Handler::OnTimerRecord(), EditActions::Handler::OnUndo(), ProjectManager::OpenProject(), ProjectWindow::ProjectWindow(), ProjectHistory::PushState(), ProjectHistory::RedoAvailable(), ProjectHistory::RollbackState(), ProjectHistory::SetStateTo(), SqliteSampleBlockFactory::SqliteSampleBlockFactory(), TrackPanel::TrackPanel(), ProjectHistory::UndoAvailable(), and UnsavedChangesFlag().

Here is the caller graph for this function:

◆ Get() [2/2]

const UndoManager & UndoManager::Get ( const AudacityProject & project )

static

Definition at line 72 of file UndoManager.cpp.

{
   return Get( const_cast< AudacityProject & >( project ) );
}

References BasicUI::Get().

Here is the call graph for this function:

◆ GetCurrentState()

unsigned int UndoManager::GetCurrentState ( )

Definition at line 163 of file UndoManager.cpp.

{
   return current;
}

References current.

Referenced by HistoryDialog::DoUpdate(), and HistoryDialog::Populate().

Here is the caller graph for this function:

◆ GetNumStates()

unsigned int UndoManager::GetNumStates ( )

Definition at line 158 of file UndoManager.cpp.

{
   return stack.size();
}

References stack.

◆ GetSavedState()

int UndoManager::GetSavedState ( ) const

Definition at line 365 of file UndoManager.cpp.

{
   return saved;
}

References saved.

◆ GetShortDescription()

void UndoManager::GetShortDescription	(	unsigned int	n,
		TranslatableString *	desc
	)

Definition at line 89 of file UndoManager.cpp.

{
   wxASSERT(n < stack.size());
 
   *desc = stack[n]->shortDescription;
}

References desc, and stack.

◆ ModifyState()

void UndoManager::ModifyState	(	const TrackList &	l,
		const SelectedRegion &	selectedRegion
	)

Definition at line 178 of file UndoManager.cpp.

{
   if (current == wxNOT_FOUND) {
      return;
   }
 
//   SonifyBeginModifyState();
   // Delete current -- not necessary, but let's reclaim space early
   stack[current]->state.tracks.reset();
 
   // Duplicate
   auto tracksCopy = TrackList::Create( nullptr );
   for (auto t : l) {
      if ( t->GetId() == TrackId{} )
         // Don't copy a pending added track
         continue;
      tracksCopy->Add(t->Duplicate());
   }
 
   // Replace
   stack[current]->state.extensions = GetExtensions(mProject);
   stack[current]->state.tracks = std::move(tracksCopy);
 
   stack[current]->state.selectedRegion = selectedRegion;
//   SonifyEndModifyState();
 
   EnqueueMessage({ UndoRedoMessage::Modified });
}

References TrackList::Create(), current, EnqueueMessage(), anonymous_namespace{UndoManager.cpp}::GetExtensions(), UndoRedoMessage::Modified, mProject, and stack.

Referenced by PushState().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator=()

UndoManager & UndoManager::operator= ( const UndoManager & )

delete

◆ PushState()

void UndoManager::PushState	(	const TrackList &	l,
		const SelectedRegion &	selectedRegion,
		const TranslatableString &	longDescription,
		const TranslatableString &	shortDescription,
		UndoPush	flags = `UndoPush::NONE`
	)

Definition at line 221 of file UndoManager.cpp.

{
   if ( (flags & UndoPush::CONSOLIDATE) != UndoPush::NONE &&
       // compare full translations not msgids!
       lastAction.Translation() == longDescription.Translation() &&
       mayConsolidate ) {
      ModifyState(l, selectedRegion);
      // MB: If the "saved" state was modified by ModifyState, reset
      //  it so that UnsavedChanges returns true.
      if (current == saved) {
         saved = -1;
      }
      return;
   }
 
   auto tracksCopy = TrackList::Create( nullptr );
   for (auto t : l) {
      if ( t->GetId() == TrackId{} )
         // Don't copy a pending added track
         continue;
      tracksCopy->Add(t->Duplicate());
   }
 
   mayConsolidate = true;
 
   AbandonRedo();
 
   stack.push_back(
      std::make_unique<UndoStackElem>
         (GetExtensions(mProject), std::move(tracksCopy),
            longDescription, shortDescription, selectedRegion)
   );
 
   current++;
 
   lastAction = longDescription;
 
   EnqueueMessage({ UndoRedoMessage::Pushed });
}

References AbandonRedo(), CONSOLIDATE, TrackList::Create(), current, EnqueueMessage(), anonymous_namespace{UndoManager.cpp}::GetExtensions(), lastAction, mayConsolidate, ModifyState(), mProject, NONE, UndoRedoMessage::Pushed, saved, stack, and TranslatableString::Translation().

Here is the call graph for this function:

◆ Redo()

void UndoManager::Redo ( const Consumer & consumer )

Definition at line 301 of file UndoManager.cpp.

{
   wxASSERT(RedoAvailable());
 
   current++;
 
   /*
   if (!RedoAvailable()) {
      *sel0 = stack[current]->sel0;
      *sel1 = stack[current]->sel1;
   }
   else {
      current++;
      *sel0 = stack[current]->sel0;
      *sel1 = stack[current]->sel1;
      current--;
   }
   */
 
   lastAction = {};
   mayConsolidate = false;
 
   consumer( *stack[current] );
 
   EnqueueMessage({ UndoRedoMessage::UndoOrRedo });
}

References current, EnqueueMessage(), lastAction, mayConsolidate, RedoAvailable(), stack, and UndoRedoMessage::UndoOrRedo.

Here is the call graph for this function:

◆ RedoAvailable()

bool UndoManager::RedoAvailable ( )

Definition at line 173 of file UndoManager.cpp.

{
   return (current < (int)stack.size() - 1);
}

References current, and stack.

Referenced by Redo().

Here is the caller graph for this function:

◆ RemoveStateAt()

void UndoManager::RemoveStateAt ( int n )

private

Definition at line 106 of file UndoManager.cpp.

{
   // Remove the state from the array first, and destroy it at function exit.
   // Because in case of callbacks from destruction of Sample blocks, there
   // might be a yield to GUI and other events might inspect the undo stack
   // (such as history window update).  Don't expose an inconsistent stack
   // state.
   auto iter = stack.begin() + n;
   auto state = std::move(*iter);
   stack.erase(iter);
}

References stack.

Referenced by RemoveStates().

Here is the caller graph for this function:

◆ RemoveStates()

void UndoManager::RemoveStates	(	size_t	begin,
		size_t	end
	)

Parameters

begin	inclusive start of range
end	exclusive end of range

Definition at line 126 of file UndoManager.cpp.

{
   Publish({ UndoRedoMessage::BeginPurge, begin, end });
   auto cleanup =
      finally([&]{ Publish({ UndoRedoMessage::EndPurge }); });
 
   // Wrap the whole in a savepoint for better performance
   TransactionScope trans{mProject, "DiscardingUndoStates"};
 
   for (size_t ii = begin; ii < end; ++ii) {
      RemoveStateAt(begin);
 
      if (current > begin)
        --current;
      if (saved > static_cast<int>(begin))
        --saved;
   }
 
   // Success, commit the savepoint
   trans.Commit();
   
   if (begin != end)
      EnqueueMessage({ UndoRedoMessage::Purge });
}

References PackedArray::begin(), UndoRedoMessage::BeginPurge, current, PackedArray::end(), UndoRedoMessage::EndPurge, EnqueueMessage(), mProject, Observer::Publisher< UndoRedoMessage >::Publish(), UndoRedoMessage::Purge, RemoveStateAt(), and saved.

Referenced by AbandonRedo(), ClearStates(), and HistoryDialog::OnDiscard().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RenameState()

void UndoManager::RenameState	(	int	state,
		const TranslatableString &	longDescription,
		const TranslatableString &	shortDescription
	)

Definition at line 208 of file UndoManager.cpp.

{
   if (state >= 0 && state < stack.size() ) {
      auto &theState = *stack[state];
      theState.description = longDescription;
      theState.shortDescription = shortDescription;
 
      EnqueueMessage({ UndoRedoMessage::Renamed });
   }
}

References EnqueueMessage(), UndoRedoMessage::Renamed, and stack.

Here is the call graph for this function:

◆ SetLongDescription()

void UndoManager::SetLongDescription	(	unsigned int	n,
		const TranslatableString &	desc
	)

Definition at line 96 of file UndoManager.cpp.

{
   n -= 1;
 
   wxASSERT(n < stack.size());
 
   stack[n]->description = desc;
}

References desc, and stack.

◆ SetStateTo()

void UndoManager::SetStateTo	(	unsigned int	n,
		const Consumer &	consumer
	)

Definition at line 273 of file UndoManager.cpp.

{
   wxASSERT(n < stack.size());
 
   current = n;
 
   lastAction = {};
   mayConsolidate = false;
 
   consumer( *stack[current] );
 
   EnqueueMessage({ UndoRedoMessage::Reset });
}

References current, EnqueueMessage(), lastAction, mayConsolidate, UndoRedoMessage::Reset, and stack.

Here is the call graph for this function:

◆ StateSaved()

void UndoManager::StateSaved ( )

Definition at line 360 of file UndoManager.cpp.

{
   saved = current;
}

References current, and saved.

Referenced by ProjectFileManager::DoSave().

Here is the caller graph for this function:

◆ StopConsolidating()

void UndoManager::StopConsolidating ( )

inline

Definition at line 198 of file UndoManager.h.

198{ mayConsolidate = false; }

◆ Undo()

void UndoManager::Undo ( const Consumer & consumer )

Definition at line 287 of file UndoManager.cpp.

{
   wxASSERT(UndoAvailable());
 
   current--;
 
   lastAction = {};
   mayConsolidate = false;
 
   consumer( *stack[current] );
 
   EnqueueMessage({ UndoRedoMessage::UndoOrRedo });
}

References current, EnqueueMessage(), lastAction, mayConsolidate, stack, UndoAvailable(), and UndoRedoMessage::UndoOrRedo.

Here is the call graph for this function:

◆ UndoAvailable()

bool UndoManager::UndoAvailable ( )

Definition at line 168 of file UndoManager.cpp.

{
   return (current > 0);
}

References current.

Referenced by Undo().

Here is the caller graph for this function:

◆ UnsavedChanges()

bool UndoManager::UnsavedChanges ( ) const

Definition at line 355 of file UndoManager.cpp.

{
   return (saved != current);
}

References current, and saved.

Referenced by ProjectFileManager::CompactProjectOnClose().

Here is the caller graph for this function:

◆ VisitStates() [1/2]

void UndoManager::VisitStates	(	const Consumer &	consumer,
		bool	newestFirst
	)

Give read-only access to all states.

Definition at line 328 of file UndoManager.cpp.

{
   auto fn = [&]( decltype(stack[0]) &ptr ){ consumer( *ptr ); };
   if (newestFirst)
      std::for_each(stack.rbegin(), stack.rend(), fn);
   else
      std::for_each(stack.begin(), stack.end(), fn);
}

References fn, and stack.

Referenced by HistoryDialog::DoUpdate().

Here is the caller graph for this function:

◆ VisitStates() [2/2]

void UndoManager::VisitStates	(	const Consumer &	consumer,
		size_t	begin,
		size_t	end
	)

Visit a specified range of states.

end is exclusive; visit newer states first if end < begin

Definition at line 337 of file UndoManager.cpp.

{
   auto size = stack.size();
   if (begin < end) {
      end = std::min(end, size);
      for (auto ii = begin; ii < end; ++ii)
         consumer(*stack[ii]);
   }
   else {
      if (size == 0)
         return;
      begin = std::min(begin, size - 1);
      for (auto ii = begin; ii > end; --ii)
         consumer(*stack[ii]);
   }
}

References PackedArray::begin(), PackedArray::end(), min(), size, and stack.

Here is the call graph for this function:

Member Data Documentation

◆ current

int UndoManager::current

private

Definition at line 233 of file UndoManager.h.

Referenced by AbandonRedo(), ClearStates(), GetCurrentState(), ModifyState(), PushState(), Redo(), RedoAvailable(), RemoveStates(), SetStateTo(), StateSaved(), Undo(), UndoAvailable(), UndoManager(), and UnsavedChanges().

◆ lastAction

TranslatableString UndoManager::lastAction

private

Definition at line 239 of file UndoManager.h.

Referenced by PushState(), Redo(), SetStateTo(), and Undo().

◆ mayConsolidate

bool UndoManager::mayConsolidate { false }

private

Definition at line 240 of file UndoManager.h.

Referenced by PushState(), Redo(), SetStateTo(), and Undo().

◆ mProject

AudacityProject& UndoManager::mProject

private

Definition at line 231 of file UndoManager.h.

Referenced by ModifyState(), PushState(), and RemoveStates().

◆ saved

int UndoManager::saved

private

Definition at line 234 of file UndoManager.h.

Referenced by AbandonRedo(), ClearStates(), GetSavedState(), PushState(), RemoveStates(), StateSaved(), UndoManager(), and UnsavedChanges().

◆ stack

UndoStack UndoManager::stack

private

Invariant: each state holds a non-null pointer to TrackList

Definition at line 237 of file UndoManager.h.

Referenced by AbandonRedo(), ClearStates(), GetNumStates(), GetShortDescription(), ModifyState(), PushState(), Redo(), RedoAvailable(), RemoveStateAt(), RenameState(), SetLongDescription(), SetStateTo(), Undo(), VisitStates(), and ~UndoManager().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Consumer

Constructor & Destructor Documentation

◆ UndoManager() [1/2]

◆ ~UndoManager()

◆ UndoManager() [2/2]

Member Function Documentation

◆ AbandonRedo()

◆ ClearStates()

◆ EnqueueMessage()

◆ Get() [1/2]

◆ Get() [2/2]

◆ GetCurrentState()

◆ GetNumStates()

◆ GetSavedState()

◆ GetShortDescription()

◆ ModifyState()

◆ operator=()

◆ PushState()

◆ Redo()

◆ RedoAvailable()

◆ RemoveStateAt()

◆ RemoveStates()

◆ RenameState()

◆ SetLongDescription()

◆ SetStateTo()

◆ StateSaved()

◆ StopConsolidating()

◆ Undo()

◆ UndoAvailable()

◆ UnsavedChanges()

◆ VisitStates() [1/2]

◆ VisitStates() [2/2]

Member Data Documentation

◆ current

◆ lastAction

◆ mayConsolidate

◆ mProject

◆ saved

◆ stack