Open 3D Engine EMotionFX Gem API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
MCore::CommandManager Class Reference

#include <MCoreCommandManager.h>

Inherited by CommandSystem::CommandManager.

Classes

struct  CommandHistoryEntry
 

Public Member Functions

 CommandManager ()
 
virtual ~CommandManager ()
 
bool ExecuteCommand (const char *command, AZStd::string &outCommandResult, bool addToHistory=true, Command **outExecutedCommand=nullptr, CommandLine *outExecutedParamters=nullptr, bool callFromCommandGroup=false, bool clearErrors=true, bool handleErrors=true)
 
bool ExecuteCommand (const AZStd::string &command, AZStd::string &outCommandResult, bool addToHistory=true, Command **outExecutedCommand=nullptr, CommandLine *outExecutedParamters=nullptr, bool callFromCommandGroup=false, bool clearErrors=true, bool handleErrors=true)
 
bool ExecuteCommand (Command *command, AZStd::string &outCommandResult, bool addToHistory=true, bool clearErrors=true, bool handleErrors=true, bool autoDeleteCommand=true)
 
bool ExecuteCommandInsideCommand (const char *command, AZStd::string &outCommandResult)
 
bool ExecuteCommandInsideCommand (const AZStd::string &command, AZStd::string &outCommandResult)
 
bool ExecuteCommandInsideCommand (Command *command, AZStd::string &outCommandResult)
 
bool ExecuteCommandOrAddToGroup (const AZStd::string &command, MCore::CommandGroup *commandGroup=nullptr, bool executeInsideCommand=false)
 
bool ExecuteCommandOrAddToGroup (Command *command, MCore::CommandGroup *commandGroup=nullptr, bool executeInsideCommand=false)
 
bool ExecuteCommandGroup (CommandGroup &commandGroup, AZStd::string &outCommandResult, bool addToHistory=true, bool clearErrors=true, bool handleErrors=true)
 
bool ExecuteCommandGroupInsideCommand (CommandGroup &commandGroup, AZStd::string &outCommandResult)
 
bool Undo (AZStd::string &outCommandResult)
 
bool Redo (AZStd::string &outCommandResult)
 
bool RegisterCommand (Command *command)
 
void LogCommandHistory ()
 
CommandFindCommand (const AZStd::string &commandName)
 
void RemoveCallbacks ()
 
void RegisterCallback (CommandManagerCallback *callback)
 
void RemoveCallback (CommandManagerCallback *callback, bool delFromMem=true)
 
size_t GetNumCallbacks () const
 
CommandManagerCallbackGetCallback (size_t index)
 
void SetMaxHistoryItems (size_t maxItems)
 
size_t GetMaxHistoryItems () const
 
ptrdiff_t GetHistoryIndex () const
 
size_t GetNumHistoryItems () const
 
const CommandHistoryEntryGetHistoryItem (size_t index) const
 
CommandGetHistoryCommand (size_t historyIndex)
 
void ClearHistory ()
 
const CommandLineGetHistoryCommandLine (size_t historyIndex) const
 
size_t GetNumRegisteredCommands () const
 
CommandGetCommand (size_t index)
 
void RemoveCommandCallback (Command::Callback *callback, bool delFromMem)
 
void RemoveCommandCallback (const char *commandName, Command::Callback *callback, bool delFromMem)
 
bool RegisterCommandCallback (const char *commandName, Command::Callback *callback)
 
template<typename T , typename... Args>
bool RegisterCommandCallback (const char *commandName, AZStd::vector< Command::Callback * > &callbacks, Args... args)
 
MCORE_INLINE void AddError (const char *errorLine)
 
MCORE_INLINE void AddError (const AZStd::string &errorLine)
 
bool ShowErrorReport ()
 
bool IsExecuting () const
 

Protected Member Functions

bool ExecuteCommand (Command *command, const CommandLine &commandLine, AZStd::string &outCommandResult, bool addToHistory, bool callFromCommandGroup, bool clearErrors, bool handleErrors, bool autoDeleteCommand)
 
bool ShouldDeleteCommand (Command *commandObject, bool commandExecutionResult, bool callFromCommandGroup, bool addToHistory)
 
void PushCommandHistory (Command *command, const CommandLine &parameters)
 
void PushCommandHistory (CommandGroup *commandGroup)
 
void PopCommandHistory ()
 
