Description

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

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:

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

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 selection mode.

The Mouse is also used to provide a customizable pop-up menu when the third button is pressed. This menu contains selectable items, separators, and submenus. There are several `standard' selections in the popup menu, and there are text commands available which allow the user to add their own submenus and pop-up menu items. Thus, the user can customize their own user interface. There are Command objects which call routines within the Mouse object to add these items. The entire definition of the pop-up menu is contained within a member object PopupMenu. When the third button is pressed, the definition of this pop-up menu is given to the DisplayDevice specified in the constructor of Mouse (via virtual functions there for handling pop-up menus), and the virtual function ni DisplayDevice which activates the pop-up menu is called to allow an item to be selected.

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 UIList, 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.