digitalmars.com                      
Last update Thu Jun 16 18:57:24 2011

Mouse - msmouse.h

This chapter describes: Digital Mars msm_functions provide a C interface to the Microsoft mouse and require that a Microsoft compatible mouse driver be installed. Keep your mouse programming manual handy; these functions work with the information in that manual.

Converting Mouse Coordinates to Display

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

The Display functions use a left-handed coordinate system. The mouse coordinates in text mode are not in character coordinates.

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 msm_Functions

The following sections describe how to use the msm_functions. For more information on specific functions, see Chapter 3.

Initializing and Terminating the Mouse Driver

Functions that initialize and terminate the mouse driver are: The msm_init function must be called before any of the other mouse functions. It initializes the mouse driver and performs a number of operations, including setting the default cursor shape.

The msm_term function terminates the mouse driver and cleans up the display by removing the mouse cursor. Once msm_term has been called, another msm_init is required to restart the driver.

Positioning the Mouse Cursor

Functions that position the mouse cursor are:

Use msm_setareax and msm_setareay to restrict mouse cursor movements to a particular rectangle, normally the screen coordinates. msm_init sets these to reflect the screen size, unless a fault exists in the mouse driver.

Use msm_setcurpos to position the mouse cursor at an arbitrary position on the screen.

Setting Mouse Cursor Shape and Size

Functions that set the shape and size of the mouse cursor are:

Use msm_setgraphcur to set the graphics cursor shape, and msm_settextcur to set the text cursor shape. The graphics cursor is the most flexible; it is bit mapped on a 16x16 matrix. The text cursor can be used only 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

Functions that control display of the mouse cursor are:

Use msm_hidecursor and msm_showcursor to turn the mouse cursor off and on unconditionally. They are useful to bracket an instruction that updates the display. Because a time penalty is involved, enclose a series of updates if possible, rather than each individual update.

The msm_condoff function turns off the cursor only when it is in a specified area of the screen and is useful for an area of the screen that is being continually updated. However, any call to msm_showcursor disables this automatic hiding facility.

The mouse cursor must be hidden when writing to or updating the screen. Otherwise, you risk screen corruption.

Adjusting Mouse Response

Functions that modify mouse response to movement are:

Use msm_setratio to set the sensitivity of the mouse. Higher values mean 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.

Use msm_setthreshold 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 without sacrificing precision when working on detail. For example, this is useful when a user wants to go to a menu.

Testing for Mouse Events and Movement

Functions that test for mouse events and movement are: Use msm_readcounters 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.

Use msm_getstatus to return the current cursor position in pixels, and the current state of the mouse buttons, for example, whether they were up or down at the time the call was made.

Use the msm_getpress and msm_getrelease functions for event counts. 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. These functions are useful when you need to determine whether the user is clicking a mouse button or attempting a drag. For example, you could write a routine that uses 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.

Use the msm_signal function 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.

Emulating a Light Pen

Functions that cause the mouse to emulate a light pen are:

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.

Sample Program

The following example uses msm_functions.
#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;
}

msm_condoff

Header
msmouse.h
Prototype
void msm_condoff(unsigned upperx, unsigned uppery, unsigned lowerx, unsigned lowery);
Description
The msm_condoff function defines an area in which the mouse cursor is hidden. The parameters define a rectangular region on the screen. When the mouse is in that region, the mouse cursor is hidden. This is useful if a portion of the screen is to be updated. A call to msm_showcursor displays the cursor again.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init msm_showcursor msm_term

msm_getpress

Header
msmouse.h
Prototype
int msm_getpress(unsigned *count, unsigned *curposx, unsigned *curposy);
Description
The msm_getpress function gets mouse button press information. The count parameter points to an integer designating which button to get information about (0 = left button, 1 = right button, 2 = middle button). The function places the number of times that the button has been pressed since the last call to msm_getpress into count and the mouse position at the last press into curposx and curposy. Values can be in the range 0 to 32767.

Before using msm_getpress call msm_init.

Return Value
Returns the state of all of the buttons as a bit pattern.
Bit Button
0 left button (1 == down, 0 == up)
1 right button
2 middle button
All other bits should be ignored.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init msm_getrelease msm_getstatus msm_term

msm_getrelease

