Up: User interface objects
The Mouse class provides all the capabilities to provide a 2D
pointer for a particular DisplayDevice. Mouse will use
virtual functions with DisplayDevice to determine when a mouse
button has been pressed, and where it is located. Based on this, the
Mouse will rotate, translate, or scale the objects in the current
Scene. It can also be used to `pick' items, by clicking one
of the mouse buttons while the cursor is positioned over the item.
Finally, it is used to activate and choose from a pop up menu.
Mouse is derived from UIObject, and is one of the main
user interface methods in VMD (along with the text console, the GUI,
the 3D pointers, and any external command input programs).
|Global instance (if any):
|Used in optional component:
||Part of main VMD code
It is assumed the Mouse has three buttons, left, middle, and
right. The right button is always used to active the pop-up menu, while
the other two are used to apply transformations to the current
Scene. The left and middle buttons are also used to select
items. For some things, you can only click on them (press button +
release) for something useful to happen. For other things, you can
select them (press button), pull them (move the mouse while the
button is held down), and release. The Mouse will issue commands
to do the button presses, mouse motion, and button releases associated
with picking objects.
The Mouse is always in one of several modes, which are
changed by various means (text commands, pop-up menu options, or
keyboard shortcuts). These modes are:
Note that clicking on an item with the left button while the mouse is NOT
in a pick mode is equivalent to clicking-and-releasing the button with
the mouse in the atom select mode. Clicking on an item with the middle
button in these same situations is the same as using the left button, but
instead the picking operation is done as if the mouse were in the bond
- Rotation mode: When held down, the left button will
rotate things about the X or Y axis as the mouse is moved, in a
`virtual trackball' method. The middle button is used to rotate
about the Z axis (perpendicular to the screen).
- Translation mode: The left button will move the objects
in the X-Y plane; the middle button will move things in the Z
direction (toward or away from the viewer).
- Scaling mode: The left button, when held down and the mouse
moved left-right, will enlarge or shrink the scene. The middle button
will do the same thing, but with a larger scaling factor (so the
left is for fine tuning, the middle is for coarse-grain scaling).
- Light mode: This acts just like rotation mode, but instead
of rotating all the displayed objects, the mouse will only rotate the
position of one of the light sources. When setting this mode, you also
select which light to rotate (0 ... 3).
- Pick mode: While the mouse can be used to select certain
items while it is in the other modes, there are certain special
pick-and-drag operations in VMD which can only be done if the
pointer is put in a special picking mode. By default there
are five picking modes, which are numbered 0 ... N-1, in this order:
query, select atom, select bond, select angle, or select dihedral.
Picking on an object when in a non-picking mode does not allow you
move the mouse around any while the item is selected; in that case,
when the button is pressed, if an item is selected it acts just as
if the button were immediately released. But if the mouse is in a
special picking mode, then when the button is pressed and an item is
selected, you can move the mouse around while the button is held down
and have extra actions be taken during the motion. For example, there
are special modes which are used to add perturbative forces to atoms; to
to do this, the mouse must be placed in the atom-tug mode. When setting
the mouse into a pick mode, you also must select which mode it is to
Finally, the Mouse contains the ability to check the keyboard for
special events as well as the 2D pointing device. The Mouse maintains
a list of user-customizable keyboard shortcuts, which associate a
specific keypress (i.e. 'A' or 'r') with a text command. When that key is
pressed while the Mouse is in the graphics display window, the
associated text command is executed as if the entire command had been entered
at the console prompt.
There is one global instance of the Mouse class, mouse. It
is created after the global DisplayDevice, and
CommandQueue objects are created. Note that if a `default'
DisplayDevice is created, the Mouse will not be able to check
for events, determine a pointer position, etc, and so will do nothing.
- Mouse::Mouse(CommandQueue *, DisplayDevice *)
The first argument is the CommandQueue object which this
class should use when creating new Commands to be executed, and
the second argument is the DisplayDevice which this class should
be a 2D pointer for. The DisplayDevice must provide all the
device-specific information for the Mouse, such as the X,Y
location of the pointer, the state of the mouse buttons, and the
ability to post and activate a pop-up menu.
The MoveMode enumeration lists the possible mouse modes. These are:
- DisplayDevice *dispDev - display to use for device-specific
functionality, such as checking for events, determining the pointer
- MoveMode moveMode - current mode the mouse is in.
- int activePickMode - if the current mode is PICKING,
this variable indicates which pick mode is active.
- int pickInProgress - if this is zero, no picking operation is
currently in progress (which means that it is NOT that case that a
mouse button has been pressed and selected something, with the mouse button
still left down). If something is currently being selected with the mouse
and the button is still down, this flag indicates which button is being
used. In fact, pickInProgress = pick-button + 1.
- int moveObj - if the current mode is LIGHT, this
variable indicates which light to rotate.
- int currX, currY, oldX, oldY - current and previous positions
of the pointer, measured in pixels from the lower-left corner of the
global display screen.
- float transInc, rotInc, scaleInc - the amount of change to
apply each time a translation, rotation, or scaling operation is requested.
- float xRotVel, yRotVel, zRotVel - current angular velocity
of the scene; when the system has angular velocity, even if no event is
generated by the Mouse, the current scene will be rotated by the
angular velocity amount.
- NameList<NameList<char *> *> userMenuList - a list of
NameList objects which hold the definitions of user menus. Each name
in userMenuList is the title of a submenu to be added to the main
pop-up menu, with an associated list of names which define the submenu.
This is used to store the user-defined pop-up menu commands.
- <NameList<char *> *mainUserMenu - this is the one
user-controlled menu which is always added to the main menu. The user can
add two types of items to the main menu:
- Single commands, which are put into the mainUsermenu list.
- Submenu commands, which are put into a new submenu with a specified
name that is added to the main menu. This allows for grouping of related
commands under a separate submenu in the main menu.
- NameList<char *> userKeys - in a manner very similar to adding
new menu items, the user can assocate keyboard shortcuts (or hotkeys)
with a specified text command. This list stores the keystrokes, and
the text commands associated with those keystrokes.
- int mouse_moved(int b1Down, int b2Down) - performs the
necessary action when the mouse is moved while a button is pressed. The
arguments indicate which buttons are currently down.
- void create_key_commands(void) - creates the initial
list of keyboard shortcuts; this is only done when the Mouse is
- void stop_rotation(void) - sets the current angular velocity
- int x(void) - returns the current x position of the
Mouse, as measured from the lower-left corner. This just calls a
similar (but virtual) function in DisplayDevice.
- int y(void) - as as x(), but for the vertical position.
- int button_down(int) - returns the current state of the
- int move_mode(MoveMode, int = 0) - sets the current mouse
mode. If the new mode is PICKING or LIGHT, the second argument
must be given to indicate which picking mode or light. Otherwise, the
second argument is ignored.
- MoveMode curr_move_mode(void) - returns current mode.
- char *move_mode_name(MoveMode) - returns a string describing
the specified mode.
- int curr_pick_mode(void) - returns current picking mode, or
-1 if the current mouse mode is not PICKING.
- int picking(void) - returns TRUE if somthing is being
pickied, or FALSE otherwise.
- int create_user_menu(char *label) - indicates that a new
user-customizable submenu should be added to the main menu, with the
given label. The new menu will be initially empty.
- int add_user_menu_item(char *text, char *txtcmd) - adds
a new user menu item to the main user submenu ... the name in the menu will
be `text', and the command executed when that menu option is
chosen is `txtcmd'.
- int add_user_menu_separator(void) - puts in a separator at the current end of the main user submenu.
- int add_user_submenu_item(char *submenu, char *text, char *txtcmd) - adds the command `txtcmd' to the submenu `submenu', under the
name of `text' in that submenu.
- int add_user_submenu_separator(char *submenu) - adds a
separator to the end of the given submenu.
- int add_user_key_command(char, const char *) - adds a new
keyboard shortcut (or replaces a previous one), for the given key.
- virtual void reset(void) - resets the user interface to the
initial state it was in when it was created.
- virtual int act_on_command(int, Commmand *, int) - this is
called each time a Command is executed that the Mouse has
expressed interest in hearing about. This will be when a mouse event
occurs, such as a mouse button press.
- virtual int check_event(void) - calls the necessary routines
in DisplayDevice to determine if a button has been pressed. If not,
then any angular velocity is used to rotate the current scene.
Once it is created and given the proper CommandQueue
and DisplayDevice, Mouse only needs to have its virtual
function check_event() called regularly. This is done in the main
event loop of VMD.
The Command objects which have the word `user' as their first word
control the customization of the pop-up menu and keyboard shortcuts.
When a new DisplayDevice is eventually developed to use X-Windows
and OpenGL, there will also need to be included routines there to post
and activate the pop-up menu and for all the virtual functions in
DisplayDevice which the Mouse uses. If this is done successfully
then Mouse should be completely device-independent. It may be
necessary (or preferred) to convert to the use of a pull-down menu in
the X-Windows case.
Up: User interface objects