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.
- abstract property id¶
Returns the command id which is used to call the command and should be unique
- Returns:
the Command id
- Return type:
- abstract property isUndoable¶
Returns whether this command is undoable or not
- Returns:
Defaults to False
- Return type:
- 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:
- prepareCommand()¶
- classmethod commandAction(uiType, parent=None, optionBox=False)¶
- 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
- 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
- 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()¶
- launch(parent=None)¶
Errors¶
- exception UserCancel(message, errors=None)¶
Bases:
Exception
- exception CommandExecutionError(message, *args, **kwargs)¶
Bases:
Exception