Next: Tracker objects
Up: User interface objects
Previous: UIObject
  Contents
Subsections
UIText
Files: |
UIText.h,
UIText.C |
Derived from: |
\bf UIObject |
Global instance (if any): |
uiText |
Used in optional component: |
Part of main VMD code |
The particular UIObject which is responsible for getting text commands
from the user, parsing them, and executing them. Each time it is requested
to do so, this object will check to see if the user has entered a line of
text at the VMD prompt, and if so, this will read in the command,
break it up into the individual words, and determine what action is being
requested.
Every action in VMD which the user can request to have performed has a
corresponding Command object associated with it, and a text command
representation.
Each text command consists of N separate words separated by
whitespace, with the first word in the command used to distinguish between
different types of commands.
With each word there is an associated callback
function which is called when a text command is read in and the first word
is found in the list.
This object can also be directed to read commands from a file, and to echo
text commands to the console.
UIText is able to use the Tcl library, if available, to parse the
text commands and to provide sophisticated interpreted script capabilities
such as control loops, variable substitution, if-then-else constructs, and
user-defined subroutines and functions. If Tcl is not available, this
object will still function, but only the basic VMD commands will be
understood.
- NameList<TextCallback *> textProcessors - a list of all the
words which this object understands as the first word in a specific command,
and the callback function to call when a command with the starting word is
entered. TextCallback is a typedef for the callback function, as
defined in the file Command.h.
- int needPrompt - whether or not the prompt needs to be
printed the next time it is possible to do so.
- Stack<FILE *> input_files - a stack containing the FILE
structures for the files to read commands from. When a new file is opened
for reading, the currently open file is pushed down on the stack and the
new file is put at the top of the stack. When the end of the file is
reached, the stack is popped and reading from the new top file is resumed.
In this way files may be read in a nested fashion. When the stack is
empty, input is read from standard input.
- int doEcho - flag to indicate if text commands should be
echoed back to the console after they have been entered (even if from a
file or from the console).
- Inform txtMsgEcho - the Inform object to use for
echoing commands.
- float delay - the amount of time to wait (in seconds) before
attempting to read the next command. Once the waiting period is over, this
is set to zero.
- int num_commands(void) - the number of words which this
object understands as the first word in a command.
- char *word(int) - the Nth word that this object understands
as the first word in a command.
- void add_command(char *, TextCallback *) - adds a new word
to the UIText vocabulary, and registers the given function as the
callback for that word. If the word is already known, this does nothing.
- int process_command(int argc, char **argv) - given a tokenized
text command (one that has been broken up into `argc' individual words, with
the words in the `argv' array), this routine checks the first word to see
if it is understood, and calls the proper callback function or prints an
error message.
- void read_from_file(char *) - instructs this object to read
text commands from the given file until the end-of-file is reached.
- void wait(float) - instructs this object to wait for the given
number of seconds before attempting to read in the next text command.
- int echo(void) - returns the current echoing status.
- void echo(int yn) - turns on/off echoing of text commands.
- virtual int check_event(void) - checks to see if a text
command has been entered at the console or is available from a file. If so,
this reads in the string, and queues a `TextEvent' command (which is a
subclass of Command) containing the string.
- virtual int act_on_command(int, Command *, int) - called
after a text event command is executed. This will take the text command
string in the text event, break it into tokens, and if the first word
is understood this will call the proper callback function. If this first
word is not understood, or the callback function returns an error code,
this will print an error message.
In the constructor for this object, first the code for the `TextEvent'
command is registered as a command this object is interested in, and then
all the words this object can understand (with their callback functions)
are added to the object's internal list. Each time a new word is added
to the VMD vocabulary, a new line must be added in this section to add
the callback function (see the discussion of Command, section
27.1). The callback functions themselves should be declared in
the Cmd*.h files, and defined in the Cmd*.C files.
When a text command is actually to be executed, is it broken into an argc,
argv tokenized format, and given to the process_command routine. This
searches for the first word in the internal list of known words, and calls
the callback function with the argc, argv pair, and also the
CommandQueue object to use for queuing new commands as well as the ID
of this UIObject.
In the case where Tcl is being used, there is a slightly different order to
these events. After a string is read, it is given to the Tcl evaluation
routine, which checks it for special Tcl commands or for VMD commands.
When VMD commands are seen, Tcl will tokenize the command itself and call
a particular Tcl-tailored callback function. This callback function is
registered with Tcl for every word in the VMD vocabulary. In this Tcl
callback function, the first word is checked, and the regular text callback
function is called.
The reading of commands from files should be converted from the stdio
style I/O to the use of the streams library.
Next: Tracker objects
Up: User interface objects
Previous: UIObject
  Contents
vmd@ks.uiuc.edu