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