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 TranslatableString &longDescription, const TranslatableString &shortDescription, UndoPush flags=UndoPush::NONE)

void	ModifyState ()

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 ()

void	MarkUnsaved ()

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
bool	CheckAvailable (int index)

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 151 of file UndoManager.h.

Member Typedef Documentation

◆ Consumer

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

Definition at line 191 of file UndoManager.h.

Constructor & Destructor Documentation

◆ UndoManager() [1/2]

UndoManager::UndoManager ( AudacityProject & project )

explicit

Definition at line 81 of file UndoManager.cpp.

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

References current, and saved.

◆ ~UndoManager()

UndoManager::~UndoManager ( )

Definition at line 88 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 255 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:

◆ CheckAvailable()

bool UndoManager::CheckAvailable ( int index )

private

Definition at line 182 of file UndoManager.cpp.

{
   if (index < 0 || index >= (int)stack.size())
      return false;
   auto &extensions = stack[index]->state.extensions;
   return std::all_of(extensions.begin(), extensions.end(), [&](auto &ext){
      return !ext || ext->CanUndoOrRedo(mProject);
   });
}

References stack.

Referenced by RedoAvailable(), and UndoAvailable().

Here is the caller graph for this function:

◆ ClearStates()

void UndoManager::ClearStates ( )

Definition at line 155 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 122 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 71 of file UndoManager.cpp.

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

References key, and project.

Referenced by MacroCommands::ApplyMacro(), ProjectFileManager::Compact(), ProjectFileManager::CompactProjectOnClose(), anonymous_namespace{RealtimeEffectPanel.cpp}::RealtimeEffectControl::Create(), anonymous_namespace{ClipMenus.cpp}::DoClipLeftOrRight(), ProjectFileManager::DoSave(), EstimateRemovedBlocks(), HistoryDialog::HistoryDialog(), ProjectHistory::InitialState(), ProjectHistory::ModifyState(), CommandManager::ModifyUndoMenuItems(), anonymous_namespace{BatchProcessDialog.cpp}::OnApplyMacroDirectlyByName(), ProjectManager::OnCloseWindow(), EffectUIHost::OnEnable(), anonymous_namespace{EditMenus.cpp}::OnRedo(), anonymous_namespace{TrackMenus.cpp}::OnResample(), anonymous_namespace{TimerRecordDialog.cpp}::OnTimerRecord(), anonymous_namespace{EditMenus.cpp}::OnUndo(), ProjectManager::OpenProject(), ProjectHistory::PushState(), RealtimeEffectPanel::RealtimeEffectPanel(), ProjectHistory::RedoAvailable(), ProjectHistory::RollbackState(), ProjectHistory::SetStateTo(), RealtimeEffectStateUI::Show(), SqliteSampleBlockFactory::SqliteSampleBlockFactory(), TrackPanel::TrackPanel(), and ProjectHistory::UndoAvailable().

Here is the caller graph for this function:

◆ Get() [2/2]

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

static

Definition at line 76 of file UndoManager.cpp.

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

References BasicUI::Get(), and project.

Here is the call graph for this function:

◆ GetCurrentState()

unsigned int UndoManager::GetCurrentState ( )

Definition at line 167 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 162 of file UndoManager.cpp.

{
   return stack.size();
}

References stack.

◆ GetSavedState()

int UndoManager::GetSavedState ( ) const

Definition at line 360 of file UndoManager.cpp.

{
   return saved;
}

References saved.

◆ GetShortDescription()

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

Definition at line 93 of file UndoManager.cpp.

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

References anonymous_namespace{ExportPCM.cpp}::desc, and stack.

◆ MarkUnsaved()

void UndoManager::MarkUnsaved ( )

Definition at line 345 of file UndoManager.cpp.

{
   saved = -1;
}

References saved.

Referenced by anonymous_namespace{RealtimeEffectPanel.cpp}::RealtimeEffectControl::Create(), EffectUIHost::OnEnable(), RealtimeEffectPanel::RealtimeEffectPanel(), and RealtimeEffectStateUI::Show().

Here is the caller graph for this function:

◆ ModifyState()

void UndoManager::ModifyState ( )

Definition at line 192 of file UndoManager.cpp.

{
   if (current == wxNOT_FOUND) {
      return;
   }
 
//   SonifyBeginModifyState();
   auto &state = stack[current]->state;
 
   // Re-create all captured project state
   state.extensions = GetExtensions(mProject);
 
//   SonifyEndModifyState();
 
   EnqueueMessage({ UndoRedoMessage::Modified });
}

References 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 TranslatableString &	longDescription,
		const TranslatableString &	shortDescription,
		UndoPush	flags = `UndoPush::NONE`
	)

Definition at line 222 of file UndoManager.cpp.

{
   if ( (flags & UndoPush::CONSOLIDATE) != UndoPush::NONE &&
       // compare full translations not msgids!
       lastAction.Translation() == longDescription.Translation() &&
       mayConsolidate ) {
      ModifyState();
      // MB: If the "saved" state was modified by ModifyState, reset
      //  it so that UnsavedChanges returns true.
      if (current == saved) {
         saved = -1;
      }
      return;
   }
 
   mayConsolidate = true;
 
   AbandonRedo();
 
   stack.push_back(
      std::make_unique<UndoStackElem>
         (GetExtensions(mProject), longDescription, shortDescription)
   );
 
   current++;
 
   lastAction = longDescription;
 
   EnqueueMessage({ UndoRedoMessage::Pushed });
}

References AbandonRedo(), CONSOLIDATE, 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 291 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 177 of file UndoManager.cpp.

{
   return CheckAvailable(current + 1);
}

References CheckAvailable(), and current.

Referenced by Redo().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RemoveStateAt()

void UndoManager::RemoveStateAt ( int n )

private

Definition at line 110 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 130 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 details::begin(), UndoRedoMessage::BeginPurge, current, details::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 209 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 100 of file UndoManager.cpp.

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

References anonymous_namespace{ExportPCM.cpp}::desc, and stack.

◆ SetStateTo()

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

Definition at line 263 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 355 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 183 of file UndoManager.h.

183{ mayConsolidate = false; }

◆ Undo()

void UndoManager::Undo ( const Consumer & consumer )

Definition at line 277 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 172 of file UndoManager.cpp.

{
   return CheckAvailable(current - 1);
}

References CheckAvailable(), and current.

Referenced by Undo().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UnsavedChanges()

bool UndoManager::UnsavedChanges ( ) const

Definition at line 350 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 318 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 327 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 details::begin(), details::end(), min(), size, and stack.

Here is the call graph for this function:

Member Data Documentation

◆ current

int UndoManager::current

private

Definition at line 221 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 226 of file UndoManager.h.

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

◆ mayConsolidate

bool UndoManager::mayConsolidate { false }

private

Definition at line 227 of file UndoManager.h.

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

◆ mProject

AudacityProject& UndoManager::mProject

private

Definition at line 219 of file UndoManager.h.

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

◆ saved

int UndoManager::saved

private

Definition at line 222 of file UndoManager.h.

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

◆ stack

UndoStack UndoManager::stack

private

Definition at line 224 of file UndoManager.h.

Referenced by AbandonRedo(), CheckAvailable(), ClearStates(), GetNumStates(), GetShortDescription(), ModifyState(), PushState(), Redo(), 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()

◆ CheckAvailable()

◆ ClearStates()

◆ EnqueueMessage()

◆ Get() [1/2]

◆ Get() [2/2]

◆ GetCurrentState()

◆ GetNumStates()

◆ GetSavedState()

◆ GetShortDescription()

◆ MarkUnsaved()

◆ 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