UndoSystem
index
/home/david/Projects/Jokosher/trunk/Jokosher/UndoSystem.py

#       THIS FILE IS PART OF THE JOKOSHER PROJECT AND LICENSED UNDER THE GPL. SEE
#       THE 'COPYING' FILE FOR DETAILS
#
#       UndoSystem.py
#
#       Contains the decorator needed to allow other classes to hook specific
#       function calls into the undo stack.
#
#=========================================================================

 
Modules
       
Globals
Project
Utils

 
Classes
       
AtomicUndoAction
exceptions.Exception
CancelUndoCommand

 
class AtomicUndoAction
    Contains several undo commands to be treated as a single undoable operation.
 
Example:
        When deleting several Instruments at once, an AtomicUndoAction
        containing the commands to resurrect the Instruments will be created.
        When the user requests an undo operation, all of the commands stored
        in this object will be rolled back, making the operation appear to be
        atomic from the user's perspective.
 
  Methods defined here:
AddUndoCommand(self, objectString, function, paramList)
Adds a new undo command to this AtomicUndoAction.
 
Example:
        The parameters passed to this function:
                "E2", "Move", [1, 2]
        means
                'Call Move(1, 2)' on the Event with ID=2
 
Parameters:
        objectString -- the string representing the object and its ID
                                        (ie "E2" for Event with ID == 2).
        function -- the name of the function to be called on the object.
        paramList -- a list of values to be passed to the function as parameters.
                                Key, value parameters are not supported.
GetUndoCommands(self)
Obtains the list of undo commands held by this AtomicUndoAction.
 
Returns:
        a list of tuples, each of which contains a single undo command.
StoreToXML(self, doc, node)
Stores this instance of AtomicUndoAction into an XML node.
 
Example:
                doc = xml.Document()
                node = doc.createElement("Action")
                doc.appendChild(node)
                StoreToXml(doc, node)
                
        will save this AtomicUndoAction in doc, inside node.
 
Parameters:
        doc -- XML document to save this AtomicUndoAction into.
        node -- XML node to store this AtomicUndoAction under.
                        This node's name should be "Action".
__init__(self, addToStack=True)
Creates a new AtomicUndoAction instance and optionally adds it to the
undo stack.
 
Parameters:
        addToStack -- if True, this instance will be added to the currently
                                active Project's undo/redo stack.

 
class CancelUndoCommand(exceptions.Exception)
    This exception can be thrown by a decorated undo
function in order to tell the undo system to not
log the current action. This is useful if something
in the function fails and the action that would have
been logged to the undo stack was never actually completed.
 
  Methods defined here:
__init__(self, result=None)
Creates a new instance of CancelUndoCommand.
 
Parameters:
        result -- value the wrapped function intended to return,
                                but failed and called this exception.

Methods inherited from exceptions.Exception:
__getitem__(...)
__str__(...)

 
Functions
       
LoadUndoActionFromXML(node)
Loads an AtomicUndoAction from an XML node.
 
Parameters:
        node -- XML node from which the AtomicUndoAction is loaded.
                        Should be an "<Action>" node.
        
Returns:
        the loaded AtomicUndoAction object.
UndoCommand(*command)
Decorates functions, enabling them to be logged in the undo stack.
The decorating process is transparent to the clients.
 
Parameters:
        command -- the undo command list of strings.
        
Returns:
        an UndoFunction which decorates the original function.