Subsections

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. It is intended to be used only in text-based screens, for instance in conjunction with the keyboard and video unit. No support for graphical screens is implemented, and there are (currently) no plans to implement this.

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.



2004-02-13