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 pointer motion will double. The default is 64 mickeys/second; doubling can be disabled by setting DX to a large value. See also Functions 0Fh, 1Ah, 1Bh ============================== Function 14h: Swap user-defined mouse event handlers Call with AX = 0014h 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 CX = previous event mask ES:DX = segment:offset of previous event handler Notes On entrance to the handler: AX = mouse event flags (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 handler may be deactivated by calling function 00h or this function with an event mask of zero. See also Functions 0Ch, 18h ============================== Function 15h: Get save state buffer size Call with AX = 0015h Return BX = buffer size in bytes Notes Before running any external programs, applications should save the mouse driver state; doing so will ensure that any event handlers, sensitivity settings, or other settings will remain intact. Of course, the driver state should be restored when the external program is complete. See also Functions 16h, 17h ============================== Function 16h: Save driver state Call with AX = 0016h ES:DX = segment:offset of buffer Return Nothing Note Before running any external programs, applications should save the mouse driver state; doing so will ensure that any event handlers, sensitivity settings, or other settings will remain intact. Of course, the driver state should be restored when the external program is complete. See also Functions 15h, 17h ============================== Function 17h: Restore driver state Call with AX = 0017h ES:DX = segment:offset of buffer Return Nothing Note Before running any external programs, applications should save the mouse driver state; doing so will ensure that any event handlers, sensitivity settings, or other settings will remain intact. Of course, the driver state should be restored when the external program is complete. See also Functions 15h, 16h ============================== Function 18h: Set alternate mouse event handler Call with AX = 0018h 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 If successful AX = 0018h If unsuccessful AX = FFFFh Notes On entrance to the handler: AX = mouse event flags (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 handler may be deactivated by calling function 00h. As many as three alternate event handlers, with unique event masks, may be installed. See also Functions 0Ch, 14h ============================== Function 19h: Get address of alternate mouse event handler Call with AX = 0019h CX = event mask Return If successful CX = event mask ES:DX = segment:offset of alternate event handler If unsuccessful CX = 0000h Notes None. See also Function 18h ============================== Function 1Ah: Set sensitivity Call with AX = 001Ah BX = horizontal mickeys (default=8) CX = vertical mickeys (default=16) DX = double speed threshold (default=64) Return Nothing Notes This function will set the number of mickeys necessary for 8 pixels of motion to occur, as well as the double speed threshold. See also Functions 0Fh, 13h, 1Bh ============================== Function 1Bh: Get mouse sensitivity Call with AX = 001Bh Return BX = horizontal mickeys CX = vertical mickeys DX = double speed threshold Notes None. See also Functions 0Fh, 13h, 1Ah ============================== Function 1Ch: Set mouse interrupt rate Call with AX = 001Ch BX = interrupt rate flags bit 0 no interrupts (if set) bit 1 30 interrupts/second (if set) bit 2 50 interrupts/second (if set) bit 3 100 interrupts/second (if set) bit 4 200 interrupts/second (if set) Return Nothing Notes This function will only affect InPort mice. See also Function 24h ============================== Function 1Dh: Set pointer page Call with AX = 001Dh BX = page Return Nothing Notes Valid page numbers depend on the active display mode. See also Function 1Eh ============================== Function 1Eh: Get pointer page Call with AX = 001Eh Return BX = page Notes None. See also Function 1Dh ============================== Function 1Fh: Disable mouse driver Call with AX = 001Fh Return If successful AX = 001Fh ES:BX = segment:offset of previous INT 33h handler If unsuccessful AX = FFFFh Notes This function causes the mouse driver to release all interrupts other than INT 33h. The driver may then be effectively removed by restoring the previous contents of the INT 33h vector. See also Function 20h ============================== Function 20h: Enable mouse driver Call with AX = 0020h Return Nothing Notes Calling this function will re-enable the mouse driver and the servicing of mouse interrupts. See also Function 1Fh ============================== Function 21h: Reset mouse driver Call with AX = 0021h Return If mouse support available AX = FFFFh BX = number of buttons If mouse support unavailable AX = 0021h Notes The difference between this function and function 00h is that this function performs no initialization of the mouse hardware. See also Function 00h ============================== Function 22h: Set language for driver messages Call with AX = 0022h BX = language code 0 = English 1 = French 2 = Dutch 3 = German 4 = Swedish 5 = Finnish 6 = Spanish 7 = Portuguese 8 = Italian Return Nothing Notes This function is available only with international versions of the mouse driver. See also Function 23h ============================== Function 23h: Get language Call with AX = 0023h Return BX = language code Notes This function is available only with international versions of the mouse driver. See also Function 22h ============================== Function 24h: Get mouse information Call with AX = 0024h Return BH = major version number of driver BL = minor version number of driver CH = mouse type 1 = bus mouse 2 = serial mouse 3 = InPort mouse 4 = PS/2 mouse 5 = HP mouse CL = IRQ number 0 = PS/2 2, 3, 4, 5, or 7 = IRQ number Notes None. See also None. **** FREQUENTLY ASKED QUESTIONS **** Q: When I write something to the screen, it overwrites the mouse pointer. Then, when I move the mouse, the pointer comes back, along with a rectangle of outdated screen information. What do I do? A: The mouse driver keeps track of what was behind the pointer so that it may be restored when the mouse is moved. To avoid this problem, hide the pointer before writing to the screen, then show it when you're done. Q: When I'm in 320x200x256 mode or text mode, the driver returns incorrect coordinate values. What's wrong? A: For whatever reason, the mouse driver returns values in this way when in these modes. In 320x200x256 mode, the driver uses horizontal values which are actually twice the real value; shift the real value left one bit when passing a coordinate to the driver, and shift the returned value right one bit before using a value returned by the driver. Note that this shifting is only necessary for the horizontal coordinate. As for text mode, it's something of a similar absurd nature, such as twice the real value in one direction and thrice in the other, but I'm not sure. Q: What the hell's a mickey, anyway? A: The mickey is the smallest amount of motion the mouse can detect. One mickey is 1/200" on a 200 DPI mouse, 1/400" on a 400 DPI mouse, etc.. Q: How do I get those nifty-looking 256-colour mouse pointers? A: You write a mouse event handler which will be called whenever the mouse moves. You may also wish to trap INT 33h for calls such as hide pointer and show pointer. End of document