BETA VERSION 0.3

Written by Revonite
Copyright © 2002, Revonite
Revonite@TropicalStorm.com

Music: Nine Inch Nails - The Becoming
Don't like good music? Hit Stop.

 

User Manual

What is DML? What can it do? This is a basic introduction to Direct Mouse Library and how it can be used. Firstly, it is designed for use in QBasic or QuickBASIC and for the Intel 386+ architecture (not sure about IA64). Direct Mouse Library was designed specifically for screen mode 13 (0x13), so using this library for screen mode 12 may not return cursor locations properly. *Added in beta 0.2 - text mode functions.

 

Change Log

 

Before anything, you must include DML with your QBasic program. This can be done by starting QBasic like so:

QB /lDML

Which loads the DML library. Next, you must enter screen mode 13 (as this is where your mouse routines will be..). If you don't know how to enter screen mode 13, learn QBasic before messing around with the mouse. Now that you're in screen 13 with a basic program such as:

SCREEN 13

Okay, next step is to include DML.BI into your program, which contains all of the sub and function declarations that you'll need for the functions in the next part of this manual. To include DML.BI, add this line to the TOP of your program (note: make sure DML.BI is in your program directory):

' $INCLUDE: 'DML.BI'

You should now be set up ready to use the following functions in your program..

