FutureBasic Logo

<<    Index    >> FutureBasic 5

mouse <event>   function



Syntax:
clickType = mouse(0)
locationInfo = mouse(locationType)


Description:
If you have designated a mouse-event handling routine using the on mouse statement, then the mouse <event> functions return information about a mouse click event. Your mouse-event handling routine should check the mouse(0) function, and possibly the mouse(locationType) functions, each time your routine is called.
The mouse <event> functions will not report a mouse click that occurs inside an active control (such as a button or scrollbar), or in an edit field or picture field, or anywhere outside the active window's content region. Such mouse clicks are handled by other routines, such as your dialog-event handling routine (see the dialog function), or your menu-event handling routine (see the menu function).

mouse(0) function
The mouse(0) function indicates whether a single, double or triple-click occurred. It will usually return one of the following values:

Mouse(0)Description
_click1nDrag (-1)single click, and mouse is still down.
_click2nDrag (-2)double click, and mouse is still down.
_click3nDrag (-3)triple click, and mouse is still down.

In rare cases, the user may have time to both click the mouse and release it before your program detects the click. This can happen, for example, if your program runs a long time between successive calls to HandleEvents. In that case, mouse(0) may return one of the following values:

Mouse(0)Description
_click1 (1)single click, and mouse is already released.
_click2 (2)double click, and mouse is already released.
_click3 (3)triple click, and mouse is already released.

If you just want to detect the click, and you don't care whether the user released the mouse button before your mouse-event handling routine was called, then your routine can just check abs(mouse(0)), which will always return 1, 2 or 3.

mouse(locationType) functions
To detect where the mouse pointer was at the instant it was clicked, call the mouse(_lastMHorz) and mouse(_lastMVert) functions within your mouse-event handling routine. The values returned by mouse(_lastMHorz) and mouse(_lastMVert) are usually the same as those returned by mouse(_horz) and mouse(_vert) (see the mouse <position> functions), but they may be different, especially if the mouse is being moved quickly.
If mouse(0) returns a positive value (indicating that the mouse was both clicked and released before your mouse-event handling routine was called), then you may also be interested in the values returned by mouse(_releaseHorz) and mouse(_releaseVert). These values tell you where the mouse pointer was at the instant the mouse button was released. If mouse(0) returned a negative value, then mouse(_releaseHorz) and mouse(releaseVert) are meaningless.

mouse Window (Appearance Manager)
A new selector helps your program determine where the mouse is located:
wndNum = mouse(_mouseWindow)
...will return the FutureBasic window reference number of the window over which the mouse is positioned. The window does not need to be active when this is used.

Click Sequencing
FutureBasic reports a mouseclick event as soon as it can after the mouse button has been pressed down. If the user executes a double-click, FutureBasic interprets it first as a single-click event and then (once the second click happens) as a double-click event. Both "events" will be reported to your mouse-event handling routine. Similarly, if the user executes a triple-click, FutureBasic will first report a single-click event, then a double-click event, and finally a triple-click event.
You should take this into account when writing your mouse-event handling routine. The example program "doubleClick.BAS" handles single-clicks and double-clicks; like most well-designed programs, its interface is designed so that the effects of a single-click are included in the effects of a double-click.

Waiting for the Mouse Up
In most cases, FutureBasic will call your mouse-event handling routine while the mouse button is still being held down. But in some situations, your routine may need to track the mouse's motion until the button is released. You can use the Toolbox function fn STILLDOWN to determine when the user releases the mouse button.

See Also:
mouse(_down); mouse <position>; on mouse; HandleEvents