PROGRAMMER'S REFERENCE MANUAL A. INTRODUCTION The following manual provides information to programmers who want to include support for MOUSE in their application programs. This document includes descriptions of the graphics cursor and text cursor, and the mouse functions. All functions supported by MOUSE driver including: a. All functions supported by the Microsoft mouse driver. b. Additional functions supported for the middle button processing of the MOUSE. c. Some new function supported to MOUSE working in different modes. All the function call interface is compatible with Microsoft Corp. As it is documented in the installation and operation manual published by Microsoft Corp. entitled Microsoft (r) Mouse User's Guide for IBM Personal Computers. B. Screen Coordinated System The MOUSE driver is compatible with the IBM Color Graphics Adapter, the IBM Monochrome Display Adapter, the IBM Enhanced Graphics Adapter, and the Hercules Monochrome Graphics Adapter. The MOUSE driver works with all of the BIOS supported screen modes for both the IBM Color/Graphics Monitor Adapter and the IBM Monochrome Display Adapter, these modes are: a. High-resolution graphics mode (640 * 200, 2 colors). b. Medium-resolution color mode (320 * 200, 4 colors). c. Text mode - (1) 80 column by 25 row. (2) 40 column by 25 row. The Hercules graphics Card is supported in monochrome graphics mode: d. Monochrome Graphics (720 * 348, 2 colors). When you want to use MOUSE with the hercules high resolution modes, follow these steps: (1) If you are using the page at B000H, poke a 6 into the memory location 40:49. (2) If you are using the page at B800H, poke a 5 into 40:49. In medium-resolution mode -- The physical coordinate is 320 pixels across by 200 pixels. All horizontal coordinates are mapped to even coordinates in logical coordinate system. On the upper left-corner of the screen is (0,0), on the bottommost right-corner of the screen is (638,0). In 80 column by 25 row text mode -- The logical coordinates is 640 * 200 are used. A logical character size of 8 * 8 pixels is assumed. All logical horizontal coordinates are multiples of eight, and all logical vertical coordinate are multiples of eight. In 40 column by 25 row text mode -- The logical coordinates is 640 * 200 are used. A logical character size of 16 * 8 pixels is assumed. All logical horizontal coordinates are multiples of sixteen, and all logical vertical coordinates are multiples of eight. In Hercules monochrome graphics mode -- The logical coordinates match the physical pixels. The pixels on the top row have coordinates of (0,0), (1,0), etc. The pixels at the bottommost right of the screen is (719,347). Logical coordinates are used as both input and output to mouse function calls. User should be careful to provide the correct values for the current screen mode. C. CURSOR DESCRIPTION - TEXT CURSOR AND GRAPHICS CURSOR The characteristics of the cursor are determined by Functions 9 and 10. MOUSE has both text and graphics cursor available. 1. Graphics Cursor The graphics cursor is an array of pixels (normally 16 by 16). It is defined by two arrays of bits called the screen mask and the cursor mask. The screen mask has two parts to determine the shape or the background of cursor pixels. Cursor pixels are part of the shape (0) or of the background (1) (it is ANDed with the screen contents). The cursor mask is used to determine the shape color and background color of the cursor pixels (it is XORed with the result of the previous operation). The operational behavior of these bit arrays are summarized in the following table: 旼컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴컴컴컴커 � screen mask � cursor mask � resulting screen bit � 쳐컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴캑 � 0 � 0 � 0 � 쳐컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴캑 � 0 � 1 � 1 � 쳐컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴캑 � 1 � 0 � unchanged � 쳐컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴캑 � 1 � 1 � inverted � 읕컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴컴컴컴켸 Note that when a mouse function refers to the graphics cursor location is referring to the point on the screen that lies directly under the cursor's target area. The target area is the point in the cursor block that the mouse software uses to determine the cursor coordinates. This point is called the hot spot of the cursor. The upper left corner of the cursor block is the hot spot for the default graphic cursor. 2. Text Cursor The text cursor is a cursor that can be used when the video is in one of the text modes. Tow kind of text cursor are supported: a hardware text cursor and a software text cursor. a. The hardware text cursor is the cursor actually placed on the screen by the video controller itself. It is defined in terms of the scan lines of the character cell numbered from 0, starting from the top scan line. The numbers of scan lines on a character cell depend on the actual video controller and monitor (see the controller documentation for details). b. The software text cursor is a character code and a character attribute that replaces and/or modifies the character cell on the screen where it is positioned. The behaviors of this cursor is defined by 2 16-bit values. he format of the two values is the following: Bit Description 15 blinking (1) or non blinking (0) 14-12 background color 11 high intensity (1) or medium intensity (0) 10-8 foreground color 7-0 character code The tow values are called the screen mask and the cursor mask. The screen mask is used to determine which of the character attributes are preserved (it is ANDed with the screen character and attribute). The cursor mask is used to determine which of the characteristics are changed by the cursor (it is XORed with the result of the previous operation). D. USING THE MOUSE BUTTON The mouse function calls can return the current state of the mouse buttons and the number of times of a given button has been pressed or released. The button state is returned as a integer value in the low order three bits are one or zero. The following table describes the bit status: Bit 0: Left button state (0 - Up, 1 - Down) Bit 1: Right button state (0 - Up, 1 - Down) Bit 2: Middle button state (0 - Up, 1 - Down) E. MOUSE MOTION AND CURSOR MOTION: SENSITIVITY Mouse sensitivity is a measure volume of how much mouse motion is required to move the cursor in a given distance on the screen. This can be varied so that a small amount of mouse motion can move the cursor a long way, or vice versa. Different applications may require different sensitive. F. MOUSE FUNCTION CALL Function Description * Function 0 Mouse initialization This function is used to check whether the mouse hardware and software installed or not. successful return -1 fail return 0 Input AX = 0 Output AX = mouse status BX = number of buttons * Function 1 Show cursor This function is used to show current mouse position on the screen. Input AX = 1 Output none * Function 2 Hidden cursor This function removes cursor from the screen. Input AX = 2 Output none * Function 3 Get mouse position & button status This function reports current mouse position & button status. button down a bit is 1 button up a bit is 0 Input AX = 3 Output BX = button status CX = horizontal cursor position DX = vertical cursor position * Function 4 Set mouse cursor position This function sets cursor to a specified position on the screen. Input AX =4 CX = new horizontal cursor position DX = new vertical cursor position Output none * Function 5 Get button press information This function reports 1. Current button status. 2. A count of button press since the last call to function 5 or function 0. 3. Horizontal and vertical position of the cursor, the button was pressed last time. Input AX = 5 BX = button ; BX=0 check left button ; BX=1 check right button ; BX=2 check middle button Output AX = button status; bit 0 left button, bit 1 right button, bit 2 middle button. BX = number of button presses CX = horizontal cursor position at last press DX = vertical cursor position at last press * Function 6 Get button release information This function reports 1. Current button status. 2. A count of button release since the last call to function 6 or function 0. 3. Horizontal and vertical position of the cursor, the button was released last time. Input AX = 5 BX = button ; BX=0 check left button ; BX=1 check right button ; BX=2 check middle button Output AX = button status; bit 0 left button, bit 1 right button, bit 2 middle button. BX = number of button releases CX = horizontal cursor position at last released DX = vertical cursor position at last released * Function 7 Set MIN & MAX X position This function is used to set mouse horizontal moving range. Input AX = 7 CX = new minimum horizontal cursor position DX = new maximum horizontal cursor position Output none * Function 8 Set MIN & MAX Y position This function is used to set mouse vertical moving range. Input AX = 8 CX = new minimum vertical cursor position DX = new maximum vertical cursor position Output none * Function 9 Define graphics cursor block This function determines what the shape and color of the cursor will be when it is in graphics mode, and it identifies the center of the cursor. The cursor block is a 16 X 16 bit pattern. The cursor hot spot values must be within the range from -16 to 16. They define one pixel within ( or outside) the cursor block. Input AX = 9 BX = horizontal cursor hot spot CX = vertical cursor hot spot DX = pointer to screen and cursor mask Output none Note: If you use large mode to call this function register ES must be set to the segment value of the screen and cursor mask array. * Function 10 Define text cursor This function selects the software or hardware cursor. The value of the parameter BX selects the cursor type value is 0, software text cursor is selected. CX specify the screen mask DX specify the cursor mask value is 1, hardware cursor is selected. CX contain the first scan line DX contain the last scan line Input AX = 10 BX = select cursor CX = screen mask value/scan line start DX = cursor mask value/scan line stop Output none * Function 11 Read mouse motion counters This function returns the horizontal and vertical step count, which is the distance the mouse has moved in 1/200 inch increments, since the last call to this function. The step count is always within the range from -32768 to 32767. A positive horizontal count is a motion to the right while a positive vertical count is a motion to the bottom of the screen. The step count is set to 0 after the call is completed. Input AX = 11 Output CX = horizontal count DX = vertical count * Function 12 Define event handler This function sets the call mask and subroutine address for the mouse software interrupts. The software interrupts stop execution of your program and call the specified subroutine whenever on or more of the conditions defined by the call mask occur. The call mask is a single integer value which defines the conditions to cause an interrupt. Each bit in the call mask corresponds to a specific condition: Mask Bit Condition 0 change cursor position 1 press left button 2 release left button 3 press right button 4 release right button 5 press middle button 6 release middle button 7-15 non used Input AX = 12 CX = call mask ES:DX = address of subroutine Output * Function 13 Light pen emulation mode on This function enables light pen emulation by the mouse. when the mouse emulates the light pen, calls to the pen function will return the cursor position at the last pen down which is controlled by the mouse buttons. The pen is down when any button is down. The pen is off the screen when both buttons are up. Input AX =13 Output none * Function 14 Light pen emulation mode off This function disables the light pen emulation mode. Input AX = 14 Output none * Function 15 Set mouse motion/pixel ratio This function sets the mouse motion to screen pixel ratio. The horizontal and vertical ratios specify the amount of mouse motion at 8 pixels with the values falling within the range from 1 to 32767. The default values are 8 steps to 8 pixels horizontally and 16 steps to 8 pixels vertically. This is equivalent to 3.2 inches of horizontal mouse movement and 2.0 inches of vertical mouse movement. Input AX = 15 CX = horizontal step to pixel ratio DX = vertical step to pixel ratio Output none * Function 16 Conditional hidden cursor This function allows the user to define an area on the screen within which the mouse will be turned off. Performing the Show Cursor Function - Function 1 - resets the region and turns the mouse back on. This function is used to guard a portion of the screen which your program is abort to update. Input AX = 16 CX = left margin DX = top margin SI = right margin DI = bottom margin Output none * Function 17 This command causes mouse to work in PC MOUSE mode Input AX = A0H Output AX = FAH , success AX = FEH , fail * Function 18 This command causes mouse to work in MICROSOFT MOUSE mode Input AX = A1H Output AX = FAH , success AX = FEH , fail * Function 19 This function is used to send commands to mouse. Input AX = A5H BX = FFH reset command F2H read mouse device E9H request status F5H disable mouse F4H enable mouse E7H set scaling 2:1 E6H set scaling 1:1 E8H set mouse resolution This command causes the mouse to do a self-test. Input AX = A5H BX = FFH , reset command Output AX = FAH , success AX = FEH , fail This command always receives a response of 00. Input AX = A5H BX = F2H , read device type Output AX = FAH , success BX = 0 AX = FEH , fail When mouse receive this command responds with 3-byte status report as follows: Input AX = A5H BX = E9H , status request Output AX = FAH , success BX = bit 7 reserve bit 6 0: stream mode, 1: remote mode bit 5 0: disable, 1: enable bit 4 0: scale 1:1, 1: scale 2:1 bit 3 reserved bit 2 0: left button release 1: left button press bit 1 0: middle button release, 1: middle button press bit 0 0: right button release, 1: right button press CX = current resolution DX = current sampling rate AX = FEH , fail This command is used to stop transmissions initiated from the mouse. Input AX = A5H BX = F5H , disable Output AX = FAH , success AX = FEH , fail This command enable transmissions initiated from the mouse. Input AX = A5H BX = F4H , enable Output AX = FAH , success AX = FEH , fail This command is used to provide a cursor fine tracking response. At the end of a sample interval in the mouse, the X and Y data values are converted to new values. The relationship between input and output counts follows: INPUT OUTPUT 0 0 1 1 2 1 3 3 4 6 5 9 N(>=6) 2 * N Input AX = A5H BX = E7H , set scaling 2:1 Output AX = FAH , success AX = FEH , fail This command restores scaling to 1:1. Input AX = A5H BX = E6H , set scaling Output AX = FAH , success AX = FEH , fail This mouse provides five resolutions selected by the second byte of this command Input AX = A5H BX = E8H , set resolution CX = 0, 50 dpi 1, 100 dpi 2, 200 dpi 3, 400 dpi 4, Dynamic resolution (50 - 400) Output AX = FAH , success AX = FEH , fail