Subsections

- 1 Constants, Types and Variables
  - 1 Constants
  - 2 Types
  - 3 Variables
- 2 Functions and procedures
  - 1 DetectMouse
  - 2 DoneMouse
  - 3 GetMouseButtons
  - 4 GetMouseDriver
  - 5 GetMouseEvent
  - 6 GetMouseX
  - 7 GetMouseY
  - 8 HideMouse
  - 9 InitMouse
  - 10 PollMouseEvent
  - 11 PutMouseEvent
  - 12 SetMouseDriver
  - 13 SetMouseXY
  - 14 ShowMouse
- 3 Writing a custom mouse driver

# 15 The MOUSE unit

mouseex The `Mouse` unit implements a platform independent mouse handling interface. It is implemented identically on all platforms supported by Free Pascal and can be enhanced with custom drivers, should this be needed.

# 1 Constants, Types and Variables

## 1 Constants

The following constants can be used when mouse drivers need to report errors:

    const
      { We have an errorcode base of 1030 }
      errMouseBase                    = 1030;
      errMouseInitError               = errMouseBase + 0;
      errMouseNotImplemented          = errMouseBase + 1;

The following constants describe which action a mouse event describes

    const
      MouseActionDown = $0001;  { Mouse down event }
      MouseActionUp   = $0002;  { Mouse up event }
      MouseActionMove = $0004;  { Mouse move event }

The following constants describe the used buttons in a mouse event:

      MouseLeftButton   = $01;  { Left mouse button }
      MouseRightButton  = $02;  { Right mouse button }
      MouseMiddleButton = $04;  { Middle mouse button }

The mouse unit has a mechanism to buffer mouse events. The following constant defines the size of the event buffer:

    MouseEventBufSize = 16;

## 2 Types

The `TMouseEvent` is the central type of the mouse unit, it is used to describe the mouse events:

    PMouseEvent=^TMouseEvent;
    TMouseEvent=packed record { 8 bytes }
      buttons : word;
      x,y     : word;
      Action  : word;
    end;

The `Buttons` field describes which buttons were down when the event occurred. The `x,y` fields describe where the event occurred on the screen. The `Action` describes what action was going on when the event occurred. The `Buttons` and `Action` field can be examined using the above constants.

The following record is used to implement a mouse driver in the SetMouseDriver function:

    TMouseDriver = Record
      UseDefaultQueue : Boolean;
      InitDriver : Procedure;
      DoneDriver : Procedure;
      DetectMouse : Function : Byte;
      ShowMouse : Procedure;
      HideMouse : Procedure;
      GetMouseX : Function : Word;
      GetMouseY : Function : Word;
      GetMouseButtons : Function : Word;
      SetMouseXY : procedure (x,y:word);
      GetMouseEvent : procedure (var MouseEvent:TMouseEvent);
      PollMouseEvent : function (var MouseEvent: TMouseEvent):boolean;
      PutMouseEvent : procedure (Const MouseEvent:TMouseEvent);
    end;

Its fields will be explained in the section on writing a custom driver.

## 3 Variables

The following variables are used to keep the current position and state of the mouse.

    MouseIntFlag : Byte;  { Mouse in int flag }
    MouseButtons : Byte;  { Mouse button state }
    MouseWhereX,
    MouseWhereY  : Word;  { Mouse position }

# 2 Functions and procedures

##
1 DetectMouse

Declaration
  `Function DetectMouse:byte;`
Description
  DetectMouse detects whether a mouse is attached to the system or not. If there is no mouse, then zero is returned. If a mouse is attached, then the number of mouse buttons is returned.

  This function should be called after the mouse driver was initialized.

Errors
  None.
See also
  InitMouse,DoneMouse,

Example

      Program Example1;

      { Program to demonstrate the DetectMouse function. }

      Uses mouse;

      Var
        Buttons : Byte;

      begin
        InitMouse;
        Buttons:=DetectMouse;
        If Buttons=0 then
          Writeln('No mouse present.')
        else
          Writeln('Found mouse with ',Buttons,' buttons.');
        DoneMouse;
      end.

