Mouse

This command does for your resident rodent what KEYBOARD does for your keyboard—lets you make things happen automatically. Of course, just as using KEYBOARD doesn’t actually depress the keys, MOUSE doesn’t physically move or click your real mouse—it just makes it seem like you did.

Usage

MOUSE [ CLICK | DBLCLICK ] [ AT nRow, nCol ]
      [ DRAG TO nEndRow1, nEndCol1
        [, nEndRow2, nEndCol2 ... ] ]
      [ PIXELS ] [ WINDOW WindowName ]
      [ LEFT | MIDDLE | RIGHT ]
      [ ALT ] [ CONTROL ] [ SHIFT ]

MOUSE is a pretty versatile command. You can use it to position the mouse, click or double-click any button, or drag the mouse. The syntax diagram doesn’t make it clear, however, that you have to do at least one of those things. MOUSE, by itself, gives you a syntax error. You need to include one of the first three options (or two or all three of them).

If you include both AT and CLICK or DBLCLICK, the mouse is positioned at the specified point, then clicked. Similarly, AT with DRAG positions the mouse before dragging it. You can specify more than one point to drag to and sure enough, the mouse moves to each point in sequence. The only situation in which this makes sense is when you have things happening in DragOver events.

How does MOUSE know whose coordinate system to use for the points you specify? By default, it measures things based on the main Visual FoxPro window using foxels. Specify PIXELS to measure in pixels instead. Use the WINDOW clause to tell MOUSE to measure relative to a different window. One cool thing is to use WINDOW (WONTOP()) so things happen in the active window.

In VFP 3 and VFP 5, when you use the WINDOW clause, the title bar is included in the window, so (0,0) is not the first point inside the window, but something above and to the left of it. In VFP 6 and later, the title bar no longer counts.

The last two lines of syntax let you specify which button is clicked and whether any of the modifier keys should be sent with the click. (Check out MouseDown and MouseUp to see what you can do with the keys.)

In VFP 3, two of the optional keywords are messed up. MIDDLE generates an error in that version. When VFP 3 came out, few users had three-button mice, so MIDDLE was no big loss. The second problem is only a documentation bug. The docs for VFP 3 say to use CTRL to have the Ctrl button "pressed" with your click. Nope, it's CONTROL instead. Bad choice, since other parts of the language (KEYBOARD, in particular) use CTRL, and that's what it says on our keyboards. Both problems are fixed in later versions, but it would have been nicer if they'd used the same keyword as everywhere else.

So what do you do with this command, anyway? You make things happen. Its obvious application is self-running demos. MOUSE isn’t quite as useful in that situation as you’d expect because it can’t get to the menu, but it’s still handy for clicking on items, dragging things and the like. MOUSE is also useful in builders, to let you bring things to the top or select a bunch of items, although the need for it decreases as more and more objects are exposed at design-time.

Example

* Say we've selected some objects and used ASELOBJ() to
* store references to them in aObjs. Later, we can reselect
* them.
LOCAL nCnt, nTitleSpace, nBorderSpace

* We need to add space for the title bar of both the Form
* Designer and the form itself vertically, and the borders of
* the Form Designer horizontally.

nTitleSpace = 2 * SYSMETRIC(9)
nBorderSpace = 2 * SYSMETRIC(3)

MOUSE CLICK AT -1,-1 WINDOW (WONTOP())  && To clear selections
FOR nCnt = 1 TO ALEN(aObjs,1)
   MOUSE CLICK AT aObjs[nCnt].Top + nTitleSpace , ;
                  aObjs[nCnt].Left + nBorderSpace ;
         WINDOW (WONTOP()) PIXELS SHIFT
ENDFOR

See Also

Click, DblClick, Keyboard, MCol(), MiddleClick, MouseDown, MouseUp, MouseMove, MRow(), RightClick