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

   msm Mouse_Package
   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  complimentary 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 a 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, uninstalling  the
   mouse  interrupt routines and cleaning 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
   There  are three functions which 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
   There are two functions 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
   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 occurring.

   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
   There  are two functions concerned with 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  of  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 manoeuvring of the
   mouse  cursor when a user wants to go to a menu for  example,  without
   sacrificing precision when working close in.

   Testing for Mouse Events and Movement
   There  are  total  of five functions concerned  with  detecting  mouse
   events,   such   a   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 complimentary 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 function  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 an
   interrupt  server which is then called whenever a mouse event  occurs.
   This facility allows mouse events to be handled asynchronously. When a
   mouse  interrupt occurs, information is passed to the user's  function
   detailing  the  event that caused the interrupt,  the  current  button
   status  and the position of the mouse cursor. Since interrupt  service
   routines have a number of restrictions as to what they may or may  not
   do,  this technique should not be attempted without first being  aware
   of these restrictions and their implications. For more information  on
   interrupt  service  routines  refer to the  reference  entry  for  The
   Interrupt package.

   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.

   More Information
   For more information refer to the Microsoft Mouse Programmer's Guide.

   Example
   #include <stdio.h>
   #include <msmouse.h>
   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");
   }