DML.ShowMouse
Makes the mouse cursor visible.
DML.HideMouse
Hides the mouse cursor.
DML.ResetMouse
Resets the mouse cursor position (doesn't work properly for me).
Note: Cursor is hidden after this function is used. Use DML.ShowMouse afterwards.
DML.GetMouseX%
Returns the cursor's X co-ordinate.
Example:
x% = DML.GetMouseX%
DML.GetMouseY%
Returns the cursor's Y co-ordinate.
y% = DML.GetMouseY%
DML.SetXY (x%, y%)
Sets the cursor X, Y position.
Example:
DML.SetXY 60, 30
DML.SetCageH (x1%, x2%)
Sets the horizontal limits of where the mouse cursor can move.
0 < x < 320
Example:
DML.SetCageH 20, 300
DML.SetCageV (y1%, y2%)
Sets the vertical limits of where the mouse cursor can move.
0 < y < 200
Example:
DML.SetCageV 50, 170
DML.SetCage (x1%, y1%, x2%, y2%)
Sets the mouse boundaries (same as the top two combined).
Example:
DML.SetCage 20, 50, 300, 170
DML.MouseType%

Returns the type of mouse being used.
Return value codes:
1 = Bus mouse
2 = Serial mouse
3 = InPort mouse
4 = PS/2 mouse
5 = Hewlett Packard mouse

Example:
MType% = DML.MouseType%
SELECT CASE MType%
CASE 1
PRINT "Bus mouse"
CASE 2
PRINT "Serial mouse"
CASE 3
PRINT "InPort mouse"
CASE 4
PRINT "PS/2 mouse"
CASE 5
PRINT "Hewlett Packard mouse"
END SELECT

DML.ButtonStatus%

Returns the button status. You must AND the value to return the mouse button code. The values are:
0 = No button down
1 = Left button down
2 = Right button down
3 = Left and right buttons down
4 = Middle button down
Example:
LeftButton% = DML.ButtonStatus% AND 1
RightButton% = DML.ButtonStatus% AND 2
MiddleButton% = DML.ButtonStatus% AND 3
IF LeftButton% > 0 THEN PRINT "Left button down"
IF RightButton% > 0 THEN PRINT "Right button down."
IF MiddleButton% > 0 THEN PRINT "Middle button down."

DML.NumButtons%
Simple returns the amount of buttons on the mouse.
Example:
Buttons% = DML.NumButtons%
PRINT "Number of buttons:"; Buttons%
DML.LightPenOn
Not sure about this -- turns light pen emulation on. The light pen is considered on the screen when both mouse buttons are pressed and the light pen is considered off when no buttons are pressed.
DML.LightPenOff
Turns off light pen emulation (see above).
DML.SetSensitivity (x%, y%)
Sets the mouse sensitivity. Takes two parameters: the X sensitivity and the Y sensitivity. The lower the sensitivity the more reactive. Must be a number from 1 to 32767. Default X is 8 and default Y is 16.
DML.GetTextX%
Returns the X co-ordinate of the cursor in text mode.
Example:
PRINT DML.GetTextX%
DML.GetTextY%
Returns the Y co-ordinate of the cursor in text mode.
Example:
y% = DML.GetTextY%
DML.SetTextXY (x%, y%)
Sets the text mode mouse cursor location.
Example:
DML.SetTextXY 79, 24
DML.S12MouseX%
Returns the mouse cursor X co-ordinate in screen mode 12 (i.e. 640x480).
Example:
SCREEN 12
DML.ShowMouse
DO
 LOCATE 1, 1: PRINT "X:"; DML.S12MouseX%
LOOP UNTIL INKEY$ <> ""
DML.S12MouseY%
Returns the mouse cursor Y co-ordinate in screen mode 12 (i.e. 640x480).
Example:
SCREEN 12
DML.ShowMouse
DO
 LOCATE 2, 1: PRINT "Y:"; DML.S12MouseY%
LOOP UNTIL INKEY$ <> ""
DML.GetXSensitivity%
Returns the horizontal mouse sensitivity.
Example:
MSensX% = DML.GetXSensitivity%
DML.GetYSensitivity%
Returns the vertical mouse sensitivity.
Example:
MSensY% = DML.GetYSensitivity%
DML.SetUpdateRate (r%)

This only works with InPort mice. Use DML.MouseType% to check..!
This function defines how many times the mouse co-ordinates and button status are updated every second. r% can be one of the following:

0 = None: No updating.
1 = 30 updates per second.
2 = 50 updates per second.
3 = 100 updates per second.
4 = 200 updates per second.

The more times the cursor status is updated per second, the more CPU intense your program will be (bad for slow machines). r% cannot be below 0 or above 4 (checking for this is done).

DML.SetMousePage (Pg%)
Sets the graphics page for the cursor to be shown on (you set the active graphics page through the SCREEN QBasic statement).
DML.GetMousePage%
Returns which graphics page the cursor is currently assigned to be shown on.
DML.DetectMouse%
Detects if a mouse is present; returns 0 if there is no mouse and 1 if there is a mouse.
Example:
CheckMouse% = DML.DetectMouse%
IF CheckMouse% = 0 THEN
 PRINT "Error: No mouse found."
 END
ELSE
 PRINT "Mouse found."
END IF

Now for a quick example of putting a few of these together..

' $INCLUDE: 'DML.BI'
SCREEN 13
DML.HideMouse
COLOR 6
PRINT "Mouse Demo"
COLOR 8
PRINT "Revonite"
COLOR 9
PRINT "Detecting mouse.. ";
Fnd% = DML.DetectMouse%
IF Fnd% = 0 THEN PRINT "not found": END
PRINT "found."
PRINT "Turning mouse on.. ";
DML.ShowMouse
PRINT "done."
PRINT "Mouse has"; DML.NumButtons%; "buttons."

PRINT "Press a key to hide the mouse.."
DO: LOOP UNTIL INKEY$ <> ""
DML.HideMouse
PRINT "Voila."
DO: LOOP UNTIL INKEY$ <> ""
DML.ShowMouse
LINE INPUT "Enter new cursor X co-ordinate: ", x$
LINE INPUT "Enter new cursor Y co-ordinate: ", y$
DML.SetXY VAL(x$), VAL(y$)
DO
LOCATE 20, 1: PRINT "X:"; DML.GetMouseX%
LOCATE 21, 1: PRINT "Y:"; DML.GetMouseY%
LOOP UNTIL INKEY$ <> ""
END

If you have any bug reports, questions, comments.. mail them to me (Revonite@TropicalStorm.com). If you use this library in your games or software, please give credit.. You don't have to, but it would be nice and would gain you respect for acknowledging help. Thank you.

- Revonite
151189244