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 meta class 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 require

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