Mouse - msmouse.h

This chapter describes:

How to convert mouse coordinates to display coordinates
How to use msm_functions to:
- initialize the mouse driver
- position the mouse cursor
- set the cursor's shape and size
- adjust mouse response
- test for events and movement
- use the mouse to emulate a light pen
How a sample program uses the msm_functions
Mouse function reference

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:

msm_init
msm_term

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:

msm_setareax
msm_setareay
msm_setcurpos

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:

msm_setgraphcur
msm_settextcur

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:

msm_hidecursor
msm_showcursor
msm_condoff

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:

msm_setratio
msm_setthresholdf

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:

msm_readcounters
msm_getstatus
msm_getpress
msm_getrelease
msm_signal

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:

msm_lightpenon
msm_lightpenoff

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

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

Standard C

Standard C++

Win32

DOS, DOS32, Win16

Other C

Other C++

Mouse - msmouse.h

Converting Mouse Coordinates to Display

Using msm_Functions

Initializing and Terminating the Mouse Driver

Positioning the Mouse Cursor

Setting Mouse Cursor Shape and Size

Controlling the Display of the Mouse Cursor

Adjusting Mouse Response

Testing for Mouse Events and Movement

Emulating a Light Pen

Sample Program

msm_condoff

msm_getpress

msm_getrelease

msm_getstatus

msm_hidecursor

msm_init

msm_lightpen

msm_readcounters

msm_setarea

msm_setcurpos

msm_setgraphcur

msm_setratio

msm_settextcur

msm_setthreshhold

msm_showcursor

msm_signal

msm_term