Up: User interface objects
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.
|Global instance (if any):
|Used in optional component:
||Part of main VMD code
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
- 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).
- 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.
- 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
- 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.
When objects other than UIObjects wish to execute a command, they
should use the global object commandQueue, and append the
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.
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.
Up: User interface objects