Header
msmouse.h
Prototype
int msm_getrelease(unsigned *count, unsigned *curposx, unsigned *curposy);
Description
The msm_getrelease function gets mouse button release information. The count argument points to an integer designating the button about whichyou require information (0 = left button, 1 = right button, 2 = middle button). The function places into count the number of times the button has been released since the last call to msm_getrelease, and places into curposx and curposy the mouse position at the time of release. Values range from 0 to 32767.
Return Value
Returns the state of all of the buttons as a bit pattern.
Bit Button
0 left button (1 == down, 0 == up)
1 right button
2 middle button
All other bits should be ignored.

Before using msm_getrelease initialize the mouse driver by calling msm_init.

Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_getstatus

Header
msmouse.h
Prototype
int msm_getstatus(unsigned *curposx, unsigned *curposy);
Description
The msm_getstatus function obtains the status of the mouse and places the current cursor position in the variables pointed to by curposx and curposy.

Before using msm_getstatus initialize the mouse driver by calling msm_init.

Return Value
Returns the state of all of the buttons as a bit pattern.
Bit Button
0 left button (1 == down, 0 == up)
1 right button
2 middle button
Ignore the other bits.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_hidecursor

Header
msmouse.h
Prototype
void msm_hidecursor(void);
Description
The msm_hidecursor function hides the cursor and decrements the cursor flag. Before using msm_hidecursor initialize the mouse driver by calling msm_init.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init msm_showcursor

msm_init

Header
msmouse.h
Prototype
int msm_init(void);
Description
The msm_init function initializes the mouse driver. You must call msm_init before using any other mouse functions. To terminate the mouse driver, call msm_term.

In graphics mode, msm_init sets the cursor to be an arrow; in text mode, msm_init sets the cursor to be inverse video. In addition, msm_init sets the following cursor attributes: the cursor is positioned in the middle of the screen. the cursor display is turned off and the min/max cursor position is set to the full screen dimensions. Finally, the mickey/pixel ratio is set to 1/1 in the x direction and 2/1 in the y direction.

Return Value
Returns -1 if successful. Otherwise, returns 0 if initialization failed. Failure might indicate no mouse driver is present.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_term
Example
/* Example for msm_init */

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

