LLCommandManager
Objectives
The LLCommandManager class is designed to store generic commands to execute an action. This manager's initial use is as a vehicle to store the actions associated with toolbar buttons but it is meant to be extended in the future to perform any type of command, be it a function call, a SLAPP, or anything else. It may even be extended to have user customizable commands like macros or gestures.
Design
LLCommandId is the way to uniquely identify a command and is the recommended way to pass a command between classes. It is essentially a wrapper for the LLUUID associated with a command. The LLCommandId can be used to retrieve a LLCommand pointer from the LLCommandManager. Dragging a toolbar button from one place to another passes the LLUUID for a given LLCommandId as the payload.
LLCommand is the main container for the data associated with a given command. In order to minimize dependencies and keep it truly generic, the LLCommand itself stores functions as std::string's and their associated parameters as LLSD's. The LLCommand contains parameters to define its name, icon reference, label reference and tooltip reference, along with the name of a function to execute. References for the icon, label and tooltip are used in the interest of minimizing dependencies requiring consumers of the command to look up the appropriate images or localized strings. Optionally, the LLCommand may also include functions to stop execution and query to determine if it is enabled, starting up or running.
LLCommandManager is the singleton central repository for all of the LLCommand's. It contains methods to retrieve and iterate through all of the LLCommand's. Viewer code calls LLCommandManager::load() fairly early during initialization to parse the contents of commands.xml to set up the commands.
- NOTE: Execution of commands does not happen directly through the command or command manager itself. The command is simply a storage class for the names of the functions that define a command and execution of those functions occurs in the code that uses the command, i.e., the button that drives the command.
Use of commands in toolbars
LLCommand's are mapped to toolbar buttons through their defined icon, label and tooltip references. The button is enabled by default or its enabled/disabled status is set by the return value of the is_enabled_function if one is specified. The toggle state of the button is set based on the return value of the is_running_function. Currently we do not use the is_starting_function on the toolbars.
That darned speak button
Users of the toolbars will notice that the "speak" button is one button that behaves differently than most of the rest. For starters, the "speak" command is the only fundamental command that uses the execute_stop_function, since it has to both open and close the user's microphone. The "speak" button has two built-in behaviors based on a preference -- it either functions in a "push-to-talk" behavior or as a toggle. In order for the toolbars to support this functionality, the specification of the execute_stop_function changes the button behavior from execution on the button commit event to execution and execution stop on the button mouse down and mouse up events respectively. With this setup and by maintaining its own internal microphone state, the command is able to handle both behaviors seamlessly.
There is also special code in place to trigger the command and disable the microphone automatically when the "speak" button is removed from a toolbar, to prevent the microphone from being left on erroneously.