Represents a unit of work that can be undone and redone.
Remarks
Clients should use this interface when certain actions, changes, or events should be monitored and have undoability provided for them. If you simply want to track the state of certain items between two states of interest, you should consider using mementos instead.
The central methods of this interface are undo and redo which contain the logic to undo or redo a unit of work. Keep in mind that undo/redo are sensible operations and should maintain a consistent state before and after each operation since they may be executed potentially often one after another.
The requirement for an IUndoUnit is that when a program is in a certain state and a call to undo is followed by a call to redo then the program is in the exact same state as before (the same holds true for the other way around).
IUndoUnits are managed by the UndoEngine. Custom units can always be added to the engine using the method addUnit. Also consider using fromHandler to take delegates for the undo/redo operations and combine to create a bracketing unit comprising several other units.
Also note that in order to keep a consistent state, methods of objects of this type should not be called by client code directly but only through UndoEngine instead.
Type Details
- yFiles module
- view
Properties
Methods
Called by the UndoEngine and client code to let the unit dispose of references aren't needed anymore.
Remarks
Redoes the work that is represented by this unit.
Remarks
See Also
Tries to merge the given unit with this one.
Remarks
This method is called when this unit is the head of an UndoEngine's queue and a new unit is added. It is meant to try to incorporate the change of the given unit into this and if successful return true. This should be the case when the end state of this unit is equal to the start state of the given unit.
For example, if this unit is the head of the queue and represents the work from state A to state B and the given unit the work from state B to state C, then this method should try to make this unit shift from state A to state C. If this is successful, the method is expected to return true. The other unit is then disposed by the UndoEngine afterwards.
Clients do not necessarily have to implement this method if the unit does not happen very often. Implementing this method faithfully will cause multiple units of work to inseparably appear as one and undoing/redoing it will undo/redo the work of all collapsed units. Depending on the situation this may be reasonable, for example when there are potentially a lot of changes where not every intermediate step is required to be recorded. In this case implementing this method faithfully will greatly improve the performance and reduce the required amount of memory of the undo process. If you want to group together multiple units as a single block but still want to be able to separate each step, consider to use a composite unit instead.
Parameters
A map of options to pass to the method.
- unit - IUndoUnit
- The unit to incorporate that happened after this unit.
Returns
- ↪boolean
- Whether the state change of
unithas been incorporated into this unit andunitcan be disposed of.
Tries to replace the given unit with this one.
Remarks
This method is called if a newly added unit could not be merged with the head unit of the queue (i.e. returned false). Instead of trying to merge a newly added unit, this method tries to replace the given unit (which is the head of the queue) with this by incorporating the change of the given unit into this and if successful return true. This should be the case when the start state of this unit is equal to the end state of the given unit.
For example, if the given unit represents the work from state A to state B and this unit the work from state B to state C, then this method should try to make this unit shift from state A to state C. If this is successful, the method is expected to return true. The given unit is then disposed by the UndoEngine afterwards and replaced with this unit in the queue.
Clients do not necessarily have to implement this method if the unit does not happen very often. Implementing this method faithfully will cause multiple units of work to inseparably appear as one and undoing/redoing it will undo/redo the work of all collapsed units. Depending on the situation this may be reasonable, for example when there are potentially a lot of changes where not every intermediate step is required to be recorded. In this case implementing this method faithfully will greatly improve the performance and reduce the required amount of memory of the undo process. If you want to group together multiple units as a single block but still want to be able to separate each step, consider to use a composite unit instead.
Parameters
A map of options to pass to the method.
- unit - IUndoUnit
- The unit to incorporate that happened before this unit.
Returns
- ↪boolean
- Whether the state change of
thisunit has been incorporated into the givenunitandthiscan be disposed of.
Undoes the work that is represented by this unit.
Remarks
See Also
Static Methods
Creates a composite undo unit from several distinct IUndoUnit instances.
Remarks
Parameters
A map of options to pass to the method.
- units - IUndoUnit
- The units to combine.
Returns
- ↪IUndoUnit
- A composite undo unit that encapsulates the provided undo units.
Creates a composite undo unit from several distinct IUndoUnit instances.
Remarks
Parameters
A map of options to pass to the method.
- undoName - string
- The name for the undo.
- redoName - string
- The name for the redo.
- units - IUndoUnit
- The units to combine.
Returns
- ↪IUndoUnit
- The combined undo unit
fromHandler
<T>(undoName: string, undoRedo: function(T):void, undoParam: T, redoParam: T) : IUndoUnitCreates a new undo unit using the provided name and an undo/redo handler delegate as well as the parameters to pass to the delegate.
Type Parameters
- T
Parameters
A map of options to pass to the method.
- undoName - string
- The name of the undo.
- undoRedo - function(T):void
- The undo and redo handler delegate.
Signature Details
function(param: T)The delegate that is used by fromHandler.Parameters
- param - T
- A usage-dependent parameter that is passed to the delegate.
- undoParam - T
- The undo parameter to pass to the delegate.
- redoParam - T
- The redo parameter to pass to the delegate.
Returns
- ↪IUndoUnit
- An undo unit composed of the specified undo and redo handler.
fromHandler
<T>(undoName: string, undo: function(T):void, redo: function(T):void, undoParam: T, redoParam: T) : IUndoUnitCreates a new undo unit using the provided name and undo and redo handler delegates as well as the parameters to pass to the delegates.
Type Parameters
- T
Parameters
A map of options to pass to the method.
- undoName - string
- The name of the undo.
- undo - function(T):void
- The undo handler delegate.
Signature Details
function(param: T)The delegate that is used by fromHandler.Parameters
- param - T
- A usage-dependent parameter that is passed to the delegate.
- redo - function(T):void
- The redo handler delegate.
Signature Details
function(param: T)The delegate that is used by fromHandler.Parameters
- param - T
- A usage-dependent parameter that is passed to the delegate.
- undoParam - T
- The undo parameter to pass to the delegate.
- redoParam - T
- The redo parameter to pass to the delegate.
Returns
- ↪IUndoUnit
- An undo unit composed of the specified undo and redo handlers.
Creates a new undo unit using the provided name and undo and redo handler delegates.
Type Parameters
- T
Parameters
A map of options to pass to the method.
- undoName - string
- The name of the undo.
- undo - function(T):void
- The undo handler delegate.
Signature Details
function(param: T)The delegate that is used by fromHandler.Parameters
- param - T
- A usage-dependent parameter that is passed to the delegate.
- redo - function(T):void
- The redo handler delegate.
Signature Details
function(param: T)The delegate that is used by fromHandler.Parameters
- param - T
- A usage-dependent parameter that is passed to the delegate.
Returns
- ↪IUndoUnit
- A new undo unit with the provided name and undo and redo handler delegates.