Click above to get retro games delivered to your door ever month!

The Mouse Package

   This package provides an interface to a compatible mouse driver. It
   allows full control of the mouse including position reports, button
   status and counters, sensitivity, cursor shape and control and the
   ability to install a mouse signal handler.

   The Mouse package is a C interface to the Microsoft mouse. Its use
   requires a Microsoft compatible mouse driver to be installed. This
   package is best used in conjunction with the mouse programming manual.

Converting Mouse Coordinates to Display Coordinates


   The mouse coordinate system is left-handed for both text and graphics
   modes, with 0,0 being the upper left corner.

   Note that The Display package uses a left-handed coordinate system, but
   Flash Graphics uses a right-handed system where 0,0 is the lower left
   hand corner. Also note that the mouse coordinates in text mode are not in
   character coordinates.

   To convert from Flash Graphics coordinates to mouse coordinates use:

       mouse_x = fg_x;
       mouse_y = fg_displaybox[FG_Y2] - fg_y;

   To convert from display (character) coordinates to mouse coordinates use:

       if (40 column mode)
           mouse_x = display_x * 16;
       else
           mouse_x = display_x * 8;
       mouse_y = display_y * 8;


   The mouse driver sometimes gets the number of screen rows wrong in text
   mode, so the recommended method of initializing the mouse if the display
   package is also used is:

       disp_open();            /* initialize display */
       msm_init();             /* initialize mouse   */

       /* Mouse driver sometimes gets the number of screen
       rows wrong, so here we force it to whatever disp_open()
       discovered.*/

       msm_setareay(0,(disp_numrows - 1) * 8);

       msm_showcursor();           /* mouse cursor on*/

Using the Mouse Package

   The Mouse Package contains a large number of functions which fall
   naturally into categories. By discussing these categories in turn, a

   reasonable knowledge can be obtained of how these functions fit together
   in developing a mouse driven application.

Initializing the Mouse Driver

   There are two complementary functions provided within the Mouse package
   which are concerned with initializing and closing down the mouse driver.
   These are msm_init and msm_term.

   The function msm_init attempts to initialize the mouse driver. This
   function is required to be executed before any of the other mouse
   functions can be used. If there is no mouse driver installed it will
   return 0, otherwise it returns 1. A number of operations are carried out
   by this function, including setting of the default cursor shape. For more
   details look at the individual listing for msm_init.

   The function msm_term closes down the mouse driver and cleans up the
   display by removing the mouse cursor. Once msm_term has been called a
   further msm_init is required to restart the mouse package.


Mouse Cursor Positioning

   Three functions are involved with mouse positioning. The functions
   msm_setareax and msm_setareay are used to restrict mouse cursor movements
   to a particular rectangle, normally the screen coordinates. msm_init
   normally sets these to reflect the screen size, but as mentioned above,
   it sometimes gets them wrong due to a fault with the mouse driver.

   The function msm_setcurpos is used to position the mouse cursor at an
   arbitrary position on the screen.

Mouse Cursor Shape and Size

   Two functions are concerned with the shape and size of the mouse cursor.
   They are msm_setgraphcur, which sets the graphics cursor shape, and
   msm_settextcur, which does the same for the text cursor. The graphics
   cursor is the most flexible, since it is bit mapped on a 16 by 16 matrix.
   The text cursor can only be used as a valid character and attribute
   combination. A zero character with a blinking attribute mask allows a
   flashing see-through block cursor to be used.


Controlling the Display of the Mouse Cursor

   The three functions msm_hidecursor, msm_showcursor and msm_condoff
   provide control over whether the mouse cursor is shown on the screen or
   not. The mouse cursor must be hidden when writing to or updating the
   screen, otherwise there is a risk of screen corruption.

   The first two functions turn the mouse cursor off and on unconditionally.
   These functions are normally used to bracket an instruction which updates
   the display. Because there is a time penalty involved, it is best to
   enclose a series of updates if possible, rather than each individual
   update. The function msm_condoff will turn off the cursor only when it is
   in a specified area of the screen. This is useful for an area of the
   screen that is being continually updated, although any call to
   msm_showcursor will disable this automatic hiding facility.

Adjusting Mouse Response

   Two functions are used to modifying the response of the mouse to

   movement. The function msm_setratio sets the sensitivity of the mouse.
   Higher values mean that the mouse must be moved further to get the same
   relative cursor movement. Generally, the higher the screen resolution,
   the lower this ratio needs to be.

   The second function is msm_setthreshold. This is used to set the
   threshold speed for mouse movement. This threshold is where the
   mouse/cursor ratio is temporarily halved so that the mouse appears to
   move twice as quickly. This is used to provide fast movement of the mouse
   cursor when a user wants to go to a menu for example, without sacrificing
   precision when working on detail.

Testing for Mouse Events and Movement

   Five functions are concerned with detecting mouse events, such as button
   presses and mouse movement. One, msm_readcounters, is used to detect
   motion, It reports how far the mouse has moved since the last call, and
   in what direction. The movement is in mouse units (mickeys) and must be
   converted into pixels with the aid of the mickey/pixel ratio as used by
   msm_setratio.


   The status function, msm_getstatus, returns the current cursor position
   in pixels, and the current state of the mouse buttons, i.e. whether they
   were up or down at the time the call was made.

   There are two complementary event counting functions, msm_getpress and
   msm_getrelease. These functions count the number of times the specified
   button has been pressed (for msm_getpress) or released (for
   msm_getrelease) since the last time the function was called. They also
   indicate the cursor position when the last event was recorded. They are
   often used in the situation where it is necessary to determine whether
   the user is clicking a mouse button or attempting a drag. For example a
   routine would be written using these functions to test a button. When a
   button press is detected, the function waits a fixed interval for a
   release. If it does not get one it assumes a drag is in progress.

   The final function concerned with mouse events is msm_signal. This is
   very different to the other functions discussed, in that it is not an
   event monitoring function, but is used to install a user routine as a
   handler which is then called whenever a mouse event occurs. This facility

   allows mouse events to be handled asynchronously. When a mouse event
   occurs, information is passed to the user s function detailing the event
   that caused the signal, the current button status and the position of the
   mouse cursor.

Light Pen Emulation

   The final two functions msm_lightpenon and msm_lightpenoff, are involved
   in making the mouse cursor emulate a light pen. When light pen emulation
   is on (the default), movement of the mouse, and left and right buttons
   being simultaneously pressed are reflected in the appropriate settings in
   the light pen registers of the IBM PC BIOS.


Example 

   #include <stdio.h>
   #include <msmouse.h>
   #include <stdlib.h>


   int main()
   {
       if (msm_init() == -1)
           {
               printf("Mouse initialization succeeded\n");
               msm_showcursor();
               while (1)
                   {
                       int status;
                       unsigned x,y;
                       status = msm_getstatus(&x, &y);
                       if (status & LEFT_BUTTON)
                           {
                               msm_hidecursor();
                               printf("x = %u, y = %u\n", x,y);
                               msm_showcursor();
                           }
                       if (status & RIGHT_BUTTON)
                           break;
                   }

               msm_term();
           } else {
               printf("Mouse initialization failed\n");
               return EXIT_FAILURE;
           }
       return EXIT_SUCCESS;
   }