/*------------------------ VIS_MOUS.TXT ------------------------*/ /* */ /* This file contains the VISIONS Mouse Library Manual */ /* */ /* Copyright 1990 Dan Vogel & David Bernazzani */ /* */ /* Date Initials Comments */ /* */ /* 07/26/90 DCV Initial Release 0.00. */ /*--------------------------------------------------------------*/ Overview The VISIONS mouse library written in C is intended to provide a clean C interface to the mouse driver functions as defined in the Microsoft Mouse Programmer's Reference. Although these routines closely follow the driver definitions, there are some enhancements provided by the VISIONS library. A prime example of this is the Mouse_CursorControl function. This function enables the user to display or hide the mouse cursor. Using VISIONS Mouse library calls, you can call this function to hide the cursor and it will be removed from the screen. Using direct driver calls would introduce uncertainty, since the cursor would only be removed from the screen if the display command had only been called once. Some other enhancements include a great deal of error checking to validate parameters and results, and a set of routines to convert between screen coordinates and virtual coordinates. The library was originally written in Microsoft C 5.1, but an attempt to separate compiler specific code into a separate source file was made, and this file, COMPSPEC.C, is provided as a separate the library. Theory of Operation The Mouse library is strongly based on the mouse function definitions in the Microsoft Mouse Programmer's Reference. This description will not be complete, but will focus on the differences in the VISIONS mouse library from the programmer's reference and the use of the mouse library within a program. The mouse library is intended to work with many adaptors running in different display modes. In order to make this easier, the mouse library defines all screen positions in terms of a set of virtual coordinates, which are then mapped onto the actual physical display and display mode. These virtual coordinates have an origin of 0,0 in the upper left hand corner of the screen. The range of values depends on the display mode, but is 640 by 200 for most modes of operation. This applies to text modes of display also! This means that to move the mouse to the character at 2,2 (text row 2, text column 2), you would actually have to move the cursor to virtual coordinates 8,8 (depending on the pixel size of a text character in the mode you are operating). The VISIONS Mouse library keeps track of the mode you are operating in and allows you to convert from physical (text coordinates in this case) coordinates to the virtual coordinates by calling the Mouse_VirToPhys routine. Similarly the Mouse library checks calls to set video pages and scan lines of cursors to verify that these parameters fall within the abilities of the display mode in use. Beyond these differences, the error checking is enhanced as can be seen from the routine specifications below. In using the Mouse library with VISIONS (or any other display routines) there are two major requirements. First the mouse must be reset after any change of video mode. This allows the VISIONS Mouse library to change its view of display mode capabilities. Second, it is strongly recommended that the mouse cursor be hidden during any display to the screen that might overwrite any part of the cursor. Otherwise the video might be distorted. The following is a summary of the mouse library routines. Mouse_Init - Fully initialize the mouse interface. Mouse_Reset - Reset and install mouse routines. Mouse_CursorControl - Display or Hide cursor. Mouse_Status - Query position of mouse and buttons. Mouse_SetPos - Set mouse screen position. Mouse_GetButtonPress - Query last button press. Mouse_GetButtonRel - Query last button release. Mouse_CursorLimits - Restrict cursor movement. Mouse_SetGCursor - Define graphics cursor. Mouse_SetTCursor - Define text cursor. Mouse_ReadMotion - Query mouse motion. Mouse_SetIntRoutine - Install user 'interrupt' routine. Mouse_LightPen - Light pen emulation mode. Mouse_SetMickey - Define mickey units. Mouse_ConditOff - Set restricted area for cursor. Mouse_SpeedThresh - Set double speed threshold. Mouse_SwapIntRoutine - Change user 'interrupt' routine. Mouse_GetStore - Query mouse state storage requirements. Mouse_SaveState - Query the mouse state. Mouse_RestoreState - Set the mouse state. Mouse_SetAlternateRoutine - Set alternate 'interrupt' routines. Mouse_GetAlternateRoutine - Query alternate 'interrupt' routines. Mouse_SetSensitivity - Set mouse motion sensitivity. Mouse_GetSensitivity - Query mouse motion sensitivity. Mouse_SetIntRate - Set mouse interrupt rate. Mouse_SetCRTpage - Set video page for cursor to appear on. Mouse_GetCRTpage - Query video page cursor is on. Mouse_DriverOnOff - Turn mouse driver on and off. Mouse_SoftReset - Reset mouse state. Mouse_SetLanguage - Select language for international mouse. Mouse_GetLanguage - Query language for international mouse. Mouse_GetVersion - Query mouse version and installation. Mouse_VirToPhys - Convert virtual to physical coordinates. Mouse_PhysToVir - Convert physical to virtuial coordinates. Routine Definitions In order to use the below routines you must include the file "USERMOUS.H" in your source code with the following statement. #include "USERMOUS.H" Examples of the use of these routines are available in the VISIONS demonstration program, in the file DEMOMOUS.C. /*------------------------------------------------------------------------*/ Mouse_Reset Purpose: This routine determines if a mouse has been installed, and if so it performs a complete initialization of the mouse and mouse interface. This routine must be called before any other mouse routine can be used! Calling Mouse_Init will in turn call this routine to initialize the mouse. Calling this routine multiple times within a program is not an error, if multiple resets are desired. Calling Sequence: status = Mouse_Reset(); Inputs: None. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NO_MOUSE Can not initialize mouse. Possibly no mouse installed. Functions called: Comp_Interrupt86, Comp_GetVector. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_Init Purpose: This routine determines if a mouse has already been initialized, and if not, it initializes the mouse. Calling Sequence: status = Mouse_Init(); Inputs: None. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NO_MOUSE Can not initialize mouse. Possibly no mouse installed. Functions called: Mouse_Reset. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_CursorControl Purpose: This routine determines if the mouse cursor is to be displayed or hidden. Note that this routine differs from the direct mouse interrupt call in that it maintains the state of the mouse's cursor display and only issues the display or hide mouse command to the driver when needed. This causes a difference in operation. For example, calling the mouse drivers directly twice to display the cursor, then once to hide the cursor after a reset will leave the cursor displayed, since the display cursor counter maintained by the mouse driver has not been zeroed. A second hide cursor call would be required to hide the cursor. This routine however will leave the cursor in the state last requested, regardless of the order or number of calls to hide or display the cursor. Calling Sequence: status = Mouse_CursorControl(cursor_set); Inputs: WORD cursor_set; - This is a flag indicating the desired cursor state. Possible values are: DISPLAY_CURSOR - Display the mouse cursor. HIDE_CURSOR - Hide the mouse cursor. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_CURS Bad cursor set parameter Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_Status Purpose: This routine returns the mouse's current button press status and position. Calling Sequence: status = Mouse_Status(&left,&right,&horiz,&vert); Inputs: None. Outputs: FLAG *left, *right; - These are flags indicating if the left and right buttons on the mouse are being pressed, TRUE, or not pressed, FALSE. UWORD *horiz, *vert; - These are the virtual coordinates of the mouse's current screen position. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_BUTTON Button's pressed return from mouse not understood. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetPos Purpose: This routine sets the position of the mouse cursor in virtual screen coordinates. The cursor display must be enabled for this to have a visible affect. Coordinates passed are automatically moved to nearest legal values. Calling Sequence: status = Mouse_SetPos(vert, horiz); Inputs: UWORD horiz, vert; - These are the desired virtual coordinates of the mouse's current screen position. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetButtonPress Purpose: This routine polls the mouse for information regarding button strikes, number of strikes, and location during last button strike, for the specified button. Calling Sequence: status = Mouse_GetButtonPress(button, &b_status, &b_press, &last_hor, &last_vrt); Inputs: WORD button; - This specifies for which button the information is desired. Possible values are LEFT_BUTTON and RIGHT_BUTTON. Outputs: FLAG *b_status; - This is a flag indicating, TRUE, the button is being pressed, or FALSE, it is not currently being pressed. UWORD *b_press; - This is the number of times this button was pressed since the last call to this routine. UWORD *last_hor, *last_vrt; - These are the coordinates of the mouse cursor at the time the button was last pressed. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_ILL_BUTTON Illegal button request Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetButtonRel Purpose: This routine polls the mouse for information regarding button releases, current button status, and location during last button release for the specified button. Calling Sequence: status = Mouse_GetButtonRel(button,&b_status,&b_rel,&last_hor,&last_vrt); Inputs: WORD button; - This specifies for which button the information is desired. Possible values are LEFT_BUTTON and RIGHT_BUTTON. Outputs: FLAG *b_status; - This is a flag indicating, TRUE, the button is being pressed, or FALSE, it is not currently being pressed. UWORD *b_rel; - This is the number of times this button was released since the last call to this routine. UWORD *last_hor, *last_vrt; - These are the coordinates of the mouse cursor at the time the button was last released. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_ILL_BUTTON Illegal button request Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_CursorLimits Purpose: This routine is used to set limits on the mouse cursor's screen movement. Coordinates used by this routine are tested for validity and are given in virtual screen coordiantes. Calling Sequence: status = Mouse_CursorLimits(ymin, xmin, height, width); Inputs: UWORD ymin, xmin, height, width; - These are the limits, in terms of top left corner and maximum ranges on the mouse's movements. These limits are in virtual coordinates. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_LIMITS Passed limit values are not legal Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetGCursor Purpose: This routine defines the graphics cursor appearance and the location of the hot spot relative to this cursor. Calling Sequence: status = Mouse_SetGCursor(horiz, vert, masks); Inputs: WORD horiz, vert; - These are the offsets of the hot spot relative to the top left corner of the cursor masks. Legal values range from -128 to 127. UWORD masks[32]; - These are the screen and cursor bit masks. The first 16 integers in the array form a 16 by 16 bit screen mask which is used to determine the effect of the cursor on the background it overlays, while the next 16 integers form the corresponding cursor bit mask the defines the appearance of the cursor. The display of the cursor consists of three operations, first the two 16 by 16 masks are rescaled to the resolution of the current video mode (ex: 8 by 16 in mode 4). Then the screen mask is applied to the pixel values currently displayed on the screen where the cursor is to appear. A 0 bit in the screen mask clears all color values for the corresponding screen pixel, while a 1 has no effect. Finally the cursor mask is applied to each pixel. A 0 in the cursor mask has no effect on the pixel, but a 1 in the cursor mask inverts the pixel's colors bits, normally turning it bright white. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_HSPOT Illegal hot spot value. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetTCursor Purpose: This routine defines the text cursor appearance and the type of the cursor, whether it be hardware cursor or software cursor. Calling Sequence: status = Mouse_SetTCursor(cur_type,scrn_mask,cur_mask,start_ln,stop_ln); Inputs: WORD cur_type; - This is the type of cursor selected. Possible values are: TEXT_SOFT_CURSOR for software text cursor, or TEXT_HARD_CURSOR for hardware text cursor. Note that the hardware text cursor is the same cursor that may normally be displayed on your screen in text mode. Thus selecting the hardware cursor while using standard C output routines will move the cursor as will the mouse causing confusion. Normally the software cursor is used here. UWORD scrn_mask, cur_mask; - These are the software text cursor masks used to define the software cursor. These values are only used if TEXT_SOFT_CURSOR is selected. These masks operate as follows: New char displayed = ((Current char value) AND screen mask XOR cursor mask The bits in the mask are: 0-7 ASCII character value 8-10 Foreground color 11 High or medium intensity 12-14 Background color 15 Blinking or not blinking UWORD start_ln, stop_ln; - This is the starting and stopping scan lines of the hardware text cursor. For most display adaptors these values range from 0 to 7. MDA ranges from 0 to 13. VGA and MCGA are unknown also 0 to 7. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_CURSEL Illegal cursor type selected. MOUSE_ERR_BAD_SLINES Bad scan line selections. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_ReadMotion Purpose: This routine reads the mouse's motion counters to determine how far it has moved since the last call to this routine. Calling Sequence: status = Mouse_ReadMotion(horiz, vert); Inputs: None. Outputs: WORD *horiz, *vert; - These are the distances traveled since the last call in mickeys(1/200"). A full range of integer values is possible, with positive values being down to the right. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetIntRoutine Purpose: This routine installs a user defined mouse interrupt routine. This interrupt routine will be executed whenever the condition mask is met. The user interrupt routine is not truly an interrupt routine, as it is called by the mouse driver interrupt handler and does not return with an IRET. An example of a valid interrupt routine is: LOCAL WORD u; WORD dummy(ax,bx,cx,dx,si,di) UWORD ax,bx,cx,dx,si,di; { u = u - 10; } where ax, bx, cx, dx, si, di contain values defining the interrupt. The user interrupt routine must not enable interrupts or make any system calls that enable interrupts. Furthermore the routine should be as short as possible and use as little stack as possible! Calling Sequence: status = Mouse_SetIntRoutine(call_mask, int_routine); Inputs: BITS call_mask; - This is the mask of conditions that are to cause this interrupt handler to be executed. The bits are defined as: 0 Cursor position changed (Execute on a 1 for any bit) 1 Left button pressed 2 Left button released 3 Right button pressed 4 Right button released 5-15 Not used int_routine - far *WORD(ax,bx,cx,dx,si,di) - This is the pointer to the routine to be executed when the above interrupt condition is met. The following values are passed to this routine: ax - Condition mask that caused interrupt. Same definition as call mask. bx - Current button state. TRUE for pressed, else FALSE. cx - Horizontal virtual cursor coordinate. dx - Vertical virtual cursor coordinate. si - Horizontal mouse counts in mickeys. di - Vertical mouse counts in mickeys. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_LightPen Purpose: This routine is responsible for setting the mouse into, or returning it from light pen emulation mode. Calling Sequence: status = Mouse_LightPen(mode); Inputs: FLAG mode; - This is a flag indicating if light pen emulation mode is to be set ON or OFF. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_LIGHT Illegal light pen emulation mode. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetMickey Purpose: This routine sets the mickey to 8 virtual screen pixel ratio for motion of the mouse, both horizontally and vertically. Calling Sequence: status = Mouse_SetMickey(hor_ratio, ver_ratio); Inputs: UWORD hor_ratio, ver_ratio; - These values indicate the number of mickeys per 8 virtual pixels for all virtual screens. Valid values range from 1 to 32767. The default horizontal ratio is 8 to 8, while the default vertical ratio is 16 to 8. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_RATIO Illegal mickey to pixel ratio specified. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_ConditOff Purpose: This routine allows a region to be defined on the screen where the mouse cursor will be hidden, should it enter the region. The user is responsible for redisplaying the mouse when it exits the region! Calling Sequence: status = Mouse_ConditOff(topy, topx, height, width); Inputs: UWORD topy, boty, height, width; - These are the virtual screen coordinates for the top left corner of a rectangular of the specified heighth and width where the mouse cursor will be hidden if it enters. Height and width must be > 0. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_LIMITS Coordinates specified are illegal. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SpeedThresh Purpose: This routine sets threshold for doubling the cursor speed on the screen. The threshold is defined in mickeys per second. The default value is 64 mickeys per second. A passed value of 0 resets the threshold to the default. The maximum value is undefined, but very large values can be used to effectively disable the double speed feature. Moving the mouse at a rate faster than this limit the cursor motion doubles in speed. Calling Sequence: status = Mouse_SpeedThresh(thresh); Inputs: UWORD thresh; - This is the speed threshold in mickeys per second. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SwapIntRoutine Purpose: This routine swaps one user defined mouse interrupt routine for a new one. See Mouse_SetIntRoutine for a full description of the interrupt functions. Calling Sequence: status = Mouse_SwapIntRoutine(call_mask,int_routine,&old_mask,&old_routine); Inputs: BITS call_mask; - This is the mask of conditions that are to cause this interrupt handler to be executed. The bits are defined as: 0 Cursor position changed (Execute on a 1 for any bit) 1 Left button pressed 2 Left button released 3 Right button pressed 4 Right button released 5-15 Not used int_routine - far *WORD(ax,bx,cx,dx,si,di) - This is the pointer to the routine to be executed when the above interrupt condition is met. ax - Condition mask that caused interrupt. Same definition as call mask. bx - Current button state. TRUE for pressed else FALSE. cx - Horizontal virtual cursor coordinate. dx - Vertical virtual cursor coordinate. si - Horizontal mouse counts in mickeys. di - Vertical mouse counts in mickeys. Outputs: BITS old_mask; - This is the mask of conditions that caused the old interrupt handler to be executed. The bits are defined the same as for call_mask. old_routine - far **WORD(ax,bx,cx,dx,si,di) - This is the pointer to the old interrupt routine that was swapped out. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86ext. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetStore Purpose: This routine returns the amount of storage required for storing the state of the mouse driver at any point in time. Calling Sequence: status = Mouse_GetStore(&buff_size); Inputs: None. Outputs: UWORD *buff_size; - This is the number of bytes needed for storing the mouse driver state. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SaveState Purpose: This routine saves the state of the mouse driver. This is useful for temporarily changing the mouse's parameters, and then restoring them when your routine or program is complete. Calling Sequence: status = Mouse_SaveState(buffer); Inputs: None. Outputs: UBYTE *buffer; - This is a pointer to the buffer that is to hold the stored mouse driver state. The caller is responsible for providing a buffer of adequate size. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86ext. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_RestoreState Purpose: This routine restores the state of the mouse driver to that which was saved in the passed buffer. Calling Sequence: status = Mouse_RestoreState(buffer); Inputs: UBYTE *buffer; - This is a pointer to the buffer that holds the stored mouse driver state. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86ext. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetAlternateRoutine Purpose: This routine installs an alternate call mask and user routine for up to three routines. The alternate routines aare like the standard interrupt routines with the difference that they are triggered by the use of one of the modifier keys, Alt, Ctrl, or Shift in combination with a mouse action, such as motion or a button press. Up to three simultaneous routines are supported, one for each modifier key. Calling Sequence: status = Mouse_SetAlternateRoutine(call_mask,int_routine); Inputs: BITS call_mask; - This is the mask of conditions that are to cause this interrupt handler to be executed. The bits are defined as: 0 Cursor position changed (Execute on a 1 for any bit) 1 Left button pressed 2 Left button released 3 Right button pressed 4 Right button released 5 Shift key pressed during button press or release 6 Ctrl key pressed during button press or release 7 Alt key pressed during button press or release 8-15 Not used A call mask of 0 will clear all alternate routines from the system! int_routine - far *WORD(ax,bx,cx,dx,si,di) - This is the pointer to the routine to be executed when the above interrupt condition is met. ax - Condition mask that caused interrupt. Same definition as call mask. bx - Current button state. TRUE if pressed, otherwise FALSE. cx - Horizontal virtual cursor coordinate. dx - Vertical virtual cursor coordinate. si - Horizontal mouse counts in mickeys. di - Vertical mouse counts in mickeys. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_ALT_BAD Error occurred during set alternate. Type of error internal to interrupt call. Functions called: Comp_Interrupt86ext. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetAlternateRoutine Purpose: This routine gets the last defined alternate call mask and user routine that matches the passed modifier key bit. Calling Sequence: status = Mouse_GetAlternateRoutine(&call_mask, &int_routine); Inputs: BITS *call_mask; - This is the mask of conditions that are to cause this interrupt handler to be executed. The bits are defined as: 0 Cursor position changed (Execute on a 1 for any bit) 1 Left button pressed 2 Left button released 3 Right button pressed 4 Right button released 5 Shift key pressed during button press or release 6 Ctrl key pressed during button press or release 7 Alt key pressed during button press or release 8-15 Not used A value is received in this parameter containing the modifier key bit whose alternate routine and call mask are to be returned. The call mask is returned in this parameter. Multiple set modifier key bit in the received parameter will cause undefined results. Outputs: int_routine - far **WORD(ax,bx,cx,dx,si,di) - This is the pointer to the routine to be executed when the above interrupt condition is met. ax - Condition mask that caused interrupt. Same definition as call mask. bx - Current button state. TRUE if pressed, otherwise FALSE. cx - Horizontal virtual cursor coordinate. dx - Vertical virtual cursor coordinate. si - Horizontal mouse counts in mickeys. di - Vertical mouse counts in mickeys. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_NO_ALT No alternate routines defined to return. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetSensitivity Purpose: This routine sets the mouse to cursor movement sensitivity and double speed threshold. Calling Sequence: status = Mouse_SetSensitivity(horiz, vert, thresh); Inputs: UWORD horiz, vert, thresh; - These are the sensitity numbers for horizontal and vertical movement, ranging from 1 to 100, and the threshold for double speed, also ranging from 1 to 100. Default values for all three are 50, which sets a mickey factor of 1, and a threshold of 64 mickeys per second. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_SENSE Bad sensitivity parameters. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetSensitivity Purpose: This routine returns the mouse to cursor movement sensitivity and double speed threshold. Calling Sequence: status = Mouse_GetSensitivity(&horiz, &vert, &thresh); Inputs: None. Outputs: UWORD *horiz, *vert, *thresh; - These are the sensitity numbers for horizontal and vertical movement, ranging from 1 to 100, and the threshold for double speed, also ranging from 1 to 100. Default values for all three are 50, which sets a mickey factor of 1, and a threshold of 64 mickeys per second. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_SENSE Bad sensitivity parameters. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetIntRate Purpose: This routine sets the interrupt rate for InPort mouse(s) only. Calling Sequence: status = Mouse_SetIntRate(rate); Inputs: UWORD rate; - This is the interrupt rate at which to set the mouse. Possible values are: 0 No interrupts. 1 30 ints per second 2 50 ints per second 3 100 ints per second 4 200 ints per second >4 Illegal values Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_IRATE Illegal interrupt rate specified. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetCRTpage Purpose: This routine defines CRT page on which the mouse cursor will be displayed. Calling Sequence: status = Mouse_SetCRTpage(page_num); Inputs: UWORD page_num; - This is the page number to set. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_PAGE Illegal page number parameter. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetCRTpage Purpose: This routine reads the CRT page on which the mouse cursor is displayed. Calling Sequence: status = Mouse_GetCRTpage(&page_num); Inputs: None. Outputs: UWORD *page_num; - This is the page number to which the mouse cursor is set. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_DriverOnOff Purpose: This routine allows the mouse driver to be enabled or disabled. Calling Sequence: status = Mouse_DriverOnOff(mode, old_seg, old_off); Inputs: UWORD mode; - This is the mode that the driver is to be set to. Possible values are ON or OFF. UWORD *old_seg, *old_off; - This is the vector that was in at interrupt 33H before the mouse driver was enabled. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_MODE Illegal driver mode parameter. MOUSE_ERR_CANT_DISABLE Unable to disable mouse driver. Functions called: Comp_Interrupt86ext. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SoftReset Purpose: This routine resets software values of the mouse only. This include cursor definitions, positions, interrupt calls, cursor position limits, and ratios. Calling Sequence: status = Mouse_SoftReset(); Inputs: None. Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_NOT_RESET Mouse driver not reset by call. Functions called: Mouse_SetAlternateRoutine. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_SetLanguage Purpose: This routine sets the language to be used in the international version of the mouse driver. Calling Sequence: status = Mouse_SetLanguage(lang_num); Inputs: UWORD lang_num; - This is the language selected. Possible values are: ENGLISH 0 English FRENCH 1 French DUTCH 2 Dutch GERMAN 3 German SWEDISH 4 Swedish FINNISH 5 Finnish SPANISH 6 Spanish PORTUGUESE 7 Portuguese ITALIAN 8 Italian Outputs: WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. MOUSE_ERR_BAD_LANGUAGE Bad language parameter selected. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetLanguage Purpose: This routine returns the current language setting for the international version of the mouse driver. Calling Sequence: status = Mouse_GetLanguage(&lang_num); Inputs: None. Outputs: UWORD *lang_num; - This is the language number in use. This number corresponds to the same table as in Mouse_SetLanguage. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_GetVersion Purpose: This routine returns the current driver version number, the mouse type, and the IRQ line in use. Calling Sequence: status = Mouse_GetVersion(&version, &mouse_type, &irq_num); Inputs: None. Outputs: UWORD *version; - This is the driver version number in hex. The MSB is the major version number while the LSB is the minor version number. UWORD *mouse_type; - This is the mouse type. Possibilities are: 1 Bus mouse 2 Serial mouse 3 InPort mouse 4 PS/2 mouse 5 Hewlett-Packard mouse UWORD *irq_num; - This is the irq line in use. Possible values are: 0 PS/2 machine 2-5,7 IRQ number. WORD status; - This is the result of this routine. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_NOT_INIT Mouse must be initialized before this call. Functions called: Comp_Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_VirToPhys Purpose: This routine converts a set of virtual coordinates to physical coordinates given the current mappings. The mappings are set during calls to Mouse_Reset, Mouse_CursorLimits, and Mouse_ConditOff and are based upon the video configuration at that time. Calling Sequence: Mouse_VirToPhys(xcoor, ycoor, &physx, &physy); Inputs: UWORD xcoor, ycoor; - These are the virtual x and y coordinates. Outputs: UWORD *physx, *physy; - These are the resulting physical coordinates. They may be either in text or graphics coordinate sets, depending on the video configuration. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_PhysToVir Purpose: This routine converts a set of physical coordinates to virtual coordinates given the current mappings. The mappings are set during calls to Mouse_Reset, Mouse_CursorLimits, and Mouse_ConditOff and are based upon the video configuration at that time. Calling Sequence: Mouse_PhysToVir(ycoor, xcoor, &virty, &virtx); Inputs: UWORD xcoor, ycoor; - These are the physical x and y coordinates. Outputs: UWORD *physx, *physy; - These are the resulting virtual coordinates. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_AllocAndSave Purpose: This routine determines how much space is needed to save the state of the mouse, allocates a buffer for this, and saves the state. Calling Sequence: status = Mouse_AllocAndSave(&buffer); Inputs: None. Outputs: UBYTE **buffer; - This is a pointer to the buffer allocated where the state is saved. WORD status; - This is the result of the function. Possible values are: MOUSE_ERR_NO_ERR SUCCESS MOUSE_ERR_BAD_ALLOC Unable to allocate buffer. As returned by called routines. Functions called: Mouse_GetStore, Mouse_SaveState. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_TextCursorLimits Purpose: This routine allows the user to set the limits of mouse cursor movement using text coordinates, and turn the cursor on. Calling Sequence: status = Mouse_TextCursorLimits(top_y, top_x, hite, width, on_off); Inputs: UBYTE top_y, top_x, hite, width; - These are the text coordinates of the mouse area that cursor movement is to be restricted to. FLAG on_off; - This is the desired state of the mouse cursor, on or off. Outputs: WORD status; - This is the result of the function. Possible values are: MOUSE_ERR_NO_ERR SUCCESS As returned by called routines. Functions called: Mouse_PhysToVir, Mouse_CursorLimits, Mouse_SetPos, Mouse_CursorControl. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Mouse_ClearButtons Purpose: This routine clears any pending button press information. Calling Sequence: status = Mouse_ClearButtons(); Inputs: None. Outputs: WORD status; - This is the result of the function. Possible values are: MOUSE_ERR_NO_ERR SUCCESS As returned by called routines. Functions called: Mouse_GetButtonPress. /*------------------------------------------------------------------------*/ Error Codes The following is the list of error codes that can be returned from the VISIONS mouse library. Error Name Value Description. MOUSE_ERR_NO_ERR 0 Successful completion of call. MOUSE_ERR_NO_MOUSE -600 Unable to find mouse to initialize. MOUSE_ERR_NOT_INIT -601 Mouse not initialized yet. MOUSE_ERR_BAD_BUTTON -602 Button press returned from INT strange. MOUSE_ERR_BAD_CURS -603 Illegal cursor on/off command. MOUSE_ERR_ILL_BUTTON -604 Illegal button number specified. MOUSE_ERR_BAD_LIMITS -605 Screen limits for cursor illegal. MOUSE_ERR_BAD_HSPOT -606 Bad hot spot specification. MOUSE_ERR_BAD_CURSEL -607 Bad text cursor type selection. MOUSE_ERR_BAD_SLINES -608 Bad start or stop scan lines selected. MOUSE_ERR_BAD_LIGHT -609 Bad light pen emulation mode passed. MOUSE_ERR_BAD_RATIO -610 Illegal value for mickey/pixel ratio. MOUSE_ERR_ALT_BAD -611 Interrupt call to set alt returns error. MOUSE_ERR_BAD_SENSE -612 Illegal mouse sensitivity parameters. MOUSE_ERR_NO_ALT -613 No alternate routine defined to return. MOUSE_ERR_BAD_IRATE -614 Bad interrupt rate selected. MOUSE_ERR_BAD_PAGE -615 Bad CRT page number parameter. MOUSE_ERR_BAD_MODE -616 Illegal driver mode parameter. MOUSE_ERR_CANT_DISABLE -617 Unable to disable mouse driver. MOUSE_ERR_BAD_LANGUAGE -618 Illegal language parameter. MOUSE_ERR_NOT_RESET -619 Mouse reset command returned error. MOUSE_ERR_BAD_ALLOC -620 Unable to allocate state buffer.