UndoUnitBase

This method is called when this unit is the head of an UndoEngine's or CompositeUndoUnit'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 don't necessarily have to implement this method if the unit doesn't happen very often. In fact, the default implementation of tryMergeUnit simply returns false. 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 CompositeUndoUnit instead.

This method is called if a newly added unit couldn't 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 don't necessarily have to implement this method if the unit doesn't happen very often. In fact, the default implementation of tryReplaceUnit simply returns false. 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 CompositeUndoUnit instead.