com.yworks.yfiles.graph

Class UndoEngine

java.lang.Object

com.yworks.yfiles.graph.UndoEngine

public class UndoEngine
extends Object

The main class to provide undo and redo functionality.

The UndoEngine is in charge of recording, managing and executing single units of work that can be undone and redone, represented by the interface IUndoUnit.

These units are managed in a queue-like structure and can be added manually to the queue by calling the addUnit(IUndoUnit) method.

Executing the units is done by client code or commands by calling undo() or redo(). The engine automatically manages the queue so that calling these two methdos will consistently move the units in the queue.

The beginCompoundEdit(String, String) method allows to record units by bracketing serveral changes in an ICompoundEdit. Implementations of the ICompoundEdit interface record all subsequent changes until it is committed and therefore all recorded units are added to the engine. For more information and examples see ICompoundEdit.

Depending on the properties UnitMergingEnabled and AutoMergeTime, the engine tries to collapse added IUndoUnits if possible. This enhances the performance and reduces the required memory for undo changes. For example, when a node is moved interactively, instead of saving every position that the node had when being dragged the engine will only hold one IUndoUnit at the end to undo the entire movement.

Customizing Undo/Redo

• In general, to be able to undo or redo certain work client code can implement IUndoUnit or subclass UndoUnitBase. The client application needs to encapsulate changes in this implementation and provide the logic to completely undo and redo these changes. Instances of your custom IUndoUnit implementations need to be added to the UndoEngine manually via addUnit(IUndoUnit).
• In certain cases it is difficult or not efficient to track and save the changes between certain states, and better to save the states themselves and to restore these. For example when there are potentially many intermediate steps between two states of interest and it would be complicated to produce IUndoUnits for each intermediate step and merge them in the end. In such cases client code should implement IMementoSupport instead. See the documentation of IMementoSupport for examples and guidelines on how to implement this memento design pattern concept.
• It is generally not necessary to subclass UndoEngine unless you want to customize the internal handling of the units, which is both complicated and prone to errors. In most use cases it is sufficient to provide custom IUndoUnits or IMementoSupport.

See Also:

IUndoUnit, AbstractUndoUnit, IMementoSupport, ICompoundEdit

Constructor Summary

Constructors

Constructor and Description
UndoEngine() Initializes a new instance of the UndoEngine class.

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangedListener(IEventHandler<PropertyChangedEventArgs> propertyChangedEvent) Adds the given listener for the PropertyChanged event that occurs when canUndo(), canRedo(), UndoName, or RedoName changed its value.
void	addUnit(IUndoUnit unit) Adds a new IUndoUnit to the queue.
void	addUnitRedoneListener(IEventHandler<IEventArgs> unitRedoneEvent) Adds the given listener for the UnitRedone event that occurs when the engine has successfully executed the IUndoUnit.redo() operation of an IUndoUnit.
void	addUnitUndoneListener(IEventHandler<IEventArgs> unitUndoneEvent) Adds the given listener for the UnitUndone event that occurs when the engine has successfully executed the IUndoUnit.undo() operation of an IUndoUnit.
ICompoundEdit	beginCompoundEdit(String undoName, String redoName) Begins a compound edit that will use the provided name.
boolean	canRedo() Determines whether a call to redo() can be made.
boolean	canUndo() Determines whether a call to undo() can be made.
void	clear() Clears the internal queue and disposes all units in it.
Duration	getAutoMergeTime() Gets the duration during which the engine will try to merge newly added units.
String	getRedoName() Returns the RedoName of the next redo() operation.
int	getSize() Gets the maximum size of the undo queue this instance is managing.
Object	getToken() Returns a token that can be used to store and compare the state of the undo queue.
String	getUndoName() Returns the UndoName of the next undo() operation.
boolean	isPerformingRedo() Indicates whether this instance is currently performing a redo operation.
boolean	isPerformingUndo() Indicates whether this instance is currently performing an undo operation.
boolean	isUnitMergingEnabled() Gets a value that indicates whether or not this instance should try to merge newly added units.
protected void	onPropertyChanged(String name) This will trigger the corresponding PropertyChanged event.
void	redo() Redoes the next IUndoUnit.
void	removePropertyChangedListener(IEventHandler<PropertyChangedEventArgs> propertyChangedEvent) Removes the given listener for the PropertyChanged event that occurs when canUndo(), canRedo(), UndoName, or RedoName changed its value.
void	removeUnitRedoneListener(IEventHandler<IEventArgs> unitRedoneEvent) Removes the given listener for the UnitRedone event that occurs when the engine has successfully executed the IUndoUnit.redo() operation of an IUndoUnit.
void	removeUnitUndoneListener(IEventHandler<IEventArgs> unitUndoneEvent) Removes the given listener for the UnitUndone event that occurs when the engine has successfully executed the IUndoUnit.undo() operation of an IUndoUnit.
void	setAutoMergeTime(Duration value) Sets the duration during which the engine will try to merge newly added units.
void	setSize(int value) Sets the maximum size of the undo queue this instance is managing.
void	setUnitMergingEnabled(boolean value) Sets a value that indicates whether or not this instance should try to merge newly added units.
String	toString()
void	undo() Undoes the next IUndoUnit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UndoEngine

