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.
See Also
Developer's Guide
Members
Properties
Methods
Called by the UndoEngine and client code to let the unit dispose of references aren't needed anymore.
See Also
Developer's Guide
API
- redoName
Tries to merge the given unit with this one.
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
- unit: IUndoUnit
- The unit to incorporate that happened after this unit.
Return Value
- boolean
- Whether the state change of
unithas been incorporated into this unit andunitcan be disposed of.
See Also
Developer's Guide
Tries to replace the given unit with this one.
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
- unit: IUndoUnit
- The unit to incorporate that happened before this unit.
Return Value
- boolean
- Whether the state change of
thisunit has been incorporated into the givenunitandthiscan be disposed of.
See Also
Developer's Guide
See Also
Developer's Guide
API
- undoName
Static Methods
Creates a new undo unit using the provided name and undo and redo handler delegates.
Parameters
- undoName: string
- The name of the undo.
- undo: function(T): void
- The undo handler delegate.
- redo: function(T): void
- The redo handler delegate.
Return Value
- IUndoUnit
- A new undo unit with the provided name and undo and redo handler delegates.
fromHandler
<T> (undoName: stringundoRedo: function(T): voidundoParam: TredoParam: T): IUndoUnitstaticCreates a new undo unit using the provided name and an undo/redo handler delegate as well as the parameters to pass to the delegate.
fromHandler
<T> (Parameters
- undoName: string
- The name of the undo.
- undoRedo: function(T): void
- The undo and redo handler delegate.
- undoParam: T
- The undo parameter to pass to the delegate.
- redoParam: T
- The redo parameter to pass to the delegate.
Return Value
- IUndoUnit
- An undo unit composed of the specified undo and redo handler.
fromHandler
<T> (undoName: stringundo: function(T): voidredo: function(T): voidundoParam: TredoParam: T): IUndoUnitstaticCreates a new undo unit using the provided name and undo and redo handler delegates as well as the parameters to pass to the delegates.
fromHandler
<T> (Parameters
- undoName: string
- The name of the undo.
- undo: function(T): void
- The undo handler delegate.
- redo: function(T): void
- The redo handler delegate.
- undoParam: T
- The undo parameter to pass to the delegate.
- redoParam: T
- The redo parameter to pass to the delegate.
Return Value
- IUndoUnit
- An undo unit composed of the specified undo and redo handlers.