Next: UIText
Up: User interface objects
Previous: Mouse
  Contents
Subsections
UIObject
Files: |
UIObject.h, UIObject.C |
Derived from: |
none |
Global instance (if any): |
none |
Used in optional component: |
Part of main VMD code |
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.
- 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.
- 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.
- 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 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.
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.
Next: UIText
Up: User interface objects
Previous: Mouse
  Contents
vmd@ks.uiuc.edu