Package mrv :: Package maya :: Module undo

Module undo

Contains the undo engine allowing to adjust the scene with api commands while providing full undo and redo support.

Features

modify dag or dg using the undo-enabled DG and DAG modifiers

modify values using Nodes and their plugs (as the plugs are overridden to store undo information)

Limitations

You cannot mix mel and API proprely unless you use an MDGModifier.commandToExecute

Calling operations that flush the undo queue from within an undoable method causes the internal python undo stack not to be flushed, leaving dangling objects that might crash maya once they are undon.

WORKAROUND: Mark these methods with @notundoable and assure they are not called by an undoable method

calling MFn methods on a node usually means that undo is not supported for it.

Configuration

To globally disable the undo queue using cmds.undo will disable tracking of opeartions, but will still call the mel command.

Disable the 'undoable' decorator effectively remove the surrounding mel script calls by setting the MRV_UNDO_ENABLED environment variable to 0 (default 1). Additionally it will turn off the maya undo queue as a convenience.

If the mrv undo queue is disabled, MPlugs will not store undo information anymore and do not incur any overhead.

Implementing an undoable method

decorate with @undoable

minimize probability that your operation will fail before creating an operation (for efficiency)

only use operation's doIt() method to apply your changes

if you raise, you should not have created an undo operation

Classes

[hide private]

UndoCmd

Utilities

MuteUndo
Instantiate this class to disable the maya undo queue - on deletion, the previous state will be restored

StartUndo
Utility class that will push the undo stack on __init__ and pop it on __del__

UndoRecorder
Utility class allowing to undo and redo operations on the python command stack so far to be undone and redone separately and independently of maya's undo queue.

Operations

Operation
Simple command class as base for all operations All undoable/redoable operation must support it

GenericOperation
Simple oeration allowing to use a generic doit and untoit call to be accessed using the operation interface.

GenericOperationStack
Operation able to undo generic callable commands (one or multiple).

DGModifier
Undo-aware DG Modifier - using it will automatically put it onto the API undo queue

DagModifier
undo-aware DAG modifier, copying all extra functions from DGModifier

Functions

[hide private]

initializePlugin(mobject)

source code

uninitializePlugin(mobject)

source code

Initialization

__initialize()
Assure our plugin is loaded - called during module intialization

source code

Utilities

_incrStack()
Indicate that a new method level was reached

source code

_decrStack(name="unnamed")
Indicate that a method level was exitted - and cause the undo queue to be stored on the command if appropriate We try to call the command only if needed

source code

startUndo()
Call before you start undoable operations

source code

endUndo()
Call before your function with undoable operations ends

source code

undoAndClear()
Undo all operations on the undo stack and clear it afterwards.

source code

Decorators

undoable(func)
Decorator wrapping func so that it will start undo when it begins and end undo when it ends.

source code

forceundoable(func)
As undoable, but will enable the undo queue if it is currently disabled.

source code

notundoable(func)
Decorator wrapping a function into a muteUndo call, thus all undoable operations called from this method will not enter the UndoRecorder and thus pollute it.

source code

Variables

[hide private]

_undo_enabled_envvar = "MRV_UNDO_ENABLED"

_should_initialize_plugin = int(os.environ.get(_undo_enabled_e...

Undo Plugin

isUndoing = api.MGlobal.isUndoing

undoInfo = cmds.undoInfo

_maya_undo_enabled = int(os.environ.get(_undo_enabled_envvar, ...

Function Details

[hide private]

__initialize()

source code

Assure our plugin is loaded - called during module intialization

Note: will only load the plugin if the undo system is not disabled

startUndo()

source code

Call before you start undoable operations

Note: prefer the @undoable decorator

endUndo()

source code

Call before your function with undoable operations ends

Note: prefer the @undoable decorator

undoAndClear()

source code

Undo all operations on the undo stack and clear it afterwards. The respective undo command will do nothing once undo, but would undo all future operations. The state of the undoqueue is well defined afterwards, but callers may stop functioning if their changes have been undone.

Note: can be used if you need control over undo in very specific operations and in a well defined context

undoable(func)

source code

Decorator wrapping func so that it will start undo when it begins and end undo when it ends. It assures that only toplevel undoable functions will actually produce an undo event To mark a function undoable, decorate it:

>>> @undoable
>>> def func():
>>>     pass

Notes:

Using decorated functions appears to be only FASTER than implementing it manually, thus using these is will greatly improve code readability
if you use undoable functions, you should mark yourself undoable too - otherwise the functions you call will create individual undo steps
if the undo queue is disabled, the decorator does nothing

forceundoable(func)

source code

As undoable, but will enable the undo queue if it is currently disabled. It will forcibly enable maya's undo queue.

Note: can only be employed reasonably if used in conjunction with undoAndClear as it will restore the old state of the undoqueue afterwards, which might be off, thus rendering attempts to undo impossible

notundoable(func)

source code

Decorator wrapping a function into a muteUndo call, thus all undoable operations called from this method will not enter the UndoRecorder and thus pollute it.

Notes:

use it if your method cannot support undo, butcalls undoable operations itself
all functions using a notundoable should be notundoable themselves
does nothing if the undo queue is globally disabled

Variables Details

[hide private]

_should_initialize_plugin

Value:

int(os.environ.get(_undo_enabled_envvar, True))

_maya_undo_enabled

Value:

int(os.environ.get(_undo_enabled_envvar, True))