UndoManager Class Reference

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 Member Functions
	UndoManager (AudacityProject &project)
	~UndoManager ()
	UndoManager (const UndoManager &)=delete
UndoManager &	operator= (const UndoManager &)=delete
void	PushState (const TrackList *l, const SelectedRegion &selectedRegion, const std::shared_ptr< Tags > &tags, const TranslatableString &longDescription, const TranslatableString &shortDescription, UndoPush flags=UndoPush::NONE)
void	ModifyState (const TrackList *l, const SelectedRegion &selectedRegion, const std::shared_ptr< Tags > &tags)
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)
wxLongLong_t	GetLongDescription (unsigned int n, TranslatableString *desc, TranslatableString *size)
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 ()
wxLongLong_t	GetClipboardSpaceUsage () const
void	CalculateSpaceUsage ()
Public Member Functions inherited from ClientData::Base
virtual	~Base ()

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

Private Member Functions
size_t	EstimateRemovedBlocks (size_t begin, size_t end)
	Just to find a denominator for a progress indicator. More...
void	RemoveStateAt (int n)

Private Attributes
AudacityProject &	mProject
int	current
int	saved
UndoStack	stack
TranslatableString	lastAction
bool	mayConsolidate { false }
SpaceArray	space
unsigned long long	mClipboardSpaceUsage {}

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

Member Typedef Documentation

Consumer

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

Definition at line 180 of file UndoManager.h.

Constructor & Destructor Documentation

UndoManager() [1/2]

UndoManager::UndoManager ( AudacityProject &  project )

explicit

Definition at line 67 of file UndoManager.cpp.

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

~UndoManager()

UndoManager::~UndoManager

(

)

Definition at line 74 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 370 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:

CalculateSpaceUsage()

void UndoManager::CalculateSpaceUsage

(

)

Definition at line 94 of file UndoManager.cpp.

{
   space.clear();
   space.resize(stack.size(), 0);
 
   SampleBlockIDSet seen;
 
   // After copies and pastes, a block file may be used in more than
   // one place in one undo history state, and it may be used in more than
   // one undo history state.  It might even be used in two states, but not
   // in another state that is between them -- as when you have state A,
   // then make a cut to get state B, but then paste it back into state C.
 
   // So be sure to count each block file once only, in the last undo item that
   // contains it.
 
   // Why the last and not the first? Because the user of the History dialog
   // may DELETE undo states, oldest first.  To reclaim disk space you must
   // DELETE all states containing the block file.  So the block file's
   // contribution to space usage should be counted only in that latest state.
 
   for (size_t nn = stack.size(); nn--;)
   {
      // Scan all tracks at current level
      auto &tracks = *stack[nn]->state.tracks;
      space[nn] = CalculateUsage(tracks, seen);
   }
 
   // Count the usage of the clipboard separately, using another set.  Do not
   // multiple-count any block occurring multiple times within the clipboard.
   seen.clear();
   mClipboardSpaceUsage = CalculateUsage(
      Clipboard::Get().GetTracks(), seen);
 
   //TIMER_STOP( space_calc );
}

References anonymous_namespace{UndoManager.cpp}::CalculateUsage(), Clipboard::Get(), mClipboardSpaceUsage, space, and stack.

Referenced by HistoryDialog::DoUpdate().

Here is the call graph for this function:

Here is the caller graph for this function:

ClearStates()

void UndoManager::ClearStates

(

)

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

EstimateRemovedBlocks()

size_t UndoManager::EstimateRemovedBlocks ( size_t  begin, size_t  end  )

private

Just to find a denominator for a progress indicator.

This estimate procedure should in fact be exact

Definition at line 176 of file UndoManager.cpp.

{
   if (begin == end)
      return 0;
 
   // Collect ids that survive
   SampleBlockIDSet wontDelete;
   auto f = [&](const auto &p){
      InspectBlocks(*p->state.tracks, {}, &wontDelete);
   };
   auto first = stack.begin(), last = stack.end();
   std::for_each( first, first + begin, f );
   std::for_each( first + end, last, f );
   if (saved >= 0)
      std::for_each( first + saved, first + saved + 1, f );
   InspectBlocks(TrackList::Get(mProject), {}, &wontDelete);
 
   // Collect ids that won't survive (and are not negative pseudo ids)
   SampleBlockIDSet seen, mayDelete;
   std::for_each( first + begin, first + end, [&](const auto &p){
      auto &tracks = *p->state.tracks;
      InspectBlocks(tracks, [&]( const SampleBlock &block ){
         auto id = block.GetBlockID();
         if ( id > 0 && !wontDelete.count( id ) )
            mayDelete.insert( id );
      },
      &seen);
   } );
   return mayDelete.size();
}

