CommandQueue

Files:	CommandQueue.h, CommandQueue.C
Derived from:	none
Global instance (if any):	commandQueue
Used in optional component:	Part of main VMD code

Description

CommandQueue maintains a queue of Command's, and will go through this queue and execute them when requested. The queue is first-in first-out. This object also has the ability to log commands to a file.

There is one global instance of this class in VMD, called commandQueue. It is used by all the user interface objects (UIObject classes). Each time a new action is requested by the user or some other part of VMD, a new Command instance is created and added to the CommandQueue. Within the main event loop of VMD, after each UIObject is checked for new events, the commands in the queue are all executed until the queue is empty (since the execution of one command may result in the queuing of a new command, this process continues until the queue is empty). Each time the queue is checked, the following occurs:

• The next Command instance at the top of the queue is fetched to be executed.

• If commands are being logged to a file, the text representation of the command is written to that file.

• The command itself is executed, and the return code (success of the command) is stored.

• After it is executed, each UIObject active at that time is informed about the command, and are given both the pointer to the command, and it's success flag. This is done so that user interfaces can update their visual display or internal state to reflect the fact that something has changed. In this way, even though a single user interface component may do some action, ALL user interface's can know when to update their state to reflect the changes in the program.

• After this, the Command instance is deleted. There is one routine which does this differently, `runcommand' (see below).

Constructors

• CommandQueue::CommandQueue(void)
  

Internal data structures

• ResizeArray<Command *> cmdlist - the queue of commands.

• int loggingCmds - flag indicating whether commands are being logged to a file.

• FILE *logfile - pointer to the FILE strcture for the output log file, if one is being used.

Nonvirtual member functions

• int do_execute(Command *) - executes the given command, echoing it to the log file if necessary and informing all the UIObjects. This will NOT delete the Command; this routine is called by other routines in CommandQueue.

• void delete_current(void) - deletes the command which is at the top of the queue, and moves all the other commands up. This is called by `execute' after the command has been run.

• int logging(void) - return TRUE if logging of commands is turned on.

• void log_on(char *) - turns on logging of commands, to the given file.

• void log_off(void) - turns off logging, closes the open log file if necessary.

• int num(void) - return number of commands in the queue.

• int append(Command *) - puts the given command instance at the end of the queue. This will not execute it; commands are not executed until one of the following three routines are called. This returns TRUE if the command could be added.

• int execute(void) - executes just the first command in the queue, by calling do_execute and then delete_command. Returns the success code of the command, or FALSE if not command is available.

• void execute_all(void) - just calls execute until the queue is empty.

• int runcommand(Command *) - this routine executes the given command, but without adding it to the queue. It should be used when you definitely know that a command should be done immediately, and can be done out-of-order with respect to the other commands which might be in the queue. When the command is done, it is deleted. This returns the success code of the command.

Method of use

When objects other than UIObjects wish to execute a command, they should use the global object commandQueue, and append the command:

commandQueue->append(new CmdReshape());

This command will not actually be run until the main event loop in VMD is run. If a command needs to be executed immediately, use runcommand:

int success = commandQueue->runcommand(new CmdReshape());

When UIObjects are adding commands, there are special funcions in UIObject to make this faster, `addcommand' and `runcommand'. Each UIObject is given a pointer to a CommandQueue object, and so the `addcommand' routine will take a command and add it to that queue. For example, in UIText there might be:

addcommand(new TextEvent("text command", id()));

Most commands have as their last argument an id code for the UIObject which created them. This is that so UIObjects can tell, when they are told that the command has executed, who started it all.

Suggestions for future changes/additions

There should be a version of runcommand that allows for executing a command without 'new'ing it. At least, there should be an argument to runcommand to allow this possibility.