Editor:Proposal:UndoManager

This article is currently only a proposal

The features or design guidelines described in this article are only a proposal made by one or some persons. It has not been reviewed and ratified by the core development team yet. Feel free to add your personal opinion about them or make counter proposals.

UndoManager

UndoManager provides an easy way to keep track of the actions the user has done, and allow the user to undo/redo those actions.

In some situations the UndoManager might eat up a lot of memory so a max_history property has been added. If the history stack contains more than max_history actions, the oldest entries are removed.

A visual history tool should be supplied, so the user can easily see what actions he have done.

Proposals

These proposals are already added to the proposed interface, but are not essential to have in the undo manager.

Branched mode: Make sure the user does not lose the actions he/she undid by branching the history tree.

Non-linear undo: Allow the user to undo/redo an action anywhere in the history without having to undo all actions before it. This is almost useless without a visual tool to pick the actions to undo.

See Making undo usable for more information on advanced undo.

Interface

class UndoManager
  # Methods
  UndoManager(bool branchedMode = false, int max_history=10000)
  
  list getUndoStack()
  list getRedoStack()
  
  void startGroup(str name=None)
  void endGroup()
  
  void addAction(UndoObject action)
  
  void clear()
  
  # Linear undo
  void undo(int amount=1)
  void redo(int amount=1)
  
  # Non-linear undo
  void undoAction(object action)
  void redoAction(object action)
  
  # Branched mode
  void _setMaxHistoryItems(int maxitems)
  int _getMaxHistoryItems()
  maxHistoryItems = property(_getMaxHistoryItems, _setMaxHistoryItems)
  
  bool _getBranchMode()
  void _setBranchMode(bool enable)
  branchmode = propert(_getBranchMode, _setBranchMode)
   
  list getBranches()
  void nextBranch()
  void previousBranch()
  
class UndoObject
  UndoObject(callback undoCallback, callback redoCallback, string name="", string description="", string icon="")
  
  callback getUndoAction()
  callback getRedoAction()

Usage

Example:

class SomeClass:
   def __init__(self, **args):
      self.undomanager = UndoManager()
    
   def addObject(self, object):
      
      undoCallback = pychan.tools.callbackWithArguments(self._removeObject, object=object)
      redoCallback = pychan.tools.callbackWithArguments(self._placeObject, object=object)
      
      undoobject = UndoObject(undoCallback=undoCallback, redoCallback=redoCallback, name="Placed object")
      self.undomanager.addAction(undoobject)
   
      self._placeObject(object=object)
 
   def addWall(self, actionlist, name="Added wall"):
      self.undomanager.startGroup(name=name)
      self.addObject(self.getObject("wall_1"))
      self.addObject(self.getObject("wall_2"))
      self.addObject(self.getObject("wall_3"))
      self.undomanager.endGroup()