The Microsoft Mouse Interface Tutorial
                By Matthew Hildebrand (FidoNet 1:247/128.2)
                        Revision:  January 14, 1993


Applications wishing to interface to the mouse should do so via calls to
the industry-standard Microsoft or compatible mouse driver.  All calls to
the driver are made through interrupt 33h.

A list of answers to frequently asked questions is at the end of this
document.

Following is a summary of the functions the mouse driver provides.




                     **** MOUSE DRIVER FUNCTIONS ****

==============================
Function 00h:  Reset mouse

Call with      AX = 0000h

Return         If mouse available
                 AX = FFFFh
                 BX = number of buttons
               If mouse unavailable
                 AX = 0000h

Notes          Calling this function will initialize the mouse hardware,
               position the pointer at the screen center, set the pointer
               display page to zero, hide the pointer, reset the pointer
               shape to the default, disable any user-defined event
               handlers, enable light pen emulation, set the horizontal
               mickeys:pixels ratio to 8:8 and the vertical ratio to 16:8,
               set the double speed threshold to 64 mickeys/second, and set
               both the horizontal and vertical maximum and minimum pointer
               bounds to include the entire screen.

See also       Function 21h


==============================
Function 01h:  Show pointer

Call with      AX = 0001h

Return         Nothing

Notes          Calls to Functions 01h and 02h are cumulative; ie., if
               Function 01h is called twice, Function 02h must be called
               twice before the pointer becomes visible again.
See also       Function 02h


==============================
Function 02h:  Hide pointer

Call with      AX = 0002h

Return         Nothing

Notes          Calls to Functions 01h and 02h are cumulative; ie., if
               Function 01h is called twice, Function 02h must be called
               twice before the pointer becomes visible again.

See also       Function 01h


==============================
Function 03h:  Get pointer position and button status

Call with      AX = 0002h

Return         BX = button status
                 bit 0   left button down (if set)
                 bit 1   right button down (if set)
                 bit 2   center button down (if set)
               CX = x coordinate
               DX = y coordinate

Notes          Coordinates are always in pixels, where (0,0) is the upper-
               left of the screen.

See also       Functions 04h-06h


==============================
Function 04h:  Set pointer position

Call with      AX = 0004h
               CX = x coordinate
               DX = y coordinate

Return         Nothing

Notes          The new position will be disregarded if it lies within an
               exclusion area.

               Coordinates are always in pixels, where (0,0) is the upper-
               left of the screen.

               The position will be modified, if necessary, such that it
               lies within the horizontal and vertical limits.

See also       Function 03h


==============================
Function 05h:  Get button press information

Call with      AX = 0005h
               BX = button
                 0 = left button
                 1 = right button
                 2 = center button

Return         AX = button status
                 bit 0   left button down (if set)
                 bit 1   right button down (if set)
                 bit 2   center button down (if set)
               BX = button press counter (number since last call)
               CX = x coordinate of last press
               DX = y coordinate of last press

Notes          The button press counter for the specified button is reset
               to zero following a call to this function.

See also       Function 05h


==============================
Function 06h:  Get button release information

Call with      AX = 0006h
               BX = button
                 0 = left button
                 1 = right button
                 2 = center button

Return         AX = button status
                 bit 0   left button down (if set)
                 bit 1   right button down (if set)
                 bit 2   center button down (if set)
               BX = button release counter (number since last call)
               CX = x coordinate of last release
               DX = y coordinate of last release

Notes          The button release counter for the specified button is reset
               to zero following a call to this function.

See also       Function 04h


==============================
Function 07h:  Set pointer horizontal limits

Call with      AX = 0007h
               CX = minimum x coordinate
               DX = maximum x coordinate

Return         Nothing

Notes          The two values will be swapped if necessary.

               If necessary, the pointer will be moved such that it lies
               within the new limits.

See also       Functions 08h, 10h


==============================
Function 08h:  Set pointer vertical limits

Call with      AX = 0008h
               CX = minimum y coordinate
               DX = maximum y coordinate

Return         Nothing

Notes          The two values will be swapped if necessary.

               If necessary, the pointer will be moved such that it lies
               within the new limits.

See also       Functions 07h, 10h


==============================
Function 09h:  Set graphics pointer shape