##
2 DoneMouse

Declaration
  `Procedure DoneMouse;`
Description
  DoneMouse De-initializes the mouse driver. It cleans up any memory allocated when the mouse was initialized, or removes possible mouse hooks from memory. The mouse functions will not work after `DoneMouse` was called. If `DoneMouse` is called a second time, it will exit at once. `InitMouse` should be called before `DoneMouse` can be called again.
Errors
  None.
See also
  DetectMouse, InitMouse

For an example, see most other mouse functions.

##
3 GetMouseButtons

Declaration
  `Function GetMouseButtons:word;`
Description
  GetMouseButtons returns the current button state of the mouse, i.e. it returns a or-ed combination of the following constants:
  MouseLeftButton
    When the left mouse button is held down.
  MouseRightButton
    When the right mouse button is held down.
  MouseMiddleButton
    When the middle mouse button is held down.
Errors
  None.
See also
  GetMouseEvent, GetMouseX, GetMouseY

Example

      Program Example2;

      { Program to demonstrate the GetMouseButtons function. }

      Uses mouse;

      begin
        InitMouse;
        Writeln('Press right mouse button to exit program');
        While (GetMouseButtons<>MouseRightButton) do ;
        DoneMouse;
      end.

##
4 GetMouseDriver

Declaration
  `Procedure GetMouseDriver(Var Driver : TMouseDriver);`
Description
  GetMouseDriver returns the currently set mouse driver. It can be used to retrieve the current mouse driver, and override certain callbacks.

  A more detailed explanation about getting and setting mouse drivers can be found in section mousedrv.

Errors
  None.
See also
  SetMouseDriver

For an example, see the section on writing a custom mouse driver, section mousedrv

##
5 GetMouseEvent

Declaration
  `Procedure GetMouseEvent(var MouseEvent:TMouseEvent);`
Description
  GetMouseEvent returns the next mouse event (a movement, button press or button release), and waits for one if none is available in the queue.

  Some mouse drivers can implement a mouse event queue which can hold multiple events till they are fetched.; Others don't, and in that case, a one-event queue is implemented for use with PollMouseEvent.

Errors
  None.
See also
  GetMouseButtons, GetMouseX, GetMouseY

##
6 GetMouseX

Declaration
  `Function GetMouseX:word;`
Description
  GetMouseX returns the current `X` position of the mouse. `X` is measured in characters, starting at 0 for the left side of the screen.
Errors
  None.
See also
  GetMouseButtons,GetMouseEvent, GetMouseY

Example

      Program Example4;

      { Program to demonstrate the GetMouseX,GetMouseY functions. }

      Uses mouse;

      Var
        X,Y : Word;

      begin
        InitMouse;
        Writeln('Move mouse cursor to square 10,10 to end');
        Repeat
          X:=GetMouseX;
          Y:=GetMouseY;
          Writeln('X,Y= (',X,',',Y,')');
        Until (X=9) and (Y=9);
        DoneMouse;
      end.

##
7 GetMouseY

Declaration
  `Function GetMouseY:word;`
Description
  GetMouseY returns the current `Y` position of the mouse. `Y` is measured in characters, starting at 0 for the top of the screen.
Errors
  None.
See also
  GetMouseButtons,GetMouseEvent, GetMouseX

For an example, see GetMouseX

##
8 HideMouse

Declaration
  `Procedure HideMouse;`
Description
  HideMouse hides the mouse cursor. This may or may not be implemented on all systems, and depends on the driver.
Errors
  None.
See also
  ShowMouse