void ExecuteUndoCallbacks (Command *command, const CommandLine &parameters, bool preUndo)
 
void ExecuteCommandCallbacks (Command *command, const CommandLine &parameters, bool preCommand)
 

Protected Attributes

AZStd::unordered_map< AZStd::string, Command * > m_registeredCommands
 
AZStd::vector< CommandHistoryEntrym_commandHistory
 
AZStd::vector< CommandManagerCallback * > m_callbacks
 
AZStd::vector< AZStd::string > m_errors
 
AZStd::vector< Command * > m_commands
 
size_t m_maxHistoryEntries
 
ptrdiff_t m_historyIndex
 
size_t m_totalNumHistoryItems
 
int m_commandsInExecution
 

Detailed Description

The command manager. This manager has a set of registered commands (MCore::Command) that can be executed and undo-ed and redo-ed through this manager. Also it keeps a command history. It also supports the usage of command groups, which batch sets of commands as single commands inside the command history.

Constructor & Destructor Documentation

◆ CommandManager()

MCore::CommandManager::CommandManager ( )

The default constructor.

◆ ~CommandManager()

virtual MCore::CommandManager::~CommandManager ( )
virtual

The destructor.

Reimplemented in CommandSystem::CommandManager.

Member Function Documentation

◆ AddError()

MCORE_INLINE void MCore::CommandManager::AddError ( const char *  errorLine)
inline

Add error message to the internal callback based error handling system.

Parameters
[in]errorLineThe error line to add to the internal error handler.

◆ ClearHistory()

void MCore::CommandManager::ClearHistory ( )

Clear the history.

◆ ExecuteCommand() [1/2]

bool MCore::CommandManager::ExecuteCommand ( Command command,
const CommandLine commandLine,
AZStd::string &  outCommandResult,
bool  addToHistory,
bool  callFromCommandGroup,
bool  clearErrors,
bool  handleErrors,
bool  autoDeleteCommand 
)
protected

Internal method to execute a command.

Parameters
commandThe registered command object.
commandLineThe commandline object.
outCommandResultThe return/result value of the command.
[in]callFromCommandGroupTrue in case the command is called from a command group. False in case the command to be called is not part of a command group and called only by itself.
addToHistoryWhen set to true it is being added to the command history. This is set to false when redoing a command.
Returns
True if the command succeeded, false if not.

◆ ExecuteCommand() [2/2]

bool MCore::CommandManager::ExecuteCommand ( const char *  command,
AZStd::string &  outCommandResult,
bool  addToHistory = true,
Command **  outExecutedCommand = nullptr,
CommandLine outExecutedParamters = nullptr,
bool  callFromCommandGroup = false,
bool  clearErrors = true,
bool  handleErrors = true 
)

Execute a command.

Parameters
commandThe command string including all arguments.
outCommandResultThe return/result value of the command.
addToHistoryWhen set to true it is being added to the command history and can be undone.
outExecutedCommandThis will contain the pointer to the command that was executed, or nullptr when no command was excuted. Please note that the pointer that will be stored in this parameter will be invalid when the command failed to execute.
outExecutedParamtersThis will contain the command line parameter list of the executed command.
[in]callFromCommandGroupTrue in case the command is called from a command group. False in case the command to be called is not part of a command group and called only by itself.
Returns
True if the command succeeded, false if not.

◆ ExecuteCommandCallbacks()

void MCore::CommandManager::ExecuteCommandCallbacks ( Command command,
const CommandLine parameters,
bool  preCommand 
)
protected

Will be internally called before and after executing a command.

Parameters
commandThe command which will get or got executed.
parametersThe given command parameters.
preCommandExecute all pre-commant callbacks in case this parameter is true, execute all post-command callbacks elsewise.

◆ ExecuteCommandGroup()

bool MCore::CommandManager::ExecuteCommandGroup ( CommandGroup commandGroup,
AZStd::string &  outCommandResult,
bool  addToHistory = true,
bool  clearErrors = true,
bool  handleErrors = true 
)

Execute a command group. The group will contain a set of commands inside it which are seen as one command. This is useful when you want to for example execute 10 commands, but only show these 10 commands inside the command history as one grouped command. Undoing the group will undo all commands that are part of the group..

Parameters
commandGroupThe command group to execute.
outCommandResultThe result of the group execution. This generally contains the last successful or failed command status.
addToHistorySet to true when you want to add this group to the history.
Returns
Returns true when ALL commands inside the group executed successfully, otherwise false is returned.

