UIObject

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

Description

UIObject is the base class for each object in VMD which provides some form of user interface. There is a UIObject subclass for dealing with the text console, for the 2D pointer interface (the Mouse), and for the 3D user interface (currently in development). Also, each of the different GUI forms which appear on the screen are a separate UIObject.

VMD contains many different UIObject, each for the most part independent of the others. A UIObject has the ability to get input from the user on what that would like to do, and convert these into particular commands to do that action. These commands (embodied by different subclasses of the Command object) are put in a queue for execution. Each UIObject must also present some form of visual representation of the state of VMD to the user, which changes as different actions are performed. As commands are executed, each UIObject must be informed of what the action was, in order to update its display. No user interface component is capable of executing ALL the commands available in VMD, however, and conversely no user interface component is interested in hearing about all the different possible actions in VMD.

Each UIObject has the following characteristics:

• A list of the particular Command objects which are interesting to the UIObject. When it is initialized, each UIObject must call particular functions which store the list of commands which will require some change to the user interface when they are executed. This is usually done in the specialized constructor for the class derived from UIObject.

• A unique ID code, which is provided by the CommandQueue object with which the UIObject registers when it is created.

• A CommandQueue variable which is used by the UIObject to have Commands queued and executed.

The main UIObjects in VMD are all created in the routine VMDinitUI, in the file Global.C.

Constructors

• UIObject::UIObject(char *, CommandQueue *)
  The arguments are the name of the object, and the CommandQueue which this should use to register and queue Command objects for execution.

Internal data structures

• char *name - the name of the object; this is public so that it can be accessed by other objects in VMD.

• int myID - the ID code for this object, as returned by the CommandQueue.

• int uiOn - whether this object is active; if not, it will not check for events from the user.

• int maxCmds - the total number of commands which this object can possibly be interested in.

• char *doCmd - an array of flags which are used to indicate if a command is wanted or not.

• CommandQueue *cmdQueue - the CommandQueue that this object should use to queue and execute commands.

Nonvirtual member functions

• int addcommand(Command *) - adds the given Command instance to the end of the command queue. Returns success.

• int runcommand(Command *) - have the command queue execute the given command immediately. Returns the success of the command, or -1 if the command was queued for later execution.

• void command_wanted(int) - sets the proper flag in the doCmd array to indicate that the given command code is a command the UIObject is interested in.

• void command_not_wanted(int) - opposite of command_wanted.

• int id(void) - return the ID of this UIObject.

• int want_command(int) - return whether the given command is one this object is interested in.

Virtual member functions

• virtual int is_menu(void) - return whether this object is an on-screen menu form, or another type.

• virtual int is_on(void) - return whether the object is currently active.

• virtual void On(void) - turn on the UIObject.

• virtual void Off(void) - turn off the UIObject.

• virtual void move(int, int) - moves the UIObject the the given X,Y position on the screen, where X and Y are in pixels measured from the lower-left corner of the display. This may not be applicable to all UIObject's, if not is is ignorned.

• virtual void where(int &, int &) - return the position of the UIObject, if applicable.

• virtual void init(void) - initialize the user interface. This is called once at the beginning of VMD, after all the UIObjects have been created.

• virtual void reset(void) - resets the user interface object, forcing an update of all the informative displays, etc.

• virtual void update(void) - updates the display, for example for some visual items which much change each time the scene is redrawn. This is called in the main loop of VMD after all queued Commands have been executed, before the scene is actually rendered.

• virtual int act_on_command(int, Command *, int) - this is called after a command is executed, and it is seen that this UIObject is interested in that command. The first argument is the command code, the second the Command itself, and the third is the success of the command. This routine should check what the code is, and based on that update any visual or other such representation of the program to reflect the change caused by execution of the given command. Returns TRUE if this UIObject actually did something due to this command being executed.

• virtual int check_event(void) - checks whatever external interface is necessary to see if a new command from the user has been entered. If so, this routine creates a new Command object, and adds it to the queue.

Method of use

To create a new UIObject, you must do the following:

• In the constructor for the new class, call the routine command_wanted to indicate the commands you are interested in.

• Provide versions of at least the routines init, reset, update, act_on_command, and check_event.

• Add code to the VMDinitUI routine to have the UIObject created at startup.