References TrackList::Get(), SampleBlock::GetBlockID(), InspectBlocks(), mProject, saved, and stack.

Referenced by RemoveStates().

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 57 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(), Get(), ProjectHistory::InitialState(), ProjectHistory::ModifyState(), MenuManager::ModifyUndoMenuItems(), PluginActions::Handler::OnApplyMacroDirectlyByName(), ProjectManager::OnCloseWindow(), EditActions::Handler::OnRedo(), TrackActions::Handler::OnResample(), TransportActions::Handler::OnTimerRecord(), EditActions::Handler::OnUndo(), ProjectManager::OpenProject(), ProjectHistory::PushState(), ProjectHistory::RedoAvailable(), ProjectHistory::RollbackState(), ProjectHistory::SetStateTo(), 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 62 of file UndoManager.cpp.

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

References Get().

Here is the call graph for this function:

GetClipboardSpaceUsage()

wxLongLong_t UndoManager::GetClipboardSpaceUsage ( ) const

inline

Definition at line 202 of file UndoManager.h.

   { return mClipboardSpaceUsage; }

Referenced by HistoryDialog::DoUpdate().

Here is the caller graph for this function:

GetCurrentState()

unsigned int UndoManager::GetCurrentState

(

)

Definition at line 261 of file UndoManager.cpp.

{
   return current;
}

References current.

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

Here is the caller graph for this function:

GetLongDescription()

wxLongLong_t UndoManager::GetLongDescription	(	unsigned int	n,
		TranslatableString *	desc,
		TranslatableString *	size
	)

Definition at line 131 of file UndoManager.cpp.

{
   wxASSERT(n < stack.size());
   wxASSERT(space.size() == stack.size());
 
   *desc = stack[n]->description;
 
   *size = Internat::FormatSize(space[n]);
 
   return space[n];
}

References desc, Internat::FormatSize(), size, space, and stack.

Referenced by HistoryDialog::DoUpdate().

Here is the call graph for this function:

Here is the caller graph for this function:

GetNumStates()

unsigned int UndoManager::GetNumStates

(

)

Definition at line 256 of file UndoManager.cpp.

{
   return stack.size();
}

References stack.

Referenced by HistoryDialog::DoUpdate().

Here is the caller graph for this function:

GetSavedState()

int UndoManager::GetSavedState

(

)

const

Definition at line 473 of file UndoManager.cpp.

{
   return saved;
}

References saved.

GetShortDescription()

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

Definition at line 144 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,
		const std::shared_ptr< Tags > &	tags
	)

Definition at line 276 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.tracks = std::move(tracksCopy);
   stack[current]->state.tags = tags;
 
   stack[current]->state.selectedRegion = selectedRegion;
//   SonifyEndModifyState();
 
   // wxWidgets will own the event object
   mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_MODIFIED } );
}

References TrackList::Create(), current, mProject, safenew, 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 std::shared_ptr< Tags > &	tags,
		const TranslatableString &	longDescription,
		const TranslatableString &	shortDescription,
		UndoPush	flags = UndoPush::NONE
	)

Definition at line 322 of file UndoManager.cpp.

{
   if ( (flags & UndoPush::CONSOLIDATE) != UndoPush::NONE &&
       // compare full translations not msgids!
       lastAction.Translation() == longDescription.Translation() &&
       mayConsolidate ) {
      ModifyState(l, selectedRegion, tags);
      // 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();
 
   // Assume tags was duplicated before any changes.
   // Just save a NEW shared_ptr to it.
   stack.push_back(
      std::make_unique<UndoStackElem>
         (std::move(tracksCopy),
            longDescription, shortDescription, selectedRegion, tags)
   );
 
   current++;
 
   lastAction = longDescription;
 
   // wxWidgets will own the event object
   mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_PUSHED } );
}

References AbandonRedo(), CONSOLIDATE, TrackList::Create(), current, lastAction, mayConsolidate, ModifyState(), mProject, NONE, safenew, saved, stack, and TranslatableString::Translation().

Here is the call graph for this function:

Redo()

void UndoManager::Redo

(

const Consumer &

consumer

)

