[mercury-users] SEC: UNCLASSIFIED:-

[Fergus Henderson]

On 31-Oct-2002, Ian.Sykes at defence.gov.au <Ian.Sykes at defence.gov.au> wrote:
> Does anyone know of any mouse handling routines?

Here's the man page for the ncurses mouse handling routines.  You'll need
to use the C interface.  I have not tested them, but I believe these
should work in conjunction with the Mercury curses interfaces in the
extras distribution, and should work fine on both Windows (with Cygwin)
and Unix.

----------

NAME

   getmouse, ungetmouse, mousemask, wenclose, mouse_trafo, wmouse_trafo,
   mouseinterval - mouse interface through curses

SYNOPSIS

#include <curses.h>

typedef unsigned long mmask_t;

typedef struct
{
    short id;         /* ID to distinguish multiple devices */
    int x, y, z;      /* event coordinates */
    mmask_t bstate;   /* button state bits */
}
MEVENT;

   int getmouse(MEVENT *event);
   int ungetmouse(MEVENT *event);
   mmask_t mousemask(mmask_t newmask, mmask_t *oldmask);
   bool wenclose(WINDOW *win, int y, int x);
   bool mouse_trafo(int* pY, int* pX, bool to_screen);
   bool wmouse_trafo(const WINDOW* win, int* pY, int* pX,
   bool to_screen);
   int mouseinterval(int erval);

DESCRIPTION

   These functions provide an interface to mouse events from ncurses(3X).
   Mouse events are represented by KEY_MOUSE pseudo-key values in the
   wgetch input stream.

   To make mouse events visible, use the mousemask function. This will
   set the mouse events to be reported. By default, no mouse events are
   reported. The function will return a mask to indicate which of the
   specified mouse events can be reported; on complete failure it returns
   0. If oldmask is non-NULL, this function fills the indicated location
   with the previous value of the given window's mouse event mask.

   As a side effect, setting a zero mousemask may turn off the mouse
   pointer; setting a nonzero mask may turn it on. Whether this happens
   is device-dependent.

   Here are the mouse event type masks:

                           [grohtml-19024-1.png]

   Once a class of mouse events have been made visible in a window,
   calling the wgetch function on that window may return KEY_MOUSE as an
   indicator that a mouse event has been queued. To read the event data
   and pop the event off the queue, call getmouse. This function will
   return OK if a mouse event is actually visible in the given window,
   ERR otherwise. When getmouse returns OK, the data deposited as y and x
   in the event structure coordinates will be screen-relative
   character-cell coordinates. The returned state mask will have exactly
   one bit set to indicate the event type.

   The ungetmouse function behaves analogously to ungetch. It pushes a
   KEY_MOUSE event onto the input queue, and associates with that event
   the given state data and screen-relative character-cell coordinates.

   The wenclose function tests whether a given pair of screen-relative
   character-cell coordinates is enclosed by a given window, returning
   TRUE if it is and FALSE otherwise. It is useful for determining what
   subset of the screen windows enclose the location of a mouse event.

   The wmouse_trafo function transforms a given pair of coordinates from
   stdscr-relative coordinates to screen-relative coordinates or vice
   versa. Please remember, that stdscr-relative coordinates are not
   always identical to screen-relative coordinates due to the mechanism
   to reserve lines on top or bottom of the screen for other purposes
   (ripoff() call, see also slk_... functions). If the parameter
   to_screen is TRUE, the pointers pY, pX must reference the coordinates
   of a location inside the window win. They are converted to
   screen-relative coordinates and returned through the pointers. If the
   conversion was successful, the function returns TRUE. If one of the
   parameters was NULL or the location is not inside the window, FALSE is
   returned. If to_screen is FALSE, the pointers pY, pX must reference
   screen-relative coordinates. They are converted to stdscr-relative
   coordinates if the window win encloses this point. In this case the
   function returns TRUE. If one of the parameters is NULL or the point
   is not inside the window, FALSE is returned. Please notice, that the
   referenced coordinates are only replaced by the converted coordinates
   if the transformation was successful.

   The mouseinterval function sets the maximum time (in thousands of a
   second) that can elapse between press and release events for them to
   be recognized as a click. Use mouseinterval(-1) to disable click
   resolution. This function returns the previous interval value. The
   default is one sixth of a second.

   Note that mouse events will be ignored when input is in cooked mode,
   and will cause an error beep when cooked mode is being simulated in a
   window by a function such as getstr that expects a linefeed for
   input-loop termination.

RETURN VALUE

   getmouse, ungetmouse and mouseinterval return the integer ERR upon
   failure or OK upon successful completion. mousemask returns the mask
   of reportable events. wenclose and wmouse_trafo are boolean functions
   returning TRUE or FALSE depending on their test result.

PORTABILITY

   These calls were designed for ncurses(3X), and are not found in SVr4
   curses, 4.4BSD curses, or any other previous version of curses.

   The feature macro NCURSES_MOUSE_VERSION is provided so the
   preprocessor can be used to test whether these features are present
   (its value is 1). If the interface is changed, the value of
   NCURSES_MOUSE_VERSION will be incremented.

   The order of the MEVENT structure members is not guaranteed.
   Additional fields may be added to the structure in the future.

   Under ncurses(3X), these calls are implemented using either xterm's
   built-in mouse-tracking API or Alessandro Rubini's gpm server. If you
   are using something other than xterm and there is no gpm daemon
   running on your machine, mouse events will not be visible to
   ncurses(3X) (and the wmousemask function will always return 0).

   The z member in the event structure is not presently used. It is
   intended for use with touch screens (which may be pressure-sensitive)
   or with 3D-mice/trackballs/power gloves.

BUGS

   Mouse events under xterm will not in fact be ignored during cooked
   mode, if they have been enabled by wmousemask. Instead, the xterm
   mouse report sequence will appear in the string read.

   Mouse events under xterm will not be detected correctly in a window
   with its keypad bit off, since they are interpreted as a variety of
   function key. Your terminfo description must have kmous set to "E[M"
   (the beginning of the response from xterm for mouse clicks).

   Because there are no standard terminal responses that would serve to
   identify terminals which support the xterm mouse protocol, ncurses
   assumes that if your $TERM environment variable contains "xterm", or
   kmous is defined in the terminal description, then the terminal may
   send mouse events.

SEE ALSO

   curses(3X).
     _________________________________________________________________

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-users mailing list
post:  mercury-users at cs.mu.oz.au
administrative address: owner-mercury-users at cs.mu.oz.au
unsubscribe: Address: mercury-users-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-users-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------