GetMouse
Retrieves the status of the mouse pointing device
Syntax
`
Declare Function GetMouse ( ByRef x As Long, ByRef y As Long, ByRef wheel As Long = 0, ByRef buttons As Long = 0, ByRef clip As Long = 0 ) As Long
Declare Function GetMouse ( ByRef x As LongInt, ByRef y As LongInt, ByRef wheel As LongInt = 0, ByRef buttons As LongInt = 0, ByRef clip As LongInt = 0 ) As Long
`
Usage
`
result = GetMouse (x, y [, [ wheel ] [, [ buttons ] [, [ clip ]]]])
`
Parameters
`x`
x coordinate value
`y`
y coordinate value
`wheel`
scroll wheel value
`buttons`
button status
`clip`
clip status
Return Value
`0` on success, or `1` on error (for example because the mouse is outside the graphic window) or on failure. (sets a runtime error)
Description
`GetMouse` retrieves the mouse position and buttons status; information is returned in the variables passed to this function by reference. If a mouse is not available, all variables will contain the `-1` value.
If in console mode, the `x` and `y` coordinates are the character cell coordinates the mouse is currently on; the upper left corner of the screen is at coordinates `0, 0`. If the mouse moves out of the console window, `GetMouse` returns the last coordinate on the window that the mouse was on. If in console mode and fullscreen, the scroll wheel value is not returned.
If in graphics mode, `x` and `y` will always be returned in pixel coordinates still relative to the upper left corner of the screen, which is at 0,0 in this case; custom coordinates system set via `View` or `Window` do not affect the coordinates returned by `GetMouse`.
If the mouse runs off the graphic window, all values are set to `-1` and the return value of the function is set to `1`. This may result in misinterpretation for the buttons and wheel if the return value of the function is not also tested.
`Wheel` is the mouse wheel counter; rotating the wheel away from you makes the count to increase, rotating the wheel toward you makes it to decrease. At program startup or when a new graphics mode is set via `Screen (Graphics)`, wheel position is reset to 0. FreeBASIC may not always support mouse wheels for a given platform, in which case 0 is always returned.
`Buttons` stores the buttons status as a bitmask: bit 0 is set if left mouse button is down; bit 1 is set if right mouse button is down; bit 2 is set if middle mouse button / wheel is down.
`Clip` stores the mouse clipping status; if `1`, the mouse is currently clipped to the graphics window; if `0`, the mouse is not clipped.
The error code returned by `GetMouse` can be checked using `Err` in the next line. The function version of `GetMouse` returns directly the error code as a 32 bit `Long`.
Warning: When the flag GFX_SHAPED_WINDOW is set (see `ScreenRes`), `GetMouse` is only active in any colored area, ie there where color <> RGBA(255, 0, 255, alpha).
Example
`
Dim As Long x, y, buttons, res
' Set video mode and enter loop
ScreenRes 640, 480, 8
Do
' Get mouse x, y and buttons. Discard wheel position.
res = GetMouse (x, y, , buttons)
Locate 1, 1
If res <> 0 Then '' Failure
#ifdef __FB_DOS__
Print "Mouse or mouse driver not available"
#else
Print "Mouse not available or not on window"
#endif
Else
Print Using "Mouse position: ###:### Buttons: "; x; y;
If buttons And 1 Then Print "L";
If buttons And 2 Then Print "R";
If buttons And 4 Then Print "M";
Print " "
End If
Loop While Inkey = ""
End
`
`
'Example 2: type-union-type structure
Type mouse
As Long res
As Long x, y, wheel, clip
Union
buttons As Long
Type
Left:1 As Long
Right:1 As Long
middle:1 As Long
End Type
End Union
End Type
Screen 11
Dim As mouse m
Do
m.res = GetMouse( m.x, m.y, m.wheel, m.buttons, m.clip )
ScreenLock
Cls
Print Using "res = #"; m.res
Print Using "x = ###; y = ###; wheel = +###; clip = ##"; m.x; m.y; m.wheel; m.clip
Print Using "buttons = ##; left = #; middle = #; right = #"; m.buttons; m.left; m.middle; m.right
ScreenUnlock
Sleep 10, 1
Loop While Inkey = ""
`
Dialect Differences

- Not available in the -lang qb dialect unless referenced with the alias `__Getmouse`. The variables passed must also be of type `Long` instead of `Integer`.

Platform Differences

- On Win32, scroll wheel changes are not guaranteed to be detected in full-screen console mode. Confirmed on WinXP: In windowed mode, mouse wheel changes are seen, but in full-screen console mode they are not.
- In DOS, the "clip" value has no relevance. Additionally the wheel and middle button will not work unless supported and enabled by the mouse driver. See also FaqDOS.

Differences from QB

- New to FreeBASIC

See also

- `ScreenRes` setting graph mode by resolution
- `Screen (Graphics)` setting mode the QB-like way
- `SetMouse`
- `MultiKey`
- `GetJoystick`
- `Event`
- `ScreenEvent`