Manages a list of undo/redo commands. More...

#include <juce_UndoManager.h>

Inheritance diagram for UndoManager:

Collaboration diagram for UndoManager:

[legend]

Public Member Functions
	UndoManager (int maxNumberOfUnitsToKeep=30000, int minimumTransactionsToKeep=30)
	Creates an UndoManager. More...

	~UndoManager ()
	Destructor. More...

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster. More...

void	beginNewTransaction () noexcept
	Starts a new group of actions that together will be treated as a single transaction. More...

void	beginNewTransaction (const String &actionName) noexcept
	Starts a new group of actions that together will be treated as a single transaction. More...

bool	canRedo () const noexcept
	Returns true if there's at least one action in the list to redo. More...

bool	canUndo () const noexcept
	Returns true if there's at least one action in the list to undo. More...

void	clearUndoHistory ()
	Deletes all stored actions in the list. More...

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...

void	getActionsInCurrentTransaction (Array< const UndoableAction *> &actionsFound) const
	Returns a list of the UndoableAction objects that have been performed during the transaction that is currently open. More...

String	getCurrentTransactionName () const noexcept
	Returns the name of the current transaction. More...

int	getNumActionsInCurrentTransaction () const
	Returns the number of UndoableAction objects that have been performed during the transaction that is currently open. More...

int	getNumberOfUnitsTakenUpByStoredCommands () const
	Returns the current amount of space to use for storing UndoableAction objects. More...

String	getRedoDescription () const
	Returns the name of the transaction that will be redone when redo() is called. More...

Time	getTimeOfRedoTransaction () const
	Returns the time to which the state would be restored if redo() was to be called. More...

Time	getTimeOfUndoTransaction () const
	Returns the time to which the state would be restored if undo() was to be called. More...

String	getUndoDescription () const
	Returns the name of the transaction that will be rolled-back when undo() is called. More...

bool	perform (UndoableAction *action)
	Performs an action and adds it to the undo history list. More...

bool	perform (UndoableAction *action, const String &actionName)
	Performs an action and also gives it a name. More...

bool	redo ()
	Tries to redo the last transaction that was undone. More...

void	removeAllChangeListeners ()
	Removes all listeners from the list. More...

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list. More...

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners. More...

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners. More...

void	setCurrentTransactionName (const String &newName) noexcept
	Changes the name stored for the current transaction. More...

void	setMaxNumberOfStoredUnits (int maxNumberOfUnitsToKeep, int minimumTransactionsToKeep)
	Sets the amount of space that can be used for storing UndoableAction objects. More...

bool	undo ()
	Tries to roll-back the last transaction. More...

bool	undoCurrentTransactionOnly ()
	Tries to roll-back any actions that were added to the current transaction. More...

Private Member Functions
void	dropOldTransactionsIfTooLarge ()

ActionSet *	getCurrentSet () const noexcept

ActionSet *	getNextSet () const noexcept

void	moveFutureTransactionsToStash ()

void	restoreStashedFutureTransactions ()

Private Attributes
int	maxNumUnitsToKeep

int	minimumTransactionsToKeep

bool	newTransaction

String	newTransactionName

int	nextIndex

bool	reentrancyCheck

OwnedArray< ActionSet >	stashedFutureTransactions

int	totalUnitsStored

OwnedArray< ActionSet >	transactions

Friends
struct	ContainerDeletePolicy< ActionSet >

Detailed Description

Manages a list of undo/redo commands.

An UndoManager object keeps a list of past actions and can use these actions to move backwards and forwards through an undo history.

To use it, create subclasses of UndoableAction which perform all the actions you need, then when you need to actually perform an action, create one and pass it to the UndoManager's perform() method.

The manager also uses the concept of 'transactions' to group the actions together - all actions performed between calls to beginNewTransaction() are grouped together and are all undone/redone as a group.

The UndoManager is a ChangeBroadcaster, so listeners can register to be told when actions are performed or undone.

See also: UndoableAction

Constructor & Destructor Documentation

◆ UndoManager()

UndoManager::UndoManager	(	int	maxNumberOfUnitsToKeep = `30000`,
		int	minimumTransactionsToKeep = `30`
	)

Creates an UndoManager.

Parameters

maxNumberOfUnitsToKeep	each UndoableAction object returns a value to indicate how much storage it takes up (UndoableAction::getSizeInUnits()), so this lets you specify the maximum total number of units that the undomanager is allowed to keep in memory before letting the older actions drop off the end of the list.
minimumTransactionsToKeep	this specifies the minimum number of transactions that will be kept, even if this involves exceeding the amount of space specified in maxNumberOfUnitsToKeep

◆ ~UndoManager()

UndoManager::~UndoManager ( )

Destructor.

Member Function Documentation

◆ addChangeListener()