public UndoEngine()

Initializes a new instance of the UndoEngine class.

Method Detail

addPropertyChangedListener

public final void addPropertyChangedListener(IEventHandler<PropertyChangedEventArgs> propertyChangedEvent)

Adds the given listener for the PropertyChanged event that occurs when canUndo(), canRedo(), UndoName, or RedoName changed its value.

Parameters:

propertyChangedEvent - The listener to add.

See Also:

removePropertyChangedListener(IEventHandler)

addUnit

public void addUnit(IUndoUnit unit)

Adds a new IUndoUnit to the queue.

This implementation will automatically group multiple units into a single unit if the time since the last add is less than AutoMergeTime.

Parameters:

unit - The unit of work to add.

addUnitRedoneListener

public final void addUnitRedoneListener(IEventHandler<IEventArgs> unitRedoneEvent)

Adds the given listener for the UnitRedone event that occurs when the engine has successfully executed the IUndoUnit.redo() operation of an IUndoUnit.

Parameters:

unitRedoneEvent - The listener to add.

See Also:

removeUnitRedoneListener(IEventHandler)

addUnitUndoneListener

public final void addUnitUndoneListener(IEventHandler<IEventArgs> unitUndoneEvent)

Adds the given listener for the UnitUndone event that occurs when the engine has successfully executed the IUndoUnit.undo() operation of an IUndoUnit.

Parameters:

unitUndoneEvent - The listener to add.

See Also:

removeUnitUndoneListener(IEventHandler)

beginCompoundEdit

public ICompoundEdit beginCompoundEdit(String undoName,
                                       String redoName)

Begins a compound edit that will use the provided name.

This will create a new edit that can independently be canceled or committed. Note that only if the outer-most instances is committed, the corresponding IUndoUnit units will be enqueued into this instance.

Parameters:

undoName - The undo name to use for the edit.

redoName - The redo name to use for the edit.

Returns:

A compound edit implementation that needs to be canceled or committed later.

canRedo

public boolean canRedo()

Determines whether a call to redo() can be made.

canUndo

public boolean canUndo()

Determines whether a call to undo() can be made.

clear

public void clear()

Clears the internal queue and disposes all units in it.

getAutoMergeTime

public final Duration getAutoMergeTime()

Gets the duration during which the engine will try to merge newly added units.

If this is set to Duration.ZERO, the engine will try to merge incoming units depending on the UnitMergingEnabled property. Otherwise, if the time span between the last added unit and the new unit exceeds the set value, the engine does not try to merge the units regardless what the UnitMergingEnabled property is set to. Likewise, if the time span is smaller than the set value, the engine will always try to merge units.

Returns:

The AutoMergeTime.

See Also:

setAutoMergeTime(Duration)

getRedoName

public final String getRedoName()

Returns the RedoName of the next redo() operation.

Returns:

The RedoName.

getSize

public final int getSize()

Gets the maximum size of the undo queue this instance is managing.

A size of 0 effectively disables this implementation.

Returns:

The Size.

See Also:

setSize(int)

getToken

public Object getToken()

Returns a token that can be used to store and compare the state of the undo queue.

