Zoo Command

Python command pattern with undo,redo functionality for standard applications and or DCCs if supported via command executors

Commands follow some strict rules.

  • All commands must inherent from zoo.libs.command.command.ZooCommand

  • All commands must have the following overrides
    • id(property) the command id

    • creator(property) the developer of the command name

    • isUndoable(property) Does the command support undo

    • doIt(method), Main method to do the operation

    • undoIt(method), if is undoable then undoIt() must be implemented

Commands provide persistent Gui data aka settings These include: Label, icon, toolip, color(foreground), backgroundColor

Any command can have a QAction generate on demand via command.commandAction()

Usage

The built command library lives under zoo.libs.command.library but users can add there own path via the environment variable ‘ZOO_COMMAND_LIB’ then running the following

from zoo.libs.command import executor
executor.Executor().registerEnv("ZOO_COMMAND_LIB")

To execute commands one must use the executor class and never execute the command directly otherwise it will not be added to the internal undo stack and or the redostack.

# to execute a command
from zoo.libs.command import executor
exe = executor.Executor()
exe.executor("commandId", **kwargs)

To undo a command.

from zoo.libs.command import executor
executor.Executor().registerEnv("ZOO_COMMAND_LIB")
executor.undoLast()

To redo a command from the undostack.

from zoo.libs.command import executor
executor.Executor().registerEnv("ZOO_COMMAND_LIB")
executor.redoLast()

API

class ExecutorBase(interface=None, registerEnv='ZOO_COMMAND_LIB')

Bases: object

property commands
execute(name, *args, **kwargs)
undoLast()
redoLast()
findCommand(id)
flush()
cancel(msg)
commandHelp(commandId)
groups()
class CommandStats(tool)

Bases: object

finish(tb=None)

Called when the plugin has finish executing

class CommandInterface(stats=None)

Bases: object

The standard ZooCommand metaclass interface. Each command must implement doIt, id, creator, isUndoable, description

uiData = {'backgroundColor': '', 'color': '', 'icon': '', 'label': '', 'tooltip': ''}
initialize()

Intended for overriding by the subclasses, intention here is if the subclass needs __init__ functionality then this function should be used instead to avoid any mishaps in any uncalled data.

abstract doIt(**kwargs)

Main method to implemented the command operation. all subclasses must have a doIt method The DoIt method only support Kwargs meaning that every argument must have a default, this is by design to maintain clarity in people implementation.

Parameters:
  • kwargs – key value pairs, values can be any type , we are not restricted by types including custom objects or DCC dependent objects eg.MObjects.

  • kwargs – dict

:return This method should if desired by the developer return a value, this value can be anything including maya api MObject etc.

Example:

# correct doIt(source=None, target=None, translate=True) # incorrect doIt(source, target=None, translate=True)

undoIt()

If this command instance is set to undoable then this method needs to be implemented, by design you do the inverse operation of the doIt method

Returns:

Return type:

runIt()

Runs doIt with the current arguments

Returns:

The result from doIt

runArguments(**arguments)

Parses the arguments then runs the command

Parameters:

arguments – key, value pairs that correspond to the DoIt method

Returns:

Return type:

resolveArguments(arguments)

Method which allows the developer to pre doIt validate the incoming arguments. This method get executed before any operation on the command.

Parameters:

arguments (dict) – key, value pairs that correspond to the DoIt method

Returns:

Should always return a dict with the same key value pairs as the arguments param

Return type:

dict

abstract property id

Returns the command id which is used to call the command and should be unique

Returns:

the Command id

Return type:

str

abstract property creator

Returns the developer name of this command

Return type:

str

abstract property isUndoable

Returns whether this command is undoable or not

Returns:

Defaults to False

Return type:

bool

commandUi()

Method to launch dialogs for this command instance, When a command is run the client can specify if the ui is required

class ZooCommand(stats=None)

Bases: CommandInterface

isEnabled = True
useUndoChunk = True
disableQueue = False
initialize()

Intended for overriding by the subclasses, intention here is if the subclass needs __init__ functionality then this function should be used instead to avoid any mishaps in any uncalled data.

description()
requiresWarning()
displayWarning(message)
warningMessage()
cancel(msg=None)

Raises the UserCancel error, useful when validating arguments

Parameters:

msg (str) – The Error message to display

Raise:

errors.UserCancel

hasArgument(name)
parseArguments(arguments)

Parse the arguments and get it ready for the command to use

Parameters:

arguments (duct) – dictionary

Returns:

Return type:

bool

prepareCommand()
classmethod commandAction(uiType, parent=None, optionBox=False)
class ArgumentParser

Bases: dict

generateCommandTemplate(className, id, doItContent, undoItContent, filePath, creator, doitArgs)

Function to Generate a ZooCommand template.

Parameters:
  • className (str) – the command class Name

  • id (str) – the command Id

  • doItContent (str) – The python code for the doIt method

  • undoItContent (str) – The python code for the undoIt method

  • filePath (str) – The file location to create this command

  • creator (str) – the command developers name

  • doitArgs (dict) – The doIt arguments

Returns:

Return type:

Executor

class ExecutorMeta

Bases: type

Executor meta class singleton to hot swap the class type depending on which environment we’re in. For Example if we’re in maya the zoo.libs.maya.mayacommand.mayaexecutor.MayaExecutor will be created

class Executor(*args, **kwargs)

Bases: object

execute(executeId, **kwargs)

Helper to execute zoo commands by id

Parameters:

executeId (basestring) – ID To execute

Returns:

Returns the executor and anything from exe execute

GUI

class CommandActionBase(*args: Any, **kwargs: Any)

Bases: QObject

CommandUi class deals with encapsulating a command as a widget

triggered

alias of str

triggeredUi

alias of str

create(parent=None)
class MenuItem(*args: Any, **kwargs: Any)

Bases: CommandActionBase

create(parent=None, optionBox=False)
emitCommand(*args)
Parameters:

args (tuple) – dummy to deal with maya command args shit stains. basically useless

emitCommandUi(*args)
Parameters:

args (tuple) – dummy to deal with maya command args shit stains. basically useless

class CommandAction(*args: Any, **kwargs: Any)

Bases: CommandActionBase

create(parent=None)
show()
class CommandViewer(*args: Any, **kwargs: Any)

Bases: QWidget

refresh()
setup()
launch(parent=None)

Errors

exception UserCancel(message, errors=None)

Bases: Exception

exception CommandExecutionError(message, *args, **kwargs)

Bases: Exception