home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / progbas / qbnws203.arj / MOUSE.ZIP / MOUSE.REF < prev    next >
Encoding:
Text File  |  1991-09-13  |  19.3 KB  |  590 lines
  1.  
  2. =======================================================================
  3.                        Routine Reference Section
  4. =======================================================================
  5.  
  6.    Mouse interface for QuickBASIC V4.x, Microsoft BASIC 6.X, and the
  7.    Microsoft BASIC Professional Development System 7.X.
  8.  
  9.    Written by Tony Elliott (CIS 76220,2575)
  10.               EllTech Development, Inc.
  11.               4374 Shallowford Industrial Pkwy
  12.               Marietta, GA 30066
  13.  
  14.    For QBNews and released into the Public Domain.
  15. =======================================================================
  16.  
  17. MouseAlreadyReset%
  18.  
  19. Checks to see if the current program has already reset the mouse.
  20. If so, returns the number of buttons the mouse has, otherwise returns
  21. zero.
  22.  
  23.      From BASIC:
  24.  
  25.       DECLARE FUNCTION MouseAlreadyReset% ()
  26.  
  27.      Buttons% = MouseAlreadyReset%
  28.       IF Buttons% THEN
  29.         PRINT "Mouse with"; Buttons%;" buttons has already been reset."
  30.       ELSE
  31.         PRINT "Mouse has not yet been reset."
  32.       END IF
  33.  
  34. -----------------------------------------------------------------------
  35.  
  36. MouseCancelEvent
  37.  
  38. Cancels (disables) active mouse event handler.
  39.  
  40.      From BASIC:
  41.  
  42.        DECLARE SUB MouseCancelEvent ()
  43.        CALL MouseCancelEvent
  44.  
  45. -----------------------------------------------------------------------
  46.  
  47. MouseExit
  48.  
  49. This code should be called prior to program termination. It performs
  50. such tasks as releasing memory allocated by the mouse routines and
  51. unhooking the mouse routines from the mouse driver's "User Defined
  52. Event" handler. Failure to call this routine prior to program
  53. termination could result is a system lockup if the MouseSetEvent
  54. routine has been previously called and the MouseCancelEvent routine was
  55. not.
  56.  
  57. During the call to the MouseReset routine, we attempted to add this
  58. routine to BASIC's B_OnExit chain. This allows BASIC itself to call
  59. this code when your program terminates or restarts. In other words, you
  60. probably won't have to worry about it. It is a pretty rare occurrence
  61. that the B_OnExit call would fail - more than 32 other procedures would
  62. have to be registered before it would fail.
  63.  
  64. But for those faint of heart, we've gotcha covered. The function
  65. MouseOnExit% returns true if we are successfully included in the
  66. B_OnExit chain. If it returns false, the you need to call this routine
  67. (MouseExit) manually before your program terminates. For example:
  68.  
  69.      IF NOT MouseOnExit% THEN
  70.         CALL MouseExit
  71.      END IF
  72.      END
  73.  
  74. -----------------------------------------------------------------------
  75.  
  76. MouseGetEventInfo
  77.  
  78. Returns the values captured during the last mouse event
  79.  
  80.     From BASIC:
  81.  
  82.        DECLARE SUB MouseGetEventInfo(EventType%, Lb%, Rb%, Cb%, Row%, _
  83.                                      Column%)
  84.        CALL MouseGetEventInfo(EventType%, Lb%, Rb%, Cb%, Row%, Column%)
  85.  
  86. EventType% is bit-mapped and indicates what condition(s) triggered the
  87. mouse event. Just "AND" Event% with a value associated with one of your
  88. defined events. If the result is non-zero then that was what triggered
  89. the event. For example:
  90.  
  91.        PRINT "Event cause: "
  92.        IF Event% AND 4 THEN            '4 is value for "left release"
  93.           PRINT "Left button was released."
  94.        ELSEIF Event% AND 16 THEN       '16 is value for "right release"
  95.           PRINT "Right button was released."
  96.        END IF
  97.  
  98. See MouseSetEvent for a complete listing of all available events and
  99. their respective values.
  100.  
  101. The other parameters reflect the state of the mouse at the time of the
  102. last event. See MouseGetStatus for info on how to interpret their
  103. meanings.
  104.  
  105. -----------------------------------------------------------------------
  106.  
  107. MouseGetInfo
  108.  
  109.      Returns information about the current mouse hardware and software:
  110.  
  111.  MajorVer% - The Major mouse driver version (7 for 7.04). It is
  112.              returned as zero if the mouse has not been initialized.
  113.  
  114.  MinorVer% - The Minor mouse driver version (4 for 7.04)
  115.  
  116. MouseType% - 1 = bus mouse, 2 = serial mouse, 3 = InPort mouse,
  117.              4 = PS/2 mouse, 5 = HP mouse
  118.  
  119.       Irq% - The hardware Irq line that the mouse driver is using. 0 =
  120.              PS/2, or 2, 3, 4, 5, or 7 for all others.
  121.  
  122.     From BASIC:
  123.  
  124.        DECLARE SUB MouseGetInfo(MajorV%, MinorV%, MouseType%, Irq%)
  125.        CALL MouseGetInfo(MajorV%, MinorV%, MouseType%, Irq%)
  126.  
  127. -----------------------------------------------------------------------
  128.  
  129. MouseGetPage%
  130.  
  131. Returns the display page the mouse pointer is currently visible on. See
  132. MouseSetPage to change the pointer's current display page. Returns -1
  133. if the mouse has not yet been initialized.
  134.  
  135.     From BASIC:
  136.  
  137.        DECLARE FUNCTION MouseGetPage% ()
  138.  
  139.        PRINT "The current pointer display page is" MouseGetPage%
  140.  
  141. -----------------------------------------------------------------------
  142.  
  143. MouseGetSensitivity
  144.  
  145.      Returns the current mouse "sensitivity" related settings. See the
  146.      routines MouseSetRatio and MouseSetDblSpd for more information
  147.  
  148.     From BASIC:
  149.  
  150.        DECLARE SUB MouseGetSensitivity (VertRatio%, HorizRatio%, _
  151.                                         DblSpd%)
  152.        CALL MouseGetSensitivity (VertRatio%, HorizRatio%, DblSpd%)
  153.  
  154. -----------------------------------------------------------------------
  155.  
  156. MouseGetStatus
  157.  
  158. Returns the current "real time" state of the mouse buttons and the
  159. mouse pointers current position in row/column coordinates. A value of -
  160. 1 (TRUE) returned for Lb%, Rb% or Cb% indicates that the respective
  161. button is currently pressed and a value of zero (FALSE) indicates the
  162. button is not pressed.
  163.  
  164.     From BASIC:
  165.  
  166.        DECLARE SUB MouseGetStatus(Lb%, Rb%, Cb%, Row%, Column%)
  167.  
  168.        CALL MouseGetStatus(Lb%, Rb%, Cb%, Row%, Column%)
  169.  
  170. -----------------------------------------------------------------------
  171.  
  172. MouseInstalled%
  173.  
  174. Check to see if a mouse is installed WITHOUT resetting it. The
  175. MouseReset function will still have to be invoked before the other
  176. mouse routines will function.
  177.  
  178.     From BASIC:
  179.  
  180.       DECLARE FUNCTION MouseInstalled% ()
  181.  
  182.       IF MouseInstalled% THEN
  183.          PRINT "A mouse IS installed."
  184.       ELSE
  185.          PRINT "A mouse was not detected."
  186.       END IF
  187.  
  188. -----------------------------------------------------------------------
  189.  
  190. MouseMovement
  191.  
  192. Returns the net mouse displacement since the last call to this routine.
  193. In other words, it tells you how many "Mickeys" (approx 1/200th of an
  194. inch) the mouse has moved from it's position the last time this routine
  195. was called.
  196.  
  197.      From BASIC:
  198.  
  199.        DECLARE SUB MouseMovement (Rows%, Columns%)
  200.  
  201.        CALL MouseMovement (Rows%, Columns%)
  202.  
  203. -----------------------------------------------------------------------
  204.  
  205. MousePixelsOff
  206.  
  207. Sets an internal flag which tells us to return mouse coordinates in
  208. base 1 row/column format. This the default. You need to call this
  209. routine only if you have previously called the MousePixelsOn routine
  210. and you wish to return to row/column coordinates.
  211.  
  212.     From BASIC:
  213.  
  214.       DECLARE SUB MousePixelsOff ()
  215.  
  216.       CALL MousePixelsOff
  217.  
  218. -----------------------------------------------------------------------
  219.  
  220. MousePixelsOn
  221.  
  222. Sets an internal flag which tells us to return mouse coordinates in
  223. pixel format. The default is to return base 1 row/column coordinates
  224. like BASIC uses. Use the routine MousePixelsOff to reset the coordinate
  225. system back to row/columns.
  226.  
  227.     From BASIC:
  228.  
  229.       DECLARE SUB MousePixelsOn ()
  230.  
  231.       CALL MousePixelsOn
  232.  
  233. -----------------------------------------------------------------------
  234.  
  235. MousePointerOff
  236.  
  237. This routine makes the mouse pointer visible. Please see the special
  238. note under the MousePointerOn routine for details about the mouse
  239. driver's internal counter.
  240.  
  241.     Note: Even though the mouse pointer is not visible, the driver
  242.           continues to track the mouse pointer position.
  243.  
  244.     From BASIC:
  245.  
  246.       DECLARE SUB MousePointerOff ()
  247.  
  248.       CALL MousePointerOff
  249.  
  250. -----------------------------------------------------------------------
  251.  
  252. MousePointerOn
  253.  
  254. Displays the mouse pointer (cursor) and cancels any previous mouse
  255. exclusion area defined with the routine MouseSetExclusionArea.
  256.  
  257. Note: Each time this routine is called, the mouse driver increments an
  258.       internal counter. The MousePointerOff routine decrements the
  259.       counter. The MouseReset routine set the counter to an initial
  260.       value of -1. While the counter < 0 the mouse pointer will be
  261.       hidden and when the counter >= 0 the pointer is visible.
  262.       In other words, if MousePointerOff was called three
  263.       successive times, MousePointerOn would have to be called three
  264.       times before the pointer would be physically turned back on.
  265.  
  266.     From BASIC:
  267.  
  268.       DECLARE SUB MousePointerOn ()    'This is optional.
  269.  
  270.       CALL MousePointerOn
  271.  
  272. -----------------------------------------------------------------------
  273.  
  274. MousePressInfo%
  275.  
  276. Returns the number of times the specified mouse button has been pressed
  277. since the last time this routine was called. It also returns the
  278. position where the specified button was pressed.
  279.  
  280.      From BASIC:
  281.  
  282.        DECLARE FUNCTION MousePressInfo% (Button%, Row%, Column%)
  283.  
  284.        NumberOfPresses% = MousePressInfo%(Button%, Row%, Column%)
  285.  
  286. On entry, Button% = 0 for the left button
  287.                     1 for the right button
  288.                     2 for the center button (if any)
  289.  
  290. On exit, the result of the function indicates the number of times the
  291. specified button has been pressed since this routine was last called.
  292. Row% and Column% will contain the coordinates where the specified
  293. button was last pressed. The current coordinate system is used (See
  294. MousePixelsOn and MousePixelsOff).
  295.  
  296. -----------------------------------------------------------------------
  297.  
  298. MouseReleaseInfo%
  299.  
  300. Returns the number of times the specified mouse button has been
  301. released since the last time this routine was called. It also returns
  302. the position where the specified button was last released.
  303.  
  304.      From BASIC:
  305.  
  306.        DECLARE FUNCTION MouseReleaseInfo% (Button%, Row%, Column%)
  307.  
  308.        NumberOfReleases% = MouseReleaseInfo%(Button%, Row%, Column%)
  309.  
  310. On entry, Button% = 0 for the left button
  311.                     1 for the right button
  312.                     2 for the center button (if any)
  313.  
  314. On exit, the result of the function indicates the number of times the
  315. specified button has been released since this routine was last called.
  316. Row% and Column% will contain the coordinates where the specified
  317. button was last released. The current coordinate system is used (See
  318. MousePixelsOn and MousePixelsOff).
  319.  
  320. -----------------------------------------------------------------------
  321.  
  322. MouseReset%
  323.  
  324. Initializes the mouse. The mouse driver is initialized to the following
  325. state:
  326.  
  327.       - Mouse pointer is at the center of the screen
  328.       - Display page for mouse set to 0
  329.       - Mouse pointer is hidden (off)
  330.       - Mouse pointer shape is the default arrow shape in the graphics
  331.         video modes or a reverse block in the text modes.
  332.  
  333.      From BASIC:
  334.  
  335.       DECLARE FUNCTION MouseReset% ()
  336.  
  337.       Buttons% = MouseReset%
  338.       IF Buttons% THEN
  339.         PRINT "Mouse with";Buttons%;" buttons is installed and reset."
  340.       ELSE
  341.         PRINT "Mouse not detected."
  342.       END IF
  343.  
  344. -----------------------------------------------------------------------
  345.  
  346. MouseRestoreState
  347.  
  348. Restores the state of the mouse if previously saved with the
  349. MouseSaveState routine. See the MouseSaveState routine for additional
  350. usage notes.
  351.  
  352.     From BASIC:
  353.  
  354.        DECLARE SUB MouseRestoreState ()
  355.        CALL MouseRestoreState
  356.  
  357. -----------------------------------------------------------------------
  358.  
  359. MouseSaveState
  360.  
  361. Save the current mouse state including, position, visibility, and other
  362. characteristics. You could use this routine prior to SHELLing another
  363. program which could use the mouse.
  364.  
  365. The MouseRestoreState routine restores the previous state of the mouse.
  366.  
  367. This routine make a call to BASIC's SETMEM code to release enough
  368. memory to DOS to save the mouse state. When the MouseRestoreState
  369. routine is CALLed, the memory is released from DOS and given back to
  370. BASIC.
  371.  
  372. Note: This routine can be DECLAREd as a SUB or a FUNCTION. If declared
  373.       as an integer FUNCTION, -1 (TRUE) is returned if the state was
  374.       saved successfully and 0 (FALSE) if unsuccessful (due to
  375.       insufficient memory). If you don't care about the success or
  376.       failure of the operation, you can simply DECLARE it as a SUB
  377.       without parameters.
  378.  
  379.     From BASIC:
  380.  
  381.        DECLARE SUB MouseSaveState ()
  382.        CALL MouseSaveState
  383.  
  384.           -or-
  385.  
  386.        DECLARE FUNCTION MouseSaveState% ()
  387.        IF MouseSaveState% THEN
  388.            PRINT "Mouse state saved successfully"
  389.        ELSE
  390.            PRINT "Insufficient memory to save mouse state!"
  391.        END IF
  392.  
  393. -----------------------------------------------------------------------
  394.  
  395. MouseSetDblSpd
  396.  
  397. Sets the mouse pointer "double speed threshold". If the mouse is moved
  398. faster than the specified number of MickeysPerSecond, the mouse pointer
  399. will kick into overdrive and effectively move twice as fast. The
  400. default is 64 Mickeys (approx 1/3 inch) per second.
  401.  
  402. Passing a large value (such as 10,000) effectively disables the speed
  403. doubling effect.
  404.  
  405.     From BASIC:
  406.  
  407.        DECLARE SUB MouseSetDblSpd (MickeysPerSecond%)
  408.  
  409.        CALL MouseSetDblSpd(200)          'Set it to 1 inch per second
  410.  
  411. -----------------------------------------------------------------------
  412.  
  413. MouseSetEvent
  414.  
  415. This routine sets up a "Mouse Event" handler which can be trapped in
  416. your BASIC program via "ON UEVENT".
  417.  
  418. The following are the available events that can be trapped. Any
  419. combination of events are acceptable. Each event has a value associated
  420. with it. Define the desired event by assigning its value to the
  421. EventMask% parameter when calling this routine. Combinations of events
  422. can be obtained by adding the values of the respective events. For
  423. example, to set an event for "left button release" and "right button
  424. release", simply add the values together: 4 + 16 = 20.
  425.  
  426.        1 = Any mouse movement
  427.        2 = Left button pressed
  428.        4 = Left button released
  429.        8 = Right button pressed
  430.       16 = Right button released
  431.       32 = Center button pressed
  432.       64 = Center button released
  433.  
  434.     From BASIC:
  435.  
  436.        DECLARE SUB MouseSetEvent (EventMask%)
  437.        CALL MouseSetEvent(20)       'Traps left or right button release
  438.  
  439.        ON UEVENT GOSUB MouseEvent
  440.        UEVENT ON
  441.  
  442.        DO                           'Continue processing event until
  443.            A$ = INKEY$              ' a key is pressed.
  444.        LOOP UNTIL LEN(A$)
  445.        END
  446.  
  447.     MouseEvent:
  448.       CALL MouseGetEventInfo(Event%, Lb%, Rb%, Cb%, Row%, Column%)
  449.       PRINT "Mouse event occurred: - "
  450.       IF Event% AND 4 THEN
  451.          PRINT "Left Button was released."
  452.       END IF
  453.       IF Event% AND 16 THEN
  454.          PRINT "Right Button was released."
  455.       END IF
  456.       PRINT "Mouse location:" Row% "," Column%
  457.     RETURN
  458.  
  459. -----------------------------------------------------------------------
  460.  
  461. MouseSetExclusionArea
  462.  
  463. If the mouse pointer is moved into the rectangular area of the screen
  464. defined by this routine, the mouse pointer will be turned off.
  465.  
  466.     From BASIC:
  467.  
  468.        DECLARE SUB MouseSetExclusionArea (TopRow%, LeftColumn%, _
  469.                                           BottomRow%, RightColumn%)
  470.  
  471.        CALL MouseSetExclusionArea (1, 1, 3, 80)
  472.  
  473. -----------------------------------------------------------------------
  474.  
  475. MouseSetHardwarePointer
  476.  
  477. Defines the shape and characteristics of the mouse pointer used in text
  478. video modes. The "hardware" cursor is simply a character block which
  479. the programmer can control the starting scan line and the ending scan
  480. line (i.e., the size and shape of the block). When the hardware cursor
  481. is moved over the screen, it appears as a blinking block.
  482.  
  483.     From BASIC:
  484.  
  485.        DECLARE SUB MouseSetHardwarePointer(StartScan%, EndScan%)
  486.  
  487.        CALL MouseSetHardwarePointer(0, 7)
  488.  
  489. -----------------------------------------------------------------------
  490.  
  491. MouseSetPage
  492.  
  493. Sets the current mouse pointer display page. Be sure that your current
  494. video mode supports the specified page number. See BASIC's SCREEN
  495. statement documentation for more info.
  496.  
  497.     From BASIC:
  498.  
  499.        DECLARE SUB MouseSetPage(PointerPage%)
  500.        CALL MouseSetPage(1)
  501.  
  502. -----------------------------------------------------------------------
  503.  
  504. MouseSetPointer
  505.  
  506. Set the mouse pointer position. The format for the coordinates is based
  507. on the most recent call to either of MousePixelsOn or MousePixelsOff.
  508. If neither have been previously called, row/column coordinates is the
  509. default.
  510.  
  511. If coordinates provided are outside the physical screen or outside of
  512. the vertical or horizontal limits set by the MouseSetWindow routine,
  513. the coordinates are adjusted automatically.
  514.  
  515.      From BASIC:
  516.  
  517.        DECLARE SUB MouseSetPointer(Row%, Column%)
  518.  
  519.        CALL MouseSetPointer(Row%, Column%)
  520.  
  521. -----------------------------------------------------------------------
  522.  
  523. MouseSetRatio
  524.  
  525. Sets the ratio between the amount mouse physical mouse movement
  526.  (Mickeys) and the amount of movement reflect by the mouse pointer on
  527. the screen. The value passed in reflects the number of Mickeys required
  528. to move the pointer 8 pixels. The default is 8 Mickeys per 8 pixels (1
  529. Mickey per pixel) horizontal and 16 Mickeys per 8 pixels (2 Mickeys per
  530. pixel) of vertical movement. A value between 1 and 32767 Mickeys can be
  531. specified.
  532.  
  533.     From BASIC:
  534.  
  535.        DECLARE SUB MouseSetRatio (VertRatio%, HorizRatio%)
  536.  
  537.        CALL MouseSetRatio(8, 4)        'Doubles mouse sensitivity
  538.  
  539. -----------------------------------------------------------------------
  540.  
  541. MouseSetSoftwarePointer
  542.  
  543. Sets characteristics of mouse "software" pointer. This type of pointer
  544. is used only in text modes and physically manipulates whatever
  545. character and attribute that is under it. The values passed in AndMask%
  546. and in XorMask%) determine exactly how the character and attribute will
  547. be manipulated.
  548.  
  549.     From BASIC:
  550.  
  551.        DECLARE SUB MouseSetSoftwarePointer (AndMask%, XorMask%)
  552.  
  553.        CALL MouseSetSoftwarePointer(&H77ff, &H7700)
  554.  
  555. The AND mask determines what part of the character/attribute pair will
  556. be passed through and the XOR mask determines which of the resulting
  557. bits will be toggled. In each case, the low byte of the integer applies
  558. to the character and the high bytes applies to the attribute.
  559.  
  560. -----------------------------------------------------------------------
  561.  
  562. MouseSetWindow
  563.  
  564. Set the coordinates for a window in which the mouse pointer is allowed
  565. to move. By default, the pointer is allowed to move freely over the
  566. entire screen. This routine allows you to limit the mouse pointer's
  567. movement to a specific rectangular area of the screen.
  568.  
  569.      From BASIC:
  570.  
  571.        DECLARE SUB MouseSetWindow(TopRow%, LeftColumn%, BottomRow%,_
  572.                                   RightColumn%)
  573.  
  574.        CALL MouseSetWindow(10, 10, 20, 70)
  575.  
  576. -----------------------------------------------------------------------
  577.  
  578. MouseWaitForRelease
  579.  
  580. Waits for all mouse buttons to be released before returning control to
  581. the calling program.
  582.  
  583.     From BASIC:
  584.  
  585.        DECLARE SUB MouseWaitForRelease ()
  586.  
  587.        CALL MouseWaitForRelease
  588.  
  589. -----------------------------------------------------------------------
  590.