◆ ExecuteUndoCallbacks()

void MCore::CommandManager::ExecuteUndoCallbacks ( Command command,
const CommandLine parameters,
bool  preUndo 
)
protected

Will be internally called before and after undoing a command.

Parameters
commandThe command which will get or got executed.
parametersThe given command parameters.
preUndoExecute all pre-undo callbacks in case this parameter is true, execute all post-undo callbacks elsewise.

◆ FindCommand()

Command * MCore::CommandManager::FindCommand ( const AZStd::string &  commandName)

Find the command in the hash table.

Parameters
commandNameThe name of the command.
Returns
A pointer to the command object, nullptr if it hasn't been found.

◆ GetCallback()

CommandManagerCallback * MCore::CommandManager::GetCallback ( size_t  index)

Get a given callback.

Parameters
indexThe callback number to get, which must be in range of [0..GetNumCallbacks()-1].

◆ GetCommand()

Command * MCore::CommandManager::GetCommand ( size_t  index)

Get a given registered command.

Parameters
indexThe command number, which must be in range of [0..GetNumRegisteredCommands()-1].
Returns
A pointer to the command.

◆ GetHistoryCommand()

Command * MCore::CommandManager::GetHistoryCommand ( size_t  historyIndex)

Get a given command from the command history.

Parameters
historyIndexThe history index number, which must be in range of [0..GetNumHistoryItems()-1].
Returns
A pointer to the command stored at the given history index.

◆ GetHistoryCommandLine()

const CommandLine & MCore::CommandManager::GetHistoryCommandLine ( size_t  historyIndex) const

Get the command line for a given history item.

Parameters
historyIndexThe history index number, which must be in range of [0..GetNumHistoryItems()-1].
Returns
A reference to the command line that was used when executing this command.

◆ GetHistoryIndex()

ptrdiff_t MCore::CommandManager::GetHistoryIndex ( ) const

Get the current history index. This value will be in range of [0..GetMaxHistoryItems()-1].

Returns
The current history index.

◆ GetMaxHistoryItems()

size_t MCore::CommandManager::GetMaxHistoryItems ( ) const

Get the maximum number of history items that the manager will remember. On default this value is 100. This means it will remember the last 100 executed commands, which can then be undo-ed and redo-ed.

Returns
The number of maximum history items.

◆ GetNumCallbacks()

size_t MCore::CommandManager::GetNumCallbacks ( ) const

Get the number of registered callbacks.

Returns
The number of registered callbacks.

◆ GetNumHistoryItems()

size_t MCore::CommandManager::GetNumHistoryItems ( ) const

Get the number of history items stored. This is the number of executed commands that are stored in the history right now.

Returns
The number of history items currently stored.

◆ GetNumRegisteredCommands()

size_t MCore::CommandManager::GetNumRegisteredCommands ( ) const

Get the total number of registered commands.

Returns
The number of registered commands.

◆ IsExecuting()

bool MCore::CommandManager::IsExecuting ( ) const
inline

Checks if there are commands currently being executed

Returns
True in case there is at least one command being executed.

◆ LogCommandHistory()

void MCore::CommandManager::LogCommandHistory ( )

Debug function to log the current command history.

◆ PopCommandHistory()

void MCore::CommandManager::PopCommandHistory ( )
protected

Pop a command history item from the stack. After this the command cannot be un- or redone.

◆ PushCommandHistory() [1/2]

void MCore::CommandManager::PushCommandHistory ( Command command,
const CommandLine parameters 
)
protected

Push a command to the command history stack . This method will be automatically called by the system when a command has been called but only if it is undoable.

Parameters
commandThe command instance that has been created at execution time.
parametersThe command arguments.

◆ PushCommandHistory() [2/2]

void MCore::CommandManager::PushCommandHistory ( CommandGroup commandGroup)
protected

Add the given command group to the history.

Parameters
commandGroupThe command group to add to the history.

◆ Redo()

bool MCore::CommandManager::Redo ( AZStd::string &  outCommandResult)

Redo the last command which has been undoed.

Parameters
outCommandResultThe return/result value of the command.
Returns
True if the redo succeeded, false if not.

◆ RegisterCallback()

void MCore::CommandManager::RegisterCallback ( CommandManagerCallback callback)

Register a callback. This increases the number returned by GetNumCallbacks().

Parameters
callbackThe callback to add to the list of registered callbacks.