Definition at line 408 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] );
 
   // wxWidgets will own the event object
   mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_OR_REDO } );
}

References current, lastAction, mayConsolidate, mProject, RedoAvailable(), safenew, and stack.

Here is the call graph for this function:

RedoAvailable()

bool UndoManager::RedoAvailable

(

)

Definition at line 271 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 161 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 207 of file UndoManager.cpp.

{
   // Install a callback function that updates a progress indicator
   unsigned long long nToDelete = EstimateRemovedBlocks(begin, end),
      nDeleted = 0;
   ProgressDialog dialog{ XO("Progress"), XO("Discarding undo/redo history"),
      pdlgHideStopButton | pdlgHideCancelButton
   };
   auto callback = [&](const SampleBlock &){
      dialog.Update(++nDeleted, nToDelete);
   };
   auto &trackFactory = WaveTrackFactory::Get( mProject );
   auto &pSampleBlockFactory = trackFactory.GetSampleBlockFactory();
   auto prevCallback =
      pSampleBlockFactory->SetBlockDeletionCallback(callback);
   auto cleanup = finally([&]{ pSampleBlockFactory->SetBlockDeletionCallback( prevCallback ); });
 
   // 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)
      // wxWidgets will own the event object
      mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_PURGE } );
 
   // Check sanity
   wxASSERT_MSG(
      nDeleted == 0 || // maybe bypassing all deletions
      nDeleted == nToDelete, "Block count was misestimated");
}

References current, EstimateRemovedBlocks(), WaveTrackFactory::Get(), mProject, pdlgHideCancelButton, pdlgHideStopButton, RemoveStateAt(), safenew, saved, and XO.

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 308 of file UndoManager.cpp.

{
   if (state >= 0 && state < stack.size() ) {
      auto &theState = *stack[state];
      theState.description = longDescription;
      theState.shortDescription = shortDescription;
 
      // wxWidgets will own the event object
      mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_RENAMED } );
   }
}

References mProject, safenew, and stack.

SetLongDescription()

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

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

{
   wxASSERT(n < stack.size());
 
   current = n;
 
   lastAction = {};
   mayConsolidate = false;
 
   consumer( *stack[current] );
 
   // wxWidgets will own the event object
   mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_RESET } );
}

References current, lastAction, mayConsolidate, mProject, safenew, and stack.

StateSaved()

void UndoManager::StateSaved

(

)

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

{ mayConsolidate = false; }

Undo()

void UndoManager::Undo

(

const Consumer &

consumer

)

Definition at line 393 of file UndoManager.cpp.

{
   wxASSERT(UndoAvailable());
 
   current--;
 
   lastAction = {};
   mayConsolidate = false;
 
   consumer( *stack[current] );
 
   // wxWidgets will own the event object
   mProject.QueueEvent( safenew wxCommandEvent{ EVT_UNDO_OR_REDO } );
}

References current, lastAction, mayConsolidate, mProject, safenew, stack, and UndoAvailable().

Here is the call graph for this function:

UndoAvailable()

bool UndoManager::UndoAvailable

(

)

Definition at line 266 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 463 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 436 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.

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 445 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 min(), size, and stack.

Here is the call graph for this function:

Member Data Documentation

current

int UndoManager::current

private

Definition at line 216 of file UndoManager.h.

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

lastAction

TranslatableString UndoManager::lastAction

private

Definition at line 220 of file UndoManager.h.

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

mayConsolidate

bool UndoManager::mayConsolidate { false }

private

Definition at line 221 of file UndoManager.h.

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

mClipboardSpaceUsage

unsigned long long UndoManager::mClipboardSpaceUsage {}

private

Definition at line 224 of file UndoManager.h.

Referenced by CalculateSpaceUsage().

mProject

AudacityProject& UndoManager::mProject

private

Definition at line 214 of file UndoManager.h.

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

saved

int UndoManager::saved

private

Definition at line 217 of file UndoManager.h.

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

space

SpaceArray UndoManager::space

private

Definition at line 223 of file UndoManager.h.

Referenced by CalculateSpaceUsage(), and GetLongDescription().

stack

UndoStack UndoManager::stack

private

Definition at line 218 of file UndoManager.h.

Referenced by AbandonRedo(), CalculateSpaceUsage(), ClearStates(), EstimateRemovedBlocks(), GetLongDescription(), 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:

• UndoManager.h
• UndoManager.cpp