Mouse

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

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.

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.

Constructors

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

Enumerations, lists or character name arrays

The MoveMode enumeration lists the possible mouse modes. These are:

• ROTATION.
• TRANSLATION.
• SCALING.
• LIGHT.
• PICKING.

Internal data structures

• DisplayDevice *dispDev - display to use for device-specific functionality, such as checking for events, determining the pointer position, etc.

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

Nonvirtual member functions

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

• void stop_rotation(void) - sets the current angular velocity to zero.

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

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

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

Method of use

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.

Suggestions for future changes/additions

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.