Example

      Program Example5;

      { Program to demonstrate the HideMouse function. }

      Uses mouse;

      Var
        Event : TMouseEvent;
        Visible: Boolean;

      begin
        InitMouse;
        ShowMouse;
        Visible:=True;
        Writeln('Press left mouse button to hide/show, right button quits');
        Repeat
         GetMouseEvent(Event);
         With Event do
           If (Buttons=MouseLeftbutton) and
              (Action=MouseActionDown) then
             begin
             If Visible then
               HideMouse
             else
               ShowMouse;
             Visible:=Not Visible;
             end;
        Until (Event.Buttons=MouseRightButton) and
              (Event.Action=MouseActionDown);
        DoneMouse;
      end.

##
9 InitMouse

Declaration
  `Procedure InitMouse;`
Description
  InitMouse Initializes the mouse driver. This will allocate any data structures needed for the mouse to function. All mouse functions can be used after a call to `InitMouse`.

  A call to `InitMouse` must always be followed by a call to DoneMouse at program exit. Failing to do so may leave the mouse in an unusable state, or may result in memory leaks.

Errors
  None.
See also
  DoneMouse, DetectMouse

For an example, see most other functions.

##
10 PollMouseEvent

Declaration
  `Function PollMouseEvent(var MouseEvent: TMouseEvent):boolean;`
Description
  PollMouseEvent checks whether a mouse event is available, and returns it in `MouseEvent` if one is found. The function result is `True` in that case. If no mouse event is pending, the function result is `False`, and the contents of `MouseEvent` is undefined.

  Note that after a call to `PollMouseEvent`, the event should still be removed from the mouse event queue with a call to `GetMouseEvent`.

Errors
  None.
See also
  GetMouseEvent, PutMouseEvent

##
11 PutMouseEvent

Declaration
  `Procedure PutMouseEvent(const MouseEvent: TMouseEvent);`
Description
  PutMouseEvent adds `MouseEvent` to the input queue. The next call to GetMouseEvent or `PollMouseEvent` will then return `MouseEvent`.

  Please note that depending on the implementation the mouse event queue can hold only one value.

Errors
  None.
See also
  GetMouseEvent, PollMouseEvent

##
12 SetMouseDriver

Declaration
  `Procedure SetMouseDriver(Const Driver : TMouseDriver);`
Description
  SetMouseDriver sets the mouse driver to `Driver`. This function should be called before InitMouse is called, or after `DoneMouse` is called. If it is called after the mouse has been initialized, it does nothing.

  For more information on setting the mouse driver, section mousedrv.

Errors

See also
  InitMouse, DoneMouse, GetMouseDriver

For an example, see section mousedrv

##
13 SetMouseXY

Declaration
  `Procedure SetMouseXY(x,y:word);`
Description
  SetMouseXY places the mouse cursor on `X,Y`. X and Y are zero based character coordinates: `0,0` is the top-left corner of the screen, and the position is in character cells (i.e. not in pixels).
Errors
  None.
See also
  GetMouseX, GetMouseY

Example

      Program Example7;

      { Program to demonstrate the SetMouseXY function. }

      Uses mouse;

      Var
        Event : TMouseEvent;

      begin
        InitMouse;
        Writeln('Click right mouse button to quit.');
        SetMouseXY(40,12);
        Repeat
          If (GetMouseX>70) then
            SetMouseXY(10,GetMouseY);
          If (GetMouseY>20) then
            SetMouseXY(GetMouseX,5);
          GetMouseEvent(Event);
        Until (Event.Buttons=MouseRightButton) and
              (Event.Action=MouseActionDown);
        DoneMouse;
      end.

##
14 ShowMouse

Declaration
  `Procedure ShowMouse;`
Description
  ShowMouse shows the mouse cursor if it was previously hidden. The capability to hide or show the mouse cursor depends on the driver.
Errors
  None.
See also
  HideMouse

For an example, see HideMouse

#
3 Writing a custom mouse driver

The mouse has support for adding a custom mouse driver. This can be used to add support for mouses not supported by the standard Free Pascal driver, but also to enhance an existing driver for instance to log mouse events or to implement a record and playback function.

The following unit shows how a mouse driver can be enhanced by adding some logging capabilities to the driver.