E.g. an application can retrieve the token once the user has saved his document. Comparing the token returned by this instance with another one retrieved at a later point in time enables the application to determine whether the document is in the same state.

Returns:

An object that can be checked against other tokens via the Object.equals(Object) method.

getUndoName

public final String getUndoName()

Returns the UndoName of the next undo() operation.

Returns:

The UndoName.

isPerformingRedo

public final boolean isPerformingRedo()

Indicates whether this instance is currently performing a redo operation.

Returns:

The PerformingRedo.

isPerformingUndo

public final boolean isPerformingUndo()

Indicates whether this instance is currently performing an undo operation.

Returns:

The PerformingUndo.

isUnitMergingEnabled

public final boolean isUnitMergingEnabled()

Gets a value that indicates whether or not this instance should try to merge newly added units.

If true this instance will try to merge or replace units in the queue. Note that when the AutoMergeTime property is set to Duration.ZERO and this property is set to true, the engine will always try to merge incoming units. Otherwise the AutoMergeTime dictates whether the engine will try to merge a unit or not.

Returns:

The UnitMergingEnabled.

See Also:

setUnitMergingEnabled(boolean)

onPropertyChanged

protected void onPropertyChanged(String name)

This will trigger the corresponding PropertyChanged event.

Parameters:

name - The name of the property that changed.

redo

public void redo()

Redoes the next IUndoUnit.

Throws:

UnsupportedOperationException - If an undo operation is already in progress.

RuntimeException - If canRedo() would yield false.

removePropertyChangedListener

public final void removePropertyChangedListener(IEventHandler<PropertyChangedEventArgs> propertyChangedEvent)

Removes the given listener for the PropertyChanged event that occurs when canUndo(), canRedo(), UndoName, or RedoName changed its value.

Parameters:

propertyChangedEvent - The listener to remove.

See Also:

addPropertyChangedListener(IEventHandler)

removeUnitRedoneListener

public final void removeUnitRedoneListener(IEventHandler<IEventArgs> unitRedoneEvent)

Removes the given listener for the UnitRedone event that occurs when the engine has successfully executed the IUndoUnit.redo() operation of an IUndoUnit.

Parameters:

unitRedoneEvent - The listener to remove.

See Also:

addUnitRedoneListener(IEventHandler)

removeUnitUndoneListener

public final void removeUnitUndoneListener(IEventHandler<IEventArgs> unitUndoneEvent)

Removes the given listener for the UnitUndone event that occurs when the engine has successfully executed the IUndoUnit.undo() operation of an IUndoUnit.

Parameters:

unitUndoneEvent - The listener to remove.

See Also:

addUnitUndoneListener(IEventHandler)

setAutoMergeTime

public final void setAutoMergeTime(Duration value)

Sets the duration during which the engine will try to merge newly added units.

If this is set to Duration.ZERO, the engine will try to merge incoming units depending on the UnitMergingEnabled property. Otherwise, if the time span between the last added unit and the new unit exceeds the set value, the engine does not try to merge the units regardless what the UnitMergingEnabled property is set to. Likewise, if the time span is smaller than the set value, the engine will always try to merge units.

Parameters:

value - The AutoMergeTime to set.

See Also:

getAutoMergeTime()

setSize

public final void setSize(int value)

Sets the maximum size of the undo queue this instance is managing.

A size of 0 effectively disables this implementation.

Parameters:

value - The Size to set.

See Also:

getSize()

setUnitMergingEnabled

public final void setUnitMergingEnabled(boolean value)

Sets a value that indicates whether or not this instance should try to merge newly added units.

If true this instance will try to merge or replace units in the queue. Note that when the AutoMergeTime property is set to Duration.ZERO and this property is set to true, the engine will always try to merge incoming units. Otherwise the AutoMergeTime dictates whether the engine will try to merge a unit or not.

Parameters:

value - The UnitMergingEnabled to set.

See Also:

isUnitMergingEnabled()

toString

public String toString()

Overrides:

toString in class Object

undo

public void undo()

Undoes the next IUndoUnit.

Throws:

UnsupportedOperationException - If an undo operation is already in progress.

RuntimeException - If canUndo() would yield false.