void ChangeBroadcaster::addChangeListener ( ChangeListener * listener )

inherited

Registers a listener to receive change callbacks from this broadcaster.

Trying to add a listener that's already on the list will have no effect.

◆ beginNewTransaction() [1/2]

void UndoManager::beginNewTransaction ( )

noexcept

Starts a new group of actions that together will be treated as a single transaction.

All actions that are passed to the perform() method between calls to this method are grouped together and undone/redone together by a single call to undo() or redo().

◆ beginNewTransaction() [2/2]

void UndoManager::beginNewTransaction ( const String & actionName )

noexcept

Starts a new group of actions that together will be treated as a single transaction.

All actions that are passed to the perform() method between calls to this method are grouped together and undone/redone together by a single call to undo() or redo().

Parameters

actionName a description of the transaction that is about to be performed

◆ canRedo()

bool UndoManager::canRedo ( ) const

noexcept

Returns true if there's at least one action in the list to redo.

See also: getRedoDescription, redo, canUndo

◆ canUndo()

bool UndoManager::canUndo ( ) const

noexcept

Returns true if there's at least one action in the list to undo.

See also: getUndoDescription, undo, canRedo

◆ clearUndoHistory()

void UndoManager::clearUndoHistory ( )

Deletes all stored actions in the list.

◆ dispatchPendingMessages()

void ChangeBroadcaster::dispatchPendingMessages ( )

inherited

If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

For thread-safety reasons, you must only call this method on the main message thread.

◆ dropOldTransactionsIfTooLarge()

void UndoManager::dropOldTransactionsIfTooLarge ( )

private

◆ getActionsInCurrentTransaction()

void UndoManager::getActionsInCurrentTransaction ( Array< const UndoableAction *> & actionsFound ) const

Returns a list of the UndoableAction objects that have been performed during the transaction that is currently open.

Effectively, this is the list of actions that would be undone if undoCurrentTransactionOnly() were to be called now.

The first item in the list is the earliest action performed.

◆ getCurrentSet()

ActionSet* UndoManager::getCurrentSet ( ) const

privatenoexcept

◆ getCurrentTransactionName()

String UndoManager::getCurrentTransactionName ( ) const

noexcept

Returns the name of the current transaction.

See also: setCurrentTransactionName

◆ getNextSet()

ActionSet* UndoManager::getNextSet ( ) const

privatenoexcept

◆ getNumActionsInCurrentTransaction()

int UndoManager::getNumActionsInCurrentTransaction ( ) const

Returns the number of UndoableAction objects that have been performed during the transaction that is currently open.

See also: getActionsInCurrentTransaction

◆ getNumberOfUnitsTakenUpByStoredCommands()

int UndoManager::getNumberOfUnitsTakenUpByStoredCommands ( ) const

Returns the current amount of space to use for storing UndoableAction objects.

See also: setMaxNumberOfStoredUnits

◆ getRedoDescription()

String UndoManager::getRedoDescription ( ) const

Returns the name of the transaction that will be redone when redo() is called.

See also: redo

◆ getTimeOfRedoTransaction()

Time UndoManager::getTimeOfRedoTransaction ( ) const

Returns the time to which the state would be restored if redo() was to be called.

If a redo isn't currently possible, it'll return Time::getCurrentTime().

◆ getTimeOfUndoTransaction()

Time UndoManager::getTimeOfUndoTransaction ( ) const

Returns the time to which the state would be restored if undo() was to be called.

If an undo isn't currently possible, it'll return Time().

◆ getUndoDescription()

String UndoManager::getUndoDescription ( ) const

Returns the name of the transaction that will be rolled-back when undo() is called.

See also: undo

◆ moveFutureTransactionsToStash()

void UndoManager::moveFutureTransactionsToStash ( )

private

◆ perform() [1/2]

bool UndoManager::perform ( UndoableAction * action )

Performs an action and adds it to the undo history list.

Parameters

action the action to perform - this object will be deleted by the UndoManager when no longer needed

Returns: true if the command succeeds - see UndoableAction::perform

See also: beginNewTransaction

◆ perform() [2/2]

bool UndoManager::perform	(	UndoableAction *	action,
		const String &	actionName
	)

Performs an action and also gives it a name.

Parameters

action	the action to perform - this object will be deleted by the UndoManager when no longer needed
actionName	if this string is non-empty, the current transaction will be given this name; if it's empty, the current transaction name will be left unchanged. See setCurrentTransactionName()

Returns: true if the command succeeds - see UndoableAction::perform

See also: beginNewTransaction

◆ redo()

bool UndoManager::redo ( )

Tries to redo the last transaction that was undone.

Returns: true if the transaction can be redone, and false if it fails, or if there aren't any transactions to redo

◆ removeAllChangeListeners()

void ChangeBroadcaster::removeAllChangeListeners ( )

inherited