void main()
{
 int status, oldstatus = -1;
 unsigned x, y;

 if (! msm_init ())
 {
  fprintf(stderr,"Unable to initialize
           mouse system\n");
  exit(EXIT_FAILURE);
 }

 printf("Mouse initialization succeeded\n");

 msm_showcursor();

 while (1)
 {
   status = msm_getstatus(&x, &y);
   if ((status & LEFT_BUTTON) &&
       (status != oldstatus))
   {
      msm_hidecursor();
      printf("x = %u, y = %u\n", x, y);
      msm_showcursor();
   }

   if (status & RIGHT_BUTTON)
      break;

   oldstatus = status;
 }

 msm_term ();
}

msm_lightpen

Header
msmouse.h
Prototype
void msm_lightpenon(void);
void msm_lightpenoff(void);
Description
These functions turn on or off light pen emulation mode. The mouse emulates a light pen; the "pen" is off the screen when the left and right buttons are up, and the "pen" is down when both buttons are down. Before using these functions, initialize the mouse driver by calling msm_init.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_readcounters

Header
msmouse.h
Prototype
void msm_readcounters(int *countx, int *county);
Description
The msm_readcounters function reads the mouse motion counters in mickeys. A mickey is 1/ 200 of an inch. Before using msm_readcounters, call msm_init to initialize the mouse driver.
Return Value
On returning the variables pointed to by countx and county contain the mickey count since the last call; values can range from -32768 to 32767.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_setarea

Header
msmouse.h
Prototype
void msm_setareax(unsigned minx, unsigned maxx);
void msm_setareay(unsigned miny, unsigned maxy);
Description
The msm_setareax function sets a minimum and maximum horizontal position for the cursor. If maxx < minx, the values are exchanged. The mouse horizontal motion is restricted to within these values.

The msm_setareay function sets minimum and maximum vertical position for the cursor. If maxy < miny, the values are exchanged. The mouse vertical motion is restricted to within these values.

Before using these functions initialize the mouse driver by calling msm_init.

Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_setcurpos

Header
msmouse.h
Prototype
void msm_setcurpos(unsigned curposx, unsigned curposy);
Description
The msm_setcurpos function sets the cursor position. The upper left corner of the screen is 0, 0. The values for curposx and curposy must be within the screen.

Before using msm_setcurpos initialize the mouse driver by calling msm_init.

Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_setgraphcur

Header
msmouse.h
Prototype
void msm_setgraphcur(int hotx, int hoty, int *pmasks);
Description
The msm_setgraphcur function sets the graphics cursor block. On entry to the function hotx and hoty should point to the location of the 'hot spot' of cursor. Values must be in the range -16 through 16. Location 0, 0 is the upper left corner of the cursor with positive values extending right and down. The variable pmasks should point to an array of 32 words which contain bit masks defining the cursor. The first 16 words define the mask - the bits of the background which 'shine' through the cursor. A 1 means shine through, a 0 means not. The second 16 words define the bitmap of the cursor, 1 being on and 0 being off. The cursor is 16* 16, the first word forms the top row, bit 15 forms the left-most column.

Initialize the mouse driver by calling msm_init.

Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_setratio

Header
msmouse.h
Prototype
void msm_setratio(unsigned ratiox, unsigned ratioy);
Description
The msm_setratio function sets the mickey/ pixel ratio (the sensitivity of the mouse). Higher values mean less cursor movement for corresponding mouse movement. The default values are 8, 16. Values for ratiox and ratioy must be in the range 1 to 32767. Before using msm_setratio call msm_init.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init

msm_settextcur

Header
msmouse.h
Prototype
void msm_settextcur(int select, int scanstart, int scanstop);
Description
The msm_settextcur function sets the text cursor. On entry to the function, select is used to indicate whether or not to use a hardware cursor. If select is 1, then the hardware text cursor is used. If select is 0, then an attribute cursor is used. The parameters scanstart and scanstop have different uses depending on the value in select. If select is 1, then these values form the starting and ending scan lines of the hardware text cursor. If select is 0, then these values form the screen mask and cursor mask, respectively, for the attribute cursor.

Before using msm_settextcur initialize the mouse driver by calling msm_init.

Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init

msm_setthreshhold

Header
msmouse.h
Prototype
void msm_setthreshhold(unsigned speed);
Description
The msm_setthreshhold function sets the double speed threshold, the speed at which the mickey/ pixel ratio is temporarily halved, so that the mouse apparently moves faster. Speed is in mickeys/ second. The default speed is 64.

Before using msm_setthreshhold initialize the mouse driver by calling msm_init.

Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init

msm_showcursor

Header
msmouse.h
Prototype
void msm_showcursor(void);
Description
The msm_showcursor function shows cursor. That is, this function increments the cursor flag. If the cursor flag is 0, then the cursor is displayed. msm_showcursor must be called after msm_init in order for the cursor to appear. msm_showcursor and msm_hidecursor can be nested. If msm_hidecursor is called n times, msm_showcursor must be called n times in order to show the cursor. Generally, remove the cursor before any screen I/O is performed, and then restore the cursor.

Before using msm_showcursor initialize the mouse driver by calling msm_init.

Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init

msm_signal

Header
msmouse.h
Prototype
void msm_signal(unsigned mask, void(* func)(unsigned mask, unsigned state, unsigned curposx, unsigned curposy), void *stack);
Description
The msm_signal function sets up a user-defined subroutine input mask. Use msm_signal to set a function to be called whenever input is available from the mouse. Before using msm_signal call msm_init. On input, mask defines when to call the user routine (1 is yes):

0 Mouse moved
1 Left button is pressed
2 Left button is released
3 Right button is pressed
4 Right button is released
5 Middle button is pressed
6 Middle button is released
Other bits are not used. The parameter func is a pointer to the application-defined interrupt service routine to call whenever a mouse button is pressed or released, or the mouse moves, according to the bits in mask. The parameter stack contains the value to set the stack pointer to when func is called. The stack value should point just past the end of an area that is at least 256 bytes long. When func is called, it is passed the following information:

mask Event that occurred is indicated with the bit set as defined above.
state If button event, this is the button number of the button that changed (0 = left, 1 = right, 2 = middle).
curposx, curposy Current mouse position.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init

msm_term

Header
msmouse.h
Prototype
void msm_term(void);
Description
The msm_term function terminates the mouse driver. You should call this function before the program exits if you used msm_init to initialize the mouse driver.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
msm_init
Example
See msm_init
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums