Simtel MSDOS 1992 June

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / mouse / rodent.arc / GMOUSE.DOC < prev next >

Wrap

Text File | 1987-09-28 | 28.4 KB | 1,273 lines

GMOUSE.DOC - GENIUS MOUSE Programming Interface Programmer's Reference Manual GENIUS-MOUSE DRIVER Serial Mouse Version Release 7.01 KUN YING ENTERPRISE CO.,LTD. RM. 1311,NO.41,SEC 1, CHUNG HSIAO W. RD. TAIPEI, TAIWAN, R.O.C. P.O. BOX: 22826 TAIPEI TEL: 3813682 3318779 3118545 3822228 TELEX: 11388 KUNYING FAX: 2-361-5300 page 1 Introduction The following provides information to programmers who want to include support for GENIUS-MOUSE in their application programs. This document includes descriptions of the graphics and text cursors, and descriptions of the mouse functions. This protocol is compatible with the protocol of 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 (R) Personal Computers. These notes apply to the GENIUS Serial Mouse Driver (mouse.com and mouse.sys) Release 5.01. Cursor Descriptions - Text and Graphics Cursors The characteristics of the cursor are determined by Functions 9 and 10. GENIUS MOUSE has both text and graphics cursors available. The graphics cursor is a shape that moves over the images on the screen. The shape can include an arrow, a sight mark, or others. The software text cursor is a character attribute that moves from character to character on the screen. The hardware text cursor is a moving, sometimes flashing block which also moves from character to character on the screen. The three cursors are exclusive - only one can be on the screen at one time. You have the option of choosing which cursor will appear on the screen and of switching from one cursor to the other. 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 is used to determine which of the cursor pixels becomes are part of the shape (1) or of the background (0) (it is ANDed with the screen contents). The cursor mask is used to determine which of the pixels of the cursors contribute to the color/shape of the cursor (it is XORed with the result of the previous operation). page 2 The operational behaviour of these bit arrays are summarized by 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 it 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. Text Cursor The text cursor is a cursor that can be used when the video is in one of the text modes. Two kind of text cursors are supported: a hardware text cursor and a software text cursor. 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 depends on the actual video controller and monitor (see the controller documentation for details). The software text cursor is a character or a character attribute that replaces and/or modifies the character cell on the screen where it is positioned. The behaviour of this cursor is defined by 2 16-bit values. The format of the two values is the following: bit description 15 blinking (1) or non blinking (0) character 14-12 background color 11 high intensity (1) or medium intensity (0) 10-8 foreground color 7-0 character code page 3 The two 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). Notice to System Programmers System programmers who intercept the video i/o software interrupt (int 10h) should exercise utmost care, and note the following: The program should guarantee that video mode changes (function 0) are intercepted by the mouse driver. The mouse driver guarantees consistency of the screen contents to programs that write on the screen via int 10h (or via DOS). Some programs write directly on the video memory. In this case the application program should use function 2 (hide cursor) or 16 (conditional hide cursor) before writing, then function 1 (show cursor) after writing. GWBASIC is an example of such a program. The presence of the mouse driver can also be detected by checking the interrupt vector entry for interrupt 51 in low memory for value 0 or for pointing to an IRET instruction. This method should be used with some care as it is dependent on the release of DOS. The programming interface uses the 8086 software interrupt 51. Parameter values are passed and returned via 8086 registers. This interface can be used from assembly language programs or from high level language programs such as BASIC , FORTRAN , COBOL , C or Pascal. You can also let the mouse software call a subroutine in your program whenever a specific condition occurs. When this capability is enabled, the mouse software interrupts whatever process is going on and passes execution control to the subroutine that you have specified in Function 12 of the mouse system calls. page 4 Making Calls From Assembly Language Programs : TO make mouse systemcalls from an assembly language program, you must: 1. Load the AX, BX, CX and DX registers with the parameter values. 2. Execute software interrupt 51(33H) The AX, BX, CX and DX registers correspond to the M1%, M2%, M3%, and M4% parameters. defined for the BASIC program. Values returned by the Mouse functions will be placed in the registers. Example Use the following instructions to set the cursor position to 150 (horizontal) and 100 (vertical): ; * set cursor to location (150,100) Mov AX,4 ;(function call 4) Mov CX,150 ;(set Horiziontal to 150) Mov DX,100 ;(set vertical to 100) Int 51 ;(interrupt to mouse) Note: When making a mouse system call in Assembly Language, function 9 and 12 expect a somewhat different. Value for the fourth parameter than when calling from a Basic program. page 5 Making Calls from BASIC (BASICA) Language Program : It is possible to make a mouse system call from a BASIC program running under the GWBASIC interpreter. The following shows how to make these calls. Insert an initialization sequence such as: 10 DEF SEG=0 20 MSEG=256*PEEK(51*4+3)+PEEK(51*4+2) 30 MOUSE=256*PEEK(51*4+1)+PEEK(51*4)+2 40 DEF SEG=MSEG Be sure that the statements appear before any calls to mouse functions. Then use the CALL statement to make the call. CALL MOUSE(M1%,M2%,M3%,M4%) where MOUSE is the variable containing the entry offset of the mouse software, and M1%, M2%, M3%, and M4% are the names of the integer variables you have chosen for parameters in this call. They correspond to the values for AX, BX, CX, and DX which are described in this document. As an example: 100 'Set minimum and maximum horizontal position to '(320,100) 200 M1%=7 'function number is 7 300 M3%=0 'minimum coordinate 400 M4%=639 'maximum coordinate 500 CALL MOUSE(M1%,M2%,M3%,M4%) page 6 List of Mouse Functions The following functions apply to GENIUS MOUSE. These functions will be described in greater detail in subsequent sections. FUNCTIONS FUNCTION NUMBER Base Functions Mouse Initialization 0 Show Cursor 1 Hide Cursor 2 Get Mouse Position & Button Status 3 Set Mouse Cursor Position 4 Get Button Press Information 5 Get Button Release Information 6 Set Minimum & Maximum X Position 7 Set Minimum & Maximum Y Position 8 Define Graphics Cursor Block 9 Define Text Cursor 10 Read Mouse Motion Counters 11 Define Event Handler 12 Light Pen Emulation Mode On 13 Light Pen Emulation Mode Off 14 Set Mouse Motion/Pixel Ratio 15 Condition Off 16 Set Double-Speed Threshold 19 page 7 page 6 Description of the Mouse Functions The following descriptions of the mouse functions specify the required input and the expected output of each function. The descriptions also include any special circumstances involved with each function. The input and output parameters are specified as values for 8086 registers and parameter for BASIC Language. Mouse Initialization - Function 0 *********************************** This function describes whether the mouse hardware and software are installed. The mouse status is 0 if the mouse hardware and software are not installed and -1 if the hardware and software are installed. 8086 register : Input AX = 0 Output AX = mouse status BX = number of buttons Basic: Input M1% = 0 Output M1% = Mouse status M2% = number of Buttons Example: 100 : Is mouse present ? if not error 200 M1% = 0 300 CALL Mouse(M1%,M2%,M3%,M4%) 500 IF NOT (M1%) THEN PRINT "Mouse not installed" : END page 8 Show Cursor - Function 1 ************************** This function increments the internal cursor flag. If the flag is 0 it displays the cursor on the screen. The cursor tracks the motion of the mouse, changing position as the mouse changes position. 8086 register : Input AX = 1 Output none Basic: Input M1% = 1 Output none Example: 100 : show the cursor 200 M1% = 1 300 CALL Mouse(M1%,M2%,M3%,M4%) page 9 Hide Cursor - Function 2 ************************** This function removes the cursor from the screen and decrements the internal cursor flag. Although the cursor is hidden it still tracks the motion of the mouse, changing position as the mouse changes position. 8086 register : Input AX = 2 Output none Basic: Input M1% = 2 Output none Example: 100 : Hide the cursor 200 M1% = 2 300 CALL Mouse(M1%,M2%,M3%,M4%) page 10 Get Mouse Position & Button Status - Function 3 ************************************************* This function reports the status of the buttons. It also reports the position of the cursor horizontally and vertically. The button status is a single integer value with bit 0 representing the left button and bit 1 the right. When the button is down a bit is 1 and when the button is up a bit is 0. 8086 register : Input AX = 3 Output BX = button status CX = horizontal cursor position DX = vertical cursor position Basic : Input M1% = 3 Output M2% = button status M3% = cursor position M4% = cursor position Example : 100 : Get current cursor positions, check button status 200 M1% = 3 300 CALL Mouse(M1%,M2%,M3%,M4%) 400 IF M2% AND 1 THEN PRINT "LEFT Button Down" 500 IF M2% AND 2 THEN PRINT "RIGHT Button Down" page 11 è Set Mouse Cursor Position - Function 4 **************************************** This function sets the cursor to the specified horizontal and vertical positions on the screen. The new values must be within the specified ranges of the virtual screen. If you are not using a high resolution screen the values are rounded to the nearest values permitted by the screen for horizontal and vertical positions. 8086 register : Input AX = 4 CX = new horizontal cursor position DX = new vertical cursor position Output none Basic: Input M1% = 4 M3% = (horixontal) new cursor position M4% = (vertical) new cursor position Example: 100 ; Put corsor in center of screen 200 M1% = 4 300 M3% = INT(Hmax/2) 400 M4% = INT(Vmax/2) 500 CALL Mouse(M1%,M2%,M3%,M4%) page 12 Get Button Press Information - Function 5 ********************************************* This function reports on the current button status. It gives a count of button presses since the last call to Function 5, and it gives the horizontal and vertical position of the cursor the last time the button was pressed. The BX parameter indicates which button was pressed. If BX is 0, the left button is checked. If BX is 1, the right button is checked. The button status is a single integer value. Bit 0 represents the left button and bit 1 the right. If the button is down a bit is 1 and if it is up a bit is 0. 8086 register : Input AX = 5 BX = button Output AX = button status BX = number of button presses CX = horizontal cursor position at last press DX = vertical cursor position at last press Basic : Input M1% = 5 M2% = Button Output M1% = Button status M2% = number of Button presses M3% = horizontal cursor position at last press M4% = vertical cursor positin at last press Example : 100 ; Get cursor position at last button press 200 M1% = 5 300 M2% = 0 400 CALL Mouse(M1%,M2%,M3%,M4%) 500 IF (M1% AND 1) THEN PRINT "LEFT Button Down" page 13 è Get Button Release Information - Function 6 ********************************************* This function reports on the current button status. It reports a count of the button releases since the last call to Function 6, and it gives the horizontal and vertical position of the cursor since the last time the button was released. The BX parameter specifies which button is checked. If BX is 0, the left button is checked. If BX is 1, the right button is checked. The button status is a single integer value. Bit 0 represents the left button and bit 1 represents the right button. If a button is down a bit is 1 and if a bit is 0 a button is up. 8086 register : Input AX = 6 BX = button Output AX = button status BX = number of button releases CX = horizontal cursor position at last release DX = vertical cursor position at last release Basic : Input M1% = 6 M2% = Button Output M1% = button status M2% = number of button releases M3% = horizontal cursor position at last release M4% = vartical cursor position at last release Example : 100 ; Get cursor position at last button release 200 M1% = 6 300 M2% = 1 400 CALL Mouse(M1%,M2%,M3%,M4%) 500 IF (M1% AND 2) THEN PRINT "RIGHT Button Down" page 14 Set Minimum & Maximum X Position - Function 7 ************************************************ This function sets the minimum and maximum possible cursor positions on the screen. All cursor movement is restricted to this area once the area is set. The virtual screen determines the maximum and minimum values. If the cursor is outside the defined area when the call is made, it moves to just inside the area. If the minimum value is greater than the maximum the two values are exchanged. 8086 register : Input AX = 7 CX = new minimum horizontal cursor position DX = new maximum horizontal cursor position Output none Basic : Input M1% = 7 M3% = new minimum horizontal cursor position M4% = new maximum horizontal cursor position Output none Example : 100 ; Limit cursor to horizontal position between 50 and 200 200 M1% = 7 300 M3% = 50 400 M4% = 200 500 CALL Mouse(M1%,M2%,M3%,M4%) page 15 è Set Minimum & Maximum Y Position - Function 8 *********************************************** This function sets the minimum and maximum possible cursor positions on the screen. All cursor movement is restricted to this area once the area is set. The virtual screen determines the maximum and minimum values. If the cursor is outside the defined area when the call is made, it moves to just inside the area. If the minimum value is greater than the maximum the two values are switched. 8086 register : Input AX = 7 CX = new minimum vertical cursor position DX = new maximum vertical cursor position Output none Basic : Input M1% = 7 M3% = new minimum vertical cursor position M4% = new Maximum vertical cursor position Output none Example : 100 ; Limit cursor to vertical position between 100 and 200 200 M1% = 8 300 M3% = 100 400 M4% = 200 500 CALL Mouse(M1%,M2%,M3%,M4%) page 16 Define Graphics Cursor Block - Function 9 ******************************************* 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 of -16 to 16. They define one pixel within (or outside) the cursor block. 8086 register : Input AX = 9 BX = horizontal cursor hot spot CX = vertical cursor hot spot DX = pointer toscreen and cursor mask Output none Basic : Input M1% = 9 M2% = horizontal cursor hot spot M3% = vertical cursor hot spot M4% = pointer to sereen and cursor mask page 17 è Example : 100 ; 200 ; Define the screen mask 300 ; 400 cursor(0,0) = &hffff '1111111111111111 500 cursor(1,0) = &hffff '1111111111111111 600 cursor(2,0) = &hffff '1111111111111111 700 cursor(3,0) = &hffff '1111111111111111 800 cursor(4,0) = &hffff '1111111111111111 900 cursor(5,0) = &hffff '1111111111111111 1000 cursor(6,0) = &hffff '1111111111111111 1100 cursor(7,0) = &hffff '1111111111111111 1200 cursor(8,0) = &hffff '1111111111111111 1300 cursor(9,0) = &hffff '1111111111111111 1400 cursor(10,0) = &hffff '1111111111111111 1500 cursor(11,0) = &hffff '1111111111111111 1600 cursor(12,0) = &hffff '1111111111111111 1700 cursor(13,0) = &hffff '1111111111111111 1800 cursor(14,0) = &hffff '1111111111111111 1900 cursor(15,0) = &hffff '1111111111111111 2000 ; 2100 ; Define the cursor mask 2200 ; 2300 cursor(0,1) = &h8000 '1000000000000000 2400 cursor(1,1) = &hf000 '1110000000000000 2500 cursor(2,1) = &hf800 '1111100000000000 2600 cursor(3,1) = &hff00 '1111111000000000 2700 cursor(4,1) = &hd800 '1101100000000000 2800 cursor(5,1) = &h0c00 '0000110000000000 2900 cursor(6,1) = &h0600 '0000011000000000 3000 cursor(7,1) = &h0300 '0000001100000000 3100 cursor(8,1) = &h0000 '0000000000000000 3200 cursor(9,1) = &h0000 '0000000000000000 3300 cursor(10,1) = &h0000 '0000000000000000 3400 cursor(11,1) = &h0000 '0000000000000000 3500 cursor(12,1) = &h0000 '0000000000000000 3600 cursor(13,1) = &h0000 '0000000000000000 3700 cursor(14,1) = &h0000 '0000000000000000 3800 cursor(15,1) = &h0000 '0000000000000000 3900 ; 4000 ; Set the mouse cursor shape, color, and 4050 ; hot spot 4100 ; 4200 M1% = 9 4300 M2% = 0 'horixontal hot spot 4400 M3% = 0 'vartical hot sopt 4500 CALL Mouse(M1%,M2%,M3%,cursor(0,0)) page 18 Define Text Cursor - Function 10 ********************************** This function selects the software or hardware cursor. When the hardware cursor is selected this function sets the first and last scan lines which will be shown on the screen. The value of the parameter BX selects the cursor type. If the value is 0, the software text cursor is selected. If the value is 1, the hardware text cursor is selected. When the software text cursor is selected, the values of parameters CX and DX specify the screen and cursor masks. When the hardware cursor is selected, the parameters of CX and DX must contain the line numbers of the first and last scan line in the cursor to be shown on the screen. 8086 register : Input AX = 10 BX = select cursor CX = screen mask value/scan line start DX = cursor mask value/scan line stop Output none Basic : Input M1% = 10 M2% = select cursor M3% = screen mask value/scan line start M4% = cursor mask value/scan line stop Example : TO create a text crusor that inverts the foregrand and backgrand colors: 100 M1% = 10 110 M2% = 0 120 M3% = &hffff 130 M4% = &h7700 140 CALL Mouse(M1%,M2%,M3%,M4%) page 19 è Read Mouse Motion Counters - Function 11 ****************************************** 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. With the Default Accelerator installed the ratio of mouse to cursor movement is variable between 1/200 and 1/400. The step count is always within the range -32768 to 32767. A positive horizontal count specifies a motion to the right while a positive vertical count specifies a motion to the bottom of the screen. The step count is set to 0 after the call is completed. 8086 register : Input AX = 11 Output CX = horizontal count DX = vertical count Basic : Input M1% = 11 Output M3% = horizontal count M4% = vertical count Example : 100 ; Get the Michey count 200 M1% = 11 300 CALL Mouse(M1%,M2%,M3%,M4%) page 20 Define Event Handler - Function 12 ************************************ This routine 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 one or more of the conditions defined by the call mask occur. The call mask is a single integer value which defines the conditions which will 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-15 not used 8086 register : Input AX = 12 CX = call mask ES:DX = address of subroutine Output none Basic : Input M1% = 12 M3% = call mask M4% = ADDRESS offset to subroutine Output none Example : 100 ; Call subroutine SKETCH on Left Button press 200 M1% = 12 300 M3% = &h0002 400 M4% = SKETCH% 500 CALL Mouse(M1%,M2%,M3%,M4%) page 21 è Light Pen Emulation Mode On - Function 13 ******************************************** 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 both buttons are down. The pen is off the screen when both buttons are up. 8086 register : Input AX = 13 Output none Basic : Input M1% = 13 Output none Example : 100 ; Enable Light pen 200 M1% = 13 300 CALL Mouse(M1%,M2%,M3%,M4%) page 22 Light Pen Emulation Mode Off - Function 14 ******************************************* This function disables the light pen emulation mode. When light pen simulation is disabled, calls to the pen function return information about the light pen only. 8086 register : Input AX = 14 CX = new horizontal cursor position DX = new vertical cursor position Output none Basic : Input M1% = 14 M3% = new horizontal cursor position M4% = new vertical cursor position Example : 100 ; Disable Light pen 200 M1% = 14 300 CALL Mouse(M1%,M2%,M3%,M4%) page 23 Set Mouse Motion/Pixel Ratio - Function 15 ********************************************* 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 of 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. 8086 register : Input AX = 15 CX = horizontal step to pixel ratio DX = vertical step to pixel ratio Output none Basic : Input M1% = 15 M3% = horizontal step to pixel ratio m4% = vertical step to pixel ratio Output none Example : 100 ; Set mickey/pixel ratio at 16 to 8 AND 32 TO 8 200 M1% = 15 300 M3% = 16 400 M4% = 32 500 CALL Mouse(M1%,M2%,M3%,M4%) page 24 Conditional Off - Function 16 ******************************* This function allows the user to define an area on the screen within which the mouse will turn 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 about to update. 8086 register : Input AX = 16 CX = left margin DX = top margin SI = right margin DI = bottom margin Output none BASIC : Input M1% = 16 M4% = address of the region array Output none Example : 100 ; define screen region for conditional off 200 OFF%(1)=10 300 OFF%(2)=30 400 OFF%(3)=40 500 OFF%(4)=80 600 M1%=16 700 CALL MOUSE(M1%,M2%,M3%,off(0)) 800 ; Screen update routine : : 2000 M1%=1 2100 CALL MOUSE (M1%,M2%,M3%,M4%) page 25 Set Double-Speed Threshold - Function 19 ***************************************** Function 19 sets the threshold speed for doubling the cursor's motion on the screen. Using function 19 makes it easier to point at images widely separated on the screen. Parameter M4% defines the mouse's threshold speed. If no value is given, or if the mouse is reset by a call to function 0, a default value of 64 mickeys per second is assigned. If the mouse moves faster than the value of M4%, cursor motion doubles in speed. The threshold speed remains set until function 19 is called again or until the mouse is reset by function 0. Once your program turns on teh speed-doubling feature, this feature is always on. However, the program can effectively turn of this feature by setting M4% to a speed faster than the mouse can physically move (for example, 10,000) and then calling function 19. 8086 register : Input AX = 19 DX = threshold speed in mickeys/second Output none BASIC : Input M1% = 19 M4% = threshold speed in mickeys/second Output none page 26 Example : 100 ; 110 ; Set threshold to 32 mickeys/sec 120 ; 130 M1% = 19 140 M4% = 32 150 CALL Mouse (M1%,M2%,M3%,M4%) . . . . 1000 ; Turn off speed doubling 1010 M1% = 19 1020 M4% = 1000 'mickeys/second 1030 CALL Mouse(M1%,M2%,M3%,M4%) *************** END *************** è