◆ RegisterCommand()

bool MCore::CommandManager::RegisterCommand ( Command command)

Register a command to the command manager. Each command has to be registered using this function before using it. You can just new a command object when calling this function. The command manager will keep track of the used memory and will destroy it automatically. E.g. MCORE_COMMANDMANAGER.RegisterCommand( new CreateBoxCommand() );.

Parameters
commandThe command to register.
Returns
True if command registration succeeded, false it not.

◆ RegisterCommandCallback()

bool MCore::CommandManager::RegisterCommandCallback ( const char *  commandName,
Command::Callback callback 
)

Register (add) a command callback to a given command with a given name.

Parameters
commandNameThe non-case-sensitive name of the command where we should add this callback to.
callbackThe callback to add to the given command.
Returns
Returns true when added successfully or false when there is no command with the specified name.

◆ RemoveCallback()

void MCore::CommandManager::RemoveCallback ( CommandManagerCallback callback,
bool  delFromMem = true 
)

Remove a given callback from the manager.

Parameters
callbackThe callback to remove.
delFromMemSet to true when you wish to also delete the callback object from memory.

◆ RemoveCallbacks()

void MCore::CommandManager::RemoveCallbacks ( )

Remove and delete all callbacks from memory. Automatically called by the destructor.

◆ RemoveCommandCallback() [1/2]

void MCore::CommandManager::RemoveCommandCallback ( Command::Callback callback,
bool  delFromMem 
)

Remove a given command callback. This automatically finds the command where this callback has been added to and removes it from that.

Parameters
callbackThe callback to remove.
delFromMemWhen set to true, the specified callback will be deleted from memory as well (even when not registered at any of the commands).

◆ RemoveCommandCallback() [2/2]

void MCore::CommandManager::RemoveCommandCallback ( const char *  commandName,
Command::Callback callback,
bool  delFromMem 
)

Remove a given command callback from a given command with a given name.

Parameters
commandNameThe non-case-sentive name of the command to remove the callback from.
callbackThe callback to remove from the command with the specified name.
delFromMemWhen set to true, the specified callback will be deleted from memory as well (even when not registered at any of the commands).

◆ SetMaxHistoryItems()

void MCore::CommandManager::SetMaxHistoryItems ( size_t  maxItems)

Set the maximum number of history items that the manager should remember. On default this value is 100. This means it will remember the last 100 executed commands, which can then be undo-ed and redo-ed.

Parameters
maxItemsThe maximum number of items to remember.

◆ ShowErrorReport()

bool MCore::CommandManager::ShowErrorReport ( )

Checks if an error occurred and calls the error handling callbacks.

Returns
True in case an error occurred, false if not.

◆ Undo()

bool MCore::CommandManager::Undo ( AZStd::string &  outCommandResult)

Undo the last executed command in the command history.

Parameters
outCommandResultThe return/result value of the command.
Returns
True if the undo succeeded, false if not.

Member Data Documentation

◆ m_callbacks

AZStd::vector<CommandManagerCallback*> MCore::CommandManager::m_callbacks
protected

The command manager callbacks.

◆ m_commandHistory

AZStd::vector<CommandHistoryEntry> MCore::CommandManager::m_commandHistory
protected

The command history stack for undo/redo functionality.

◆ m_commands

AZStd::vector<Command*> MCore::CommandManager::m_commands
protected

A flat array of registered commands, for easy traversal.

◆ m_commandsInExecution

int MCore::CommandManager::m_commandsInExecution
protected

The number of commands currently in execution.

◆ m_errors

AZStd::vector<AZStd::string> MCore::CommandManager::m_errors
protected

List of errors that happened during command execution.

◆ m_historyIndex

ptrdiff_t MCore::CommandManager::m_historyIndex
protected

The command history iterator. The current position in the undo/redo history.

◆ m_maxHistoryEntries

size_t MCore::CommandManager::m_maxHistoryEntries
protected

The maximum remembered commands in the command history.

◆ m_registeredCommands

AZStd::unordered_map<AZStd::string, Command*> MCore::CommandManager::m_registeredCommands
protected

A hash table storing the command objects for fast command object access.

◆ m_totalNumHistoryItems

size_t MCore::CommandManager::m_totalNumHistoryItems
protected

The number of history items since the application start. This number will neither change depending on the size of the history queue nor with undo/redo.


The documentation for this class was generated from the following file: