JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::UndoManager Class Reference

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

#include <juce_UndoManager.h>

Inheritance diagram for juce::UndoManager:
Collaboration diagram for juce::UndoManager:

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 ()
 Starts a new group of actions that together will be treated as a single transaction. More...
 
void beginNewTransaction (const String &actionName)
 Starts a new group of actions that together will be treated as a single transaction. More...
 
bool canRedo () const
 Returns true if there's at least one action in the list to redo. More...
 
bool canUndo () const
 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
 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...
 
StringArray getRedoDescriptions () const
 Returns the names of the sequence of transactions that will be performed if redo() is repeatedly 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...
 
StringArray getUndoDescriptions () const
 Returns the names of the sequence of transactions that will be performed if undo() is repeatedly called. More...
 
bool isPerformingUndoRedo () const
 Returns true if the caller code is in the middle of an undo or redo action. 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)
 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
 
ActionSet * getNextSet () const
 
void moveFutureTransactionsToStash ()
 
void restoreStashedFutureTransactions ()
 

Private Attributes

bool isInsideUndoRedoCall = false
 
int maxNumUnitsToKeep = 0
 
int minimumTransactionsToKeep = 0
 
bool newTransaction = true
 
String newTransactionName
 
int nextIndex = 0
 
OwnedArray< ActionSet > stashedFutureTransactions
 
int totalUnitsStored = 0
 
OwnedArray< ActionSet > transactions
 

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

{DataStructures}

Constructor & Destructor Documentation

◆ UndoManager()

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

Creates an UndoManager.

Parameters
maxNumberOfUnitsToKeepeach 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.
minimumTransactionsToKeepthis specifies the minimum number of transactions that will be kept, even if this involves exceeding the amount of space specified in maxNumberOfUnitsToKeep

◆ ~UndoManager()

juce::UndoManager::~UndoManager ( )

Destructor.

Member Function Documentation

◆ addChangeListener()

void juce::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 juce::UndoManager::beginNewTransaction ( )

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 juce::UndoManager::beginNewTransaction ( const String actionName)

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
actionNamea description of the transaction that is about to be performed

◆ canRedo()

bool juce::UndoManager::canRedo ( ) const

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

See also
getRedoDescription, redo, canUndo

◆ canUndo()

bool juce::UndoManager::canUndo ( ) const

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

See also
getUndoDescription, undo, canRedo

◆ clearUndoHistory()

void juce::UndoManager::clearUndoHistory ( )

Deletes all stored actions in the list.

◆ dispatchPendingMessages()

void juce::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 juce::UndoManager::dropOldTransactionsIfTooLarge ( )
private

◆ getActionsInCurrentTransaction()

void juce::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* juce::UndoManager::getCurrentSet ( ) const
private

◆ getCurrentTransactionName()

String juce::UndoManager::getCurrentTransactionName ( ) const

Returns the name of the current transaction.

See also
setCurrentTransactionName

◆ getNextSet()

ActionSet* juce::UndoManager::getNextSet ( ) const
private

◆ getNumActionsInCurrentTransaction()

int juce::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 juce::UndoManager::getNumberOfUnitsTakenUpByStoredCommands ( ) const

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

See also
setMaxNumberOfStoredUnits

◆ getRedoDescription()

String juce::UndoManager::getRedoDescription ( ) const

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

See also
redo, canRedo, getRedoDescriptions

◆ getRedoDescriptions()

StringArray juce::UndoManager::getRedoDescriptions ( ) const

Returns the names of the sequence of transactions that will be performed if redo() is repeatedly called.

Note that for transactions where no name was provided, the corresponding string will be empty.

See also
redo, canRedo, getRedoDescription

◆ getTimeOfRedoTransaction()

Time juce::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().

See also
redo, canRedo

◆ getTimeOfUndoTransaction()

Time juce::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 juce::UndoManager::getUndoDescription ( ) const

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

See also
undo, canUndo, getUndoDescriptions

◆ getUndoDescriptions()

StringArray juce::UndoManager::getUndoDescriptions ( ) const

Returns the names of the sequence of transactions that will be performed if undo() is repeatedly called.

Note that for transactions where no name was provided, the corresponding string will be empty.

See also
undo, canUndo, getUndoDescription

◆ isPerformingUndoRedo()

bool juce::UndoManager::isPerformingUndoRedo ( ) const

Returns true if the caller code is in the middle of an undo or redo action.

◆ moveFutureTransactionsToStash()

void juce::UndoManager::moveFutureTransactionsToStash ( )
private

◆ perform() [1/2]

bool juce::UndoManager::perform ( UndoableAction action)

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

Parameters
actionthe 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 juce::UndoManager::perform ( UndoableAction action,
const String actionName 
)

Performs an action and also gives it a name.

Parameters
actionthe action to perform - this object will be deleted by the UndoManager when no longer needed
actionNameif 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 juce::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 juce::ChangeBroadcaster::removeAllChangeListeners ( )
inherited

Removes all listeners from the list.

◆ removeChangeListener()

void juce::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 juce::UndoManager::restoreStashedFutureTransactions ( )
private

◆ sendChangeMessage()

void juce::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 juce::SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void juce::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 juce::SelectedItemSet< SelectableItemType >::changed().

◆ setCurrentTransactionName()

void juce::UndoManager::setCurrentTransactionName ( const String newName)

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 juce::UndoManager::setMaxNumberOfStoredUnits ( int  maxNumberOfUnitsToKeep,
int  minimumTransactionsToKeep 
)

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

Parameters
maxNumberOfUnitsToKeepeach 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.
minimumTransactionsToKeepthis 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 juce::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
See also
undoCurrentTransactionOnly

◆ undoCurrentTransactionOnly()

bool juce::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.

Member Data Documentation

◆ isInsideUndoRedoCall

bool juce::UndoManager::isInsideUndoRedoCall = false
private

◆ maxNumUnitsToKeep

int juce::UndoManager::maxNumUnitsToKeep = 0
private

◆ minimumTransactionsToKeep

int juce::UndoManager::minimumTransactionsToKeep = 0
private

◆ newTransaction

bool juce::UndoManager::newTransaction = true
private

◆ newTransactionName

String juce::UndoManager::newTransactionName
private

◆ nextIndex

int juce::UndoManager::nextIndex = 0
private

◆ stashedFutureTransactions

OwnedArray<ActionSet> juce::UndoManager::stashedFutureTransactions
private

◆ totalUnitsStored

int juce::UndoManager::totalUnitsStored = 0
private

◆ transactions

OwnedArray<ActionSet> juce::UndoManager::transactions
private

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