Removes all listeners from the list.

◆ removeChangeListener()

void ChangeBroadcaster::removeChangeListener ( ChangeListener * listener )

inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ restoreStashedFutureTransactions()

void UndoManager::restoreStashedFutureTransactions ( )

private

◆ sendChangeMessage()

void ChangeBroadcaster::sendChangeMessage ( )

inherited

Causes an asynchronous change message to be sent to all the registered listeners.

The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().

Referenced by SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void ChangeBroadcaster::sendSynchronousChangeMessage ( )

inherited

Sends a synchronous change message to all the registered listeners.

This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.

See also: dispatchPendingMessages

Referenced by SelectedItemSet< SelectableItemType >::changed().

◆ setCurrentTransactionName()

void UndoManager::setCurrentTransactionName ( const String & newName )

noexcept

Changes the name stored for the current transaction.

Each transaction is given a name when the beginNewTransaction() method is called, but this can be used to change that name without starting a new transaction.

◆ setMaxNumberOfStoredUnits()

void UndoManager::setMaxNumberOfStoredUnits	(	int	maxNumberOfUnitsToKeep,
		int	minimumTransactionsToKeep
	)

Sets the amount of space that can be used for storing UndoableAction objects.

Parameters

maxNumberOfUnitsToKeep	each UndoableAction object returns a value to indicate how much storage it takes up (UndoableAction::getSizeInUnits()), so this lets you specify the maximum total number of units that the undomanager is allowed to keep in memory before letting the older actions drop off the end of the list.
minimumTransactionsToKeep	this specifies the minimum number of transactions that will be kept, even if this involves exceeding the amount of space specified in maxNumberOfUnitsToKeep

See also: getNumberOfUnitsTakenUpByStoredCommands

◆ undo()

bool UndoManager::undo ( )

Tries to roll-back the last transaction.

Returns: true if the transaction can be undone, and false if it fails, or if there aren't any transactions to undo

◆ undoCurrentTransactionOnly()

bool UndoManager::undoCurrentTransactionOnly ( )

Tries to roll-back any actions that were added to the current transaction.

This will perform an undo() only if there are some actions in the undo list that were added after the last call to beginNewTransaction().

This is useful because it lets you call beginNewTransaction(), then perform an operation which may or may not actually perform some actions, and then call this method to get rid of any actions that might have been done without it rolling back the previous transaction if nothing was actually done.

Returns: true if any actions were undone.

Friends And Related Function Documentation

◆ ContainerDeletePolicy< ActionSet >

friend struct ContainerDeletePolicy< ActionSet >

friend

Member Data Documentation

◆ maxNumUnitsToKeep

int UndoManager::maxNumUnitsToKeep

private

◆ minimumTransactionsToKeep

int UndoManager::minimumTransactionsToKeep

private

◆ newTransaction

bool UndoManager::newTransaction

private

◆ newTransactionName

String UndoManager::newTransactionName

private

◆ nextIndex

int UndoManager::nextIndex

private

◆ reentrancyCheck

bool UndoManager::reentrancyCheck

private

◆ stashedFutureTransactions

OwnedArray<ActionSet> UndoManager::stashedFutureTransactions

private

◆ totalUnitsStored

int UndoManager::totalUnitsStored

private

◆ transactions

OwnedArray<ActionSet> UndoManager::transactions

private

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

juce_UndoManager.h

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ UndoManager()

◆ ~UndoManager()

Member Function Documentation

◆ addChangeListener()

◆ beginNewTransaction() [1/2]

◆ beginNewTransaction() [2/2]

◆ canRedo()

◆ canUndo()

◆ clearUndoHistory()

◆ dispatchPendingMessages()

◆ dropOldTransactionsIfTooLarge()

◆ getActionsInCurrentTransaction()

◆ getCurrentSet()

◆ getCurrentTransactionName()

◆ getNextSet()

◆ getNumActionsInCurrentTransaction()

◆ getNumberOfUnitsTakenUpByStoredCommands()

◆ getRedoDescription()

◆ getTimeOfRedoTransaction()

◆ getTimeOfUndoTransaction()

◆ getUndoDescription()

◆ moveFutureTransactionsToStash()

◆ perform() [1/2]

◆ perform() [2/2]

◆ redo()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ restoreStashedFutureTransactions()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

◆ setCurrentTransactionName()

◆ setMaxNumberOfStoredUnits()

◆ undo()

◆ undoCurrentTransactionOnly()

Friends And Related Function Documentation

◆ ContainerDeletePolicy< ActionSet >

Member Data Documentation

◆ maxNumUnitsToKeep

◆ minimumTransactionsToKeep

◆ newTransaction

◆ newTransactionName

◆ nextIndex

◆ reentrancyCheck

◆ stashedFutureTransactions

◆ totalUnitsStored

◆ transactions