Call with      AX = 0009h
               BX = hot spot offset from left
               CX = hot spot offset from top
               ES:DX = segment:offset of image buffer

Return         Nothing

Notes          The hot spot is the pixel of the image which the driver
               considers to be the current position.  For instance, an
               arrow pointer would have its hot spot at the upper left,
               while a crosshairs pointer would have it at the center. 
               Both the horizontal and vertical offsets must be between -16
               and 16 inclusive.

               The image buffer's length is 64 bytes.  The first 32 consist
               of a bitmask which is ANDed with the screen image, and the
               second 32 consist of a bitmap which is XORed with the screen
               image.

See also       Function 0Ah


==============================
Function 0Ah:  Set text pointer type

Call with      AX = 000Ah
               BX = pointer type
                 0 = software cursor
                 1 = hardware cursor
               CX = If BX=0:  AND mask
                    If BX=1:  Starting scan line
               DX = If BX=0:  XOR mask
                    If BX=1:  Ending scan line

Return         Nothing

Notes          If a software cursor is selected, CX and DX are as follows:
                    bits 0-7   character code
                    bits 8-10  foreground colour
                    bit 11     intensity bit
                    bits 12-14 background colour
                    bit 15     blink bit

               If the hardware cursor is selected, CX and DX are the
               starting and ending scan lines for the blinking cursor which
               the video card generates, which will depend upon the video
               card used.


==============================
Function 0Bh:  Read motion counters

Call with      AX = 000Bh
               
Return         CX = net horizontal mickey count
               DX = net vertical mickey count

Notes          This function will return the net mouse displacement since
               the last call to this function.  The returned values are
               measured in mickeys, where a negative value is upwards or to
               the left and a positive value is downwards or to the right.

See also       Functions 03h, 0Fh


==============================
Function 0Ch:  Set user-defined mouse event handler

Call with      AX = 000Ch
               CX = event mask
                 bit 0   mouse movement
                 bit 1   left button pressed
                 bit 2   left button released
                 bit 3   right button pressed
                 bit 4   right button released
                 bit 5   center button pressed
                 bit 6   center button released
               ES:DX = segment:offset of event handler

Return         Nothing

Notes          On entrance to the handler:
                 AX = mouse event mask (see Notes)
                 BX = button states
                   bit 0 left button down (if set)
                   bit 1 right button down (if set)
                   bit 2 center button down (if set)
                 CX = x coordinate of pointer
                 DX = y coordinate of pointer
                 DI = raw horizontal mickey count
                 SI = raw vertical mickey count
                 DS = mouse driver data segment

               The event mask specified in CX is placed in AX before each
               call to the handler, regardless of which of the events it
               specifies actually occurred.

               The handler may be deactivated by calling function 00h or
               this function with an event mask of zero.

See also       Functions 14h, 18h


==============================
Function 0Dh:  Activate light pen emulation

Call with      AX = 000Dh

Return         Nothing

Notes          This function activates light pen emulation for IBM BASIC. 
               The pen down condition is simulated by pressing the left and
               right buttons simultaneously.

See also       Function 0Eh


==============================
Function 0Eh:  Deactivate light pen emulation

Call with      AX = 000Eh

Return         Nothing

Notes          None.

See also       Function 0Dh


==============================
Function 0Fh:  Set mickeys to pixels ratio

Call with      AX = 0Fh
               CX = horizontal mickeys (default=8)
               DX = vertical mickeys (default=16)

Return         Nothing

Notes          The mickey values must be between 1 and 32767 inclusive.

               This function will set the number of mickeys necessary for 8
               pixels of motion to occur.

See also       Functions 13h, 1Ah, 1Bh


==============================
Function 10h:  Set pointer exclusion area

Call with      AX = 0010h
               CX = upper left x coordinate
               DX = upper left y coordinate
               SI = lower right x coordinate
               DI = lower right y coordinate

Return         Nothing

Notes          This function defines an exclusion area wherein the pointer
               is not displayed.  The exclusion area is cancelled by a call
               to function 00h or 01h, or replaced by another call to this
               function.

See also       Functions 00h-02h


==============================
Function 13h:  Set double speed threshold

Call with      AX = 0013h
               DX = speed in mickeys/second

Return         Nothing

Note           This function sets the minimum speed necessary before