Subsections

- 1 Constants, types and variables
- 2 Functions and procedures
  - 1 GetLastButtonPress
  - 2 GetLastButtonRelease
  - 3 GetMouseState
  - 4 HideMouse
  - 5 InitMouse
  - 6 LPressed
  - 7 MPressed
  - 8 RPressed
  - 9 SetMouseAscii
  - 10 SetMouseHideWindow
  - 11 SetMousePos
  - 12 SetMouseShape
  - 13 SetMouseSpeed
  - 14 SetMouseWindow
  - 15 SetMouseXRange
  - 16 SetMouseYRange
  - 17 ShowMouse

# 16 The MsMouse unit

mmouseex

The msmouse unit provides basic mouse handling under DOS (Go32v1 and Go32v2) Some general remarks about the msmouse unit:

- For maximum portability, it is advisable to use the mouse unit; that unit is portable across platforms, and offers a similar interface. Under no circumstances should the two units be used together.
- The mouse driver does not know when the text screen scrolls. This results in unerased mouse cursors on the screen when the screen scrolls while the mouse cursor is visible. The solution is to hide the mouse cursor (using HideMouse) when you write something to the screen and to show it again afterwards (using ShowMouse).
- All Functions/Procedures that return and/or accept coordinates of the mouse cursor, always do so in pixels and zero based (so the upper left corner of the screen is (0,0)). To get the (column, row) in standard text mode, divide both x and y by 8 (and add 1 if you want to have it 1 based).
- The real resolution of graphic modes and the one the mouse driver uses can differ. For example, mode 13h (320*200 pixels) is handled by the mouse driver as 640*200, so you will have to multiply the X coordinates you give to the driver and divide the ones you get from it by 2 in that mode.
- By default the msmouse unit is compiled with the conditional define MouseCheck. This causes every procedure/function of the unit to check the MouseFound variable prior to doing anything. Of course this is not necessary, so if you are sure you are not calling any mouse unit procedures when no mouse is found, you can recompile the mouse unit without this conditional define.
- You will notice that several procedures/functions have longint sized parameters while only the lower 16 bits are used. This is because FPC is a 32 bit compiler and consequently 32 bit parameters result in faster code.

# 1 Constants, types and variables

The following constants are defined (to be used in e.g. the GetLastButtonPress call).

     LButton = 1; {left button}
     RButton = 2; {right button}
     MButton = 4; {middle button}

The following variable exist:

      MouseFound: Boolean;

it is set to `True` or `False` in the unit's initialization code.

# 2 Functions and procedures

##
1 GetLastButtonPress

Declaration
  `Function GetLastButtonPress (Button: Longint; Var x,y:Longint) : Longint;`

  ``

Description

  `GetLastButtonPress` Stores the position where `Button` was last pressed in `x` and `y` and returns the number of times this button has been pressed since the last call to this function with `Button` as parameter. For `Button` you can use the `LButton`, `RButton` and `MButton` constants for resp. the left, right and middle button. With certain mouse drivers, checking the middle button when using a two-button mouse to gives and clears the stats of the right button.

Errors
  None.
See also
  GetLastButtonRelease

Example

      {example for GetLastButtonPress and GetLastButtonRelease}

      Uses MsMouse, Crt;

      Var x, y, times: Longint;
          c: Char;

      Begin
        If MouseFound Then
          Begin
            ClrScr;
            ShowMouse;
            Writeln('Move the mouse and click the buttons (press escape to quit).');
            Writeln('Press the L-key to see the stats for the left button.');
            Writeln('Press the R-key to see the stats for the right button.');
            Writeln('Press the M-key to see the stats for the middle button.');
            GotoXY(1,19);
            Write('Since the last call to GetLastButtonPress with this button as parameter, the');
            GotoXY(1,22);
            Write('Since the last call to GetLastButtonRelease with this button as parameter, the');
            Repeat
              If Keypressed Then
                Begin
                  c := UpCase(Readkey);
                  Case c Of
                    'L':
                      Begin
                        GotoXY(1, 20);
                        ClrEol;
                        times := GetLastButtonPress(LButton, x, y);
                        Write('left button has been pressed ',times,
                                ' times, the last time at (',x,',',y,')');
                        times := GetLastButtonRelease(LButton, x, y);
                        GotoXY(1,23);
                        ClrEol;
                        Write('left button has been released ',times,
                                ' times, the last time at (',x,',',y,')')
                      End;
                    'R':
                      Begin
                        GotoXY(1, 20);
                        ClrEol;
                        times := GetLastButtonPress(RButton, x, y);
                        Writeln('right button has been pressed ',times,
                                ' times, the last time at (',x,',',y,')');
                        times := GetLastButtonRelease(RButton, x, y);
                        GotoXY(1,23);
                        ClrEol;
                        Write('right button has been released ',times,
                                ' times, the last time at (',x,',',y,')')
                      End;
                    'M':
                      Begin
                        GotoXY(1, 20);
                        ClrEol;
                        times := GetLastButtonPress(MButton, x, y);
                        Writeln('middle button has been pressed ',times,
                                ' times, the last time at (',x,',',y,')');
                        times := GetLastButtonRelease(MButton, x, y);
                        GotoXY(1,23);
                        ClrEol;
                        Write('middle button has been released ',times,
                                ' times, the last time at (',x,',',y,')')
                      End
                  End
                End;
            Until (c = #27); {escape}
            While KeyPressed do ReadKey;
            GotoXY(1,24);
            HideMouse
          End
      End.

##
2 GetLastButtonRelease

Declaration
  `Function GetLastButtonRelease (Button: Longint; Var x,y:Longint) : Longint;`

  ``

Description

  `GetLastButtonRelease` stores the position where `Button` was last released in `x` and `y` and returns the number of times this button has been released since the last call to this function with `Button` as parameter. For button you can use the `LButton`, `RButton` and `MButton` constants for resp. the left, right and middle button. With certain mouse drivers, checking the middle button when using a two-button mouse to gives and clears the stats of the right button.

Errors
  None.
See also
  GetLastButtonPress

For an example, see GetLastButtonPress.

##
3 GetMouseState

Declaration
  `Procedure GetMouseState (Var x, y, buttons: Longint);`

  ``

Description

  `GetMouseState` Returns information on the current mouse position and which buttons are currently pressed. `x` and `y` return the mouse cursor coordinates in pixels. `Buttons` is a bitmask. Check the example program to see how you can get the necessary information from it.

Errors
  None.
See also
  LPressed, MPressed, RPressed, SetMousePos

Example

      {example for GetMouseState, IsLPressed, IsRPressed and IsMPressed}

      Uses MsMouse, Crt;

      Var X, Y, State: Longint;

      Begin
        If MouseFound Then
          Begin
            ClrScr;
            ShowMouse;
            GotoXY(5,24);
            Write('Left button:');
            GotoXY(30,24);
            Write('Right button:');
            GotoXY(55,24);
            Write('Middle button:');
            While KeyPressed do Readkey; {clear keyboard buffer}
            Repeat
               GetMouseState(x, y, State);
               GotoXY(20, 22);
               Write('X: ',x:5,' (column: ',(x div 8):2,')  Y: ',y:5, ' (row: ',(y div 8):2,')');
               GotoXY(18, 24); {left button}
               If (State and LButton) = LButton Then
      {or: "If LPressed Then". If you use this function, no call to GetMouseState
       is necessary}
                 Write('Down')
               Else
                 Write('Up  ');
               GotoXY(44, 24); {right button}
               If (State and RButton) = RButton Then
      {or: "If RPressed Then"}
                 Write('Down')
               Else
                 Write('Up  ');
               GotoXY(70, 24); {middle button}
               If (State and MButton) = MButton Then
      {or: "If MPressed Then"}
                 Write('Down')
               Else
                 Write('Up  ')
            Until KeyPressed;
            HideMouse;
            While KeyPressed Do Readkey
          End
      End.

##
4 HideMouse

Declaration
  `Procedure HideMouse ;`

  ``

Description

  `HideMouse` makes the mouse cursor invisible. Multiple calls to HideMouse will require just as many calls to ShowMouse to make the mouse cursor visible again.

Errors
  None.
See also
  ShowMouse, SetMouseHideWindow

For an example, see ShowMouse.

##
5 InitMouse

Declaration
  `Procedure InitMouse ;`

  ``

Description

  `InitMouse` Initializes the mouse driver sets the variable `MouseFound` depending on whether or not a mouse is found. This is Automatically called at the start of your program. You should never have to call it, unless you want to reset everything to its default values.

Errors
  None.
See also
  `MouseFound` variable.

Example

      Program Mouse1;

      {example for InitMouse and MouseFound}

      Uses MsMouse;

      Begin
        If MouseFound Then
          Begin
           {go into graphics mode 13h}
            Asm
              movl $0x013, %eax
              pushl %ebp
              int $0x010
              popl %ebp
            End;
            InitMouse;
            ShowMouse; {otherwise it stays invisible}
            Writeln('Mouse Found! (press enter to quit)');
            Readln;
           {back to text mode}
            Asm
              movl $3, %eax
              pushl %ebp
              int $0x010
              popl %ebp
            End
          End
      End.

##
6 LPressed

Declaration
  `Function LPressed : Boolean;`

  ``

Description

  `LPressed` returns `True` if the left mouse button is pressed. This is simply a wrapper for the GetMouseState procedure.

Errors
  None.
See also
  GetMouseState, MPressed, RPressed

For an example, see GetMouseState.

##
7 MPressed

Declaration
  `Function MPressed : Boolean;`

  ``

Description

  `MPressed` returns `True` if the middle mouse button is pressed. This is simply a wrapper for the GetMouseState procedure.

Errors
  None.
See also
  GetMouseState, LPressed, RPressed

For an example, see GetMouseState.

##
8 RPressed

Declaration
  `Function RPressed : Boolean;`

  ``

Description

  `RPressed` returns `True` if the right mouse button is pressed. This is simply a wrapper for the GetMouseState procedure.

Errors
  None.
See also
  GetMouseState, LPressed, MPressed

For an example, see GetMouseState.

##
9 SetMouseAscii

Declaration
  `Procedure SetMouseAscii (Ascii: Byte);`

  ``

Description

  `SetMouseAscii` sets the `Ascii` value of the character that depicts the mouse cursor in text mode. The difference between this one and SetMouseShape, is that the foreground and background colors stay the same and that the Ascii code you enter is the character that you will get on screen; there's no XOR'ing.

Errors
  None
See also
  SetMouseShape

Example

      {example for SetMouseAscii}

      {warning: no error checking is performed on the input}

      Uses MsMouse, Crt;

      Var ascii: Byte;
          x,y: Longint;

      Begin
        If MouseFound Then
          Begin
            ClrScr;
            Writeln('Press any mouse button to quit after you''ve entered an Ascii value.');
            Writeln;
            Writeln('ASCII value of mouse cursor:');
            ShowMouse;
            Repeat
              GotoXY(30,3);
              ClrEol;
              Readln(ascii);
              SetMouseAscii(ascii)
            Until (GetLastButtonPress(LButton,x,y) <> 0) Or
                  (GetLastButtonPress(RButton,x,y) <> 0) Or
                  (GetLastButtonPress(MButton,x,y) <> 0);
            HideMouse
          End;
      End.

##
10 SetMouseHideWindow

Declaration
  `Procedure SetMouseHideWindow (xmin,ymin,xmax,ymax: Longint);`

  ``

Description

  `SetMouseHideWindow` defines a rectangle on screen with top-left corner at (`xmin,ymin`) and botto-right corner at (`xmax,ymax`),which causes the mouse cursor to be turned off when it is moved into it. When the mouse is moved into the specified region, it is turned off until you call `ShowMouse` again. However, once you've called ShowMouse, you'll have to call `SetMouseHideWindow` again to redefine the hide window... This may be annoying, but it's the way it's implemented in the mouse driver. While `xmin, ymin, xmax` and `ymax` are Longint parameters, only the lower 16 bits are used.

  Warning: it seems Win98 SE doesn't (properly) support this function, maybe this already the case with earlier versions too!

Errors
  None.
See also
  ShowMouse, HideMouse

Example

      {example for SetMouseHideWindow}

      {warning: when the mouse is moved into the specified region, it is turned off
       until you call ShowMouse again. However, when you've called ShowMouse,
       you'll have to call SetMouseHideWindow again to redefine the hide window...
       It's not our fault, that's the way it's implemented in the mouse driver.

       Below you can find an example of how to define a "permanent" hide region
       with the cursor showing up again when you move it out of the region

       Note: the mouse functions are zero-based, GotoXY is 1-based}

      Uses MsMouse, Crt;

      Var x, y, buttons: Longint;
          MouseOn: Boolean;

      Begin
        If MouseFound Then
          Begin
            ClrScr;
            For y := 1 to 25 Do
              Begin
                GotoXY(20,y);
                Write('|');
                GotoXY(60,y);
                Write('|');
              End;
            MouseOn := true;
            GotoXY(30, 24);
            Writeln('Press any key to quit');
            ShowMouse;
            SetMousePos(1,1);
            While KeyPressed Do Readkey;
            Repeat
              GetMouseState(x,y,buttons);
              If Not(MouseOn) And
                ((x <= 19*8) or (x >= 59*8)) Then
                Begin
                  ShowMouse;
                  MouseOn := true
                End;
              If MouseOn And (x > 19*8) And (x<59*8) Then
                Begin
                  SetMouseHideWindow(20*8,0,60*8,25*8);
                  MouseOn := false
                End;
            Until KeyPressed;
            While KeyPressed Do Readkey;
            HideMouse
          End
      End.

##
11 SetMousePos

Declaration
  `Procedure SetMousePos (x,y:Longint);`

  ``

Description

  `SetMosusePos` sets the position of the mouse cursor on the screen. `x` is the horizontal position in pixels, `y` the vertical position in pixels. The upper-left hand corner of the screen is the origin. While `x` and `y` are longints, only the lower 16 bits are used.

Errors
  None.
See also
  GetMouseState

Example

      {example for SetMousePos}

      Uses MsMouse, Crt;

      Begin
        If MouseFound Then
          Begin
            ShowMouse;
            While KeyPressed do ReadKey;
            Repeat
              SetMousePos(Random(80*8), Random(25*8));
              delay(100);
            Until Keypressed;
            HideMouse;
            While KeyPressed do ReadKey;
          End;
      End.

##
12 SetMouseShape

Declaration
  `Procedure SetMouseShape (ForeColor,BackColor,Ascii: Byte);`

  ``

Description

  `SetMouseShape` defines how the mouse cursor looks in textmode The character and its attributes that are on the mouse cursor's position on screen are XOR'ed with resp. `ForeColor`, `BackColor` and `Ascii`. Set them all to 0 for a "transparent" cursor.

Errors
  None.
See also
  SetMouseAscii

Example

      {example for SetMouseShape}

      {warning: no error checking is performed on the input}

      {the Ascii value you enter is XOR'ed with the Ascii value of the character
       on the screen over which you move the cursor. To get a "transparent" cursor,
       use the Ascii value 0}

      Uses MsMouse, Crt;

      Var ascii, fc, bc: Byte;
          x,y: Longint;

      Begin
        If MouseFound Then
          Begin
            ClrScr;
            Writeln('Press any mouse button to quit after you''ve entered a sequence of numbers.');
            Writeln;
            Writeln('ASCII value of mouse cursor:');
            Writeln('Forground color:');
            Writeln('Background color:');
            ShowMouse;
            Repeat
              GotoXY(30,3);
              ClrEol;
              Readln(ascii);
              GotoXY(18,4);
              ClrEol;
              Readln(fc);
              GotoXY(19,5);
              ClrEol;
              Readln(bc);
              SetMouseShape(fc, bc, ascii)
            Until (GetLastButtonPress(LButton,x,y) <> 0) Or
                  (GetLastButtonPress(RButton,x,y) <> 0) Or
                  (GetLastButtonPress(MButton,x,y) <> 0);
            HideMouse
          End;
      End.

##
13 SetMouseSpeed

Declaration
  `Procedure SetMouseSpeed (Horizontal, Vertical: Longint);`

  ``

Description

  `SetMouseSpeed` sets the mouse speed in mickeys per 8 pixels. A mickey is the smallest measurement unit handled by a mouse. With this procedure you can set how many mickeys the mouse should move to move the cursor 8 pixels horizontally of vertically. The default values are 8 for horizontal and 16 for vertical movement. While this procedure accepts longint parameters, only the low 16 bits are actually used.

Errors
  None.
See also

Example

      Uses MsMouse, Crt;

      Var hor, vert: Longint;
          x, y: Longint;

      Begin
        If MouseFound Then
          Begin
            ClrScr;
            Writeln('Click any button to quit after you''ve entered a sequence of numbers.');
            Writeln;
            Writeln('Horizontal mickey''s per pixel:');
            Writeln('Vertical mickey''s per pixel:');
            ShowMouse;
            Repeat
              GotoXY(32,3);
              ClrEol;
              Readln(hor);
              GotoXY(30,4);
              ClrEol;
              Readln(vert);
              SetMouseSpeed(hor, vert);
            Until (GetLastButtonPress(LButton,x,y) <> 0) Or
                  (GetLastButtonPress(RButton,x,y) <> 0) Or
                  (GetLastButtonPress(MButton,x,y) <> 0);
          End
      End.

##
14 SetMouseWindow

Declaration
  `Procedure SetMouseWindow (xmin,ymin,xmax,ymax: Longint);`

  ``

Description

  `SetMousWindow` defines a rectangle on screen with top-left corner at (`xmin,ymin`) and bottom-right corner at (`xmax,ymax`), out of which the mouse cursor can't move. This procedure is simply a wrapper for the SetMouseXRange and SetMouseYRange procedures. While `xmin, ymin, xmax` and `ymax` are Longint parameters, only the lower 16 bits are used.

Errors
  None.
See also
  SetMouseXRange, SetMouseYRange

For an example, see SetMouseXRange.

##
15 SetMouseXRange

Declaration
  `Procedure SetMouseXRange (Min, Max: Longint);`

  ``

Description

  `SetMouseXRange` sets the minimum (`Min`) and maximum (`Max`) horizontal coordinates in between which the mouse cursor can move. While `Min` and `Max` are Longint parameters, only the lower 16 bits are used.

Errors
  None.
See also
  SetMouseYRange, SetMouseWindow

Example

      {example for SetMouseXRange, SetMouseYRange and SetMouseWindow}

      Uses MsMouse, Crt;

      Begin
        If MouseFound Then
          Begin
            SetMouseXRange(20*8,50*8);  {charracter width and height = 8 pixels}
            SetMouseYRange(10*8,15*8);

      {the two lines of code have exactly the same effect as
       SetMouseWindow(20*8,10*8,50*8,15*8)}

            Writeln('Press any key to quit.');
            ShowMouse;
            While KeyPressed Do ReadKey;
            Readkey;
            While KeyPressed Do ReadKey;
            HideMouse
          End
      End.

##
16 SetMouseYRange

Declaration
  `Procedure SetMouseYRange (Min, Max: Longint);`

  ``

Description

  `SetMouseYRange` sets the minimum (`Min`) and maximum (`Max`) vertical coordinates in between which the mouse cursor can move. While `Min` and `Max` are Longint parameters, only the lower 16 bits are used.

Errors
  None.
See also
  SetMouseXRange, SetMouseWindow

For an example, see SetMouseXRange.

##
17 ShowMouse

Declaration
  `Procedure ShowMouse ;`

  ``

Description

  `ShowMouse` makes the mouse cursor visible. At the start of your progam, the mouse cursor is invisible.

Errors
  None.
See also
  HideMouse,SetMouseHideWindow

Example

      {example for ShowMouse and HideMouse}

      Uses MsMouse;

      Begin
        ClrScr;
        If MouseFound Then
          Begin
            Writeln('Now you can see the mouse... (press enter to continue)');
            ShowMouse;
            Readln;
            HideMouse;
            Writeln('And now you can''t... (press enter to quit)');
            Readln
          End
      End.