Subsections
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.
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;
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.
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 }
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.
2002-04-25