UIText

Files:	UIText.h, UIText.C
Derived from:	\bf UIObject
Global instance (if any):	uiText
Used in optional component:	Part of main VMD code

Description

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.

Constructors

• UIText::UIText(CommandQueue *)
  

Internal data structures

• 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.

Nonvirtual member functions

• 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 member functions

• 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.

Method of use

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.

Suggestions for future changes/additions

The reading of commands from files should be converted from the stdio style I/O to the use of the streams library.