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

