MirOS Manual: curs_mouse(3), getmouse(3), mouseinterval(3), mousemask(3), mouse_trafo(3), ungetmouse(3), wenclose(3), wmouse_trafo(3)


curs_mouse(3)       UNIX Programmer's Manual        curs_mouse(3)

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(const 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(3).   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. Wheth-
     er this happens is device-dependent.

     Here are the mouse event type masks which may be defined:

     Name                     Description
     ____________________________________________________________________
     BUTTON1_PRESSED          mouse button 1 down
     BUTTON1_RELEASED         mouse button 1 up
     BUTTON1_CLICKED          mouse button 1 clicked
     BUTTON1_DOUBLE_CLICKED   mouse button 1 double clicked
     BUTTON1_TRIPLE_CLICKED   mouse button 1 triple clicked
     ____________________________________________________________________

MirOS BSD #10-current  Printed 03.04.2017                       1

curs_mouse(3)       UNIX Programmer's Manual        curs_mouse(3)

     BUTTON2_PRESSED          mouse button 2 down
     BUTTON2_RELEASED         mouse button 2 up
     BUTTON2_CLICKED          mouse button 2 clicked
     BUTTON2_DOUBLE_CLICKED   mouse button 2 double clicked
     BUTTON2_TRIPLE_CLICKED   mouse button 2 triple clicked
     ____________________________________________________________________
     BUTTON3_PRESSED          mouse button 3 down
     BUTTON3_RELEASED         mouse button 3 up
     BUTTON3_CLICKED          mouse button 3 clicked
     BUTTON3_DOUBLE_CLICKED   mouse button 3 double clicked
     BUTTON3_TRIPLE_CLICKED   mouse button 3 triple clicked
     ____________________________________________________________________
     BUTTON4_PRESSED          mouse button 4 down
     BUTTON4_RELEASED         mouse button 4 up
     BUTTON4_CLICKED          mouse button 4 clicked
     BUTTON4_DOUBLE_CLICKED   mouse button 4 double clicked
     BUTTON4_TRIPLE_CLICKED   mouse button 4 triple clicked
     ____________________________________________________________________
     BUTTON5_PRESSED          mouse button 5 down
     BUTTON5_RELEASED         mouse button 5 up
     BUTTON5_CLICKED          mouse button 5 clicked
     BUTTON5_DOUBLE_CLICKED   mouse button 5 double clicked
     BUTTON5_TRIPLE_CLICKED   mouse button 5 triple clicked
     ____________________________________________________________________
     BUTTON_SHIFT             shift was down during button state change
     BUTTON_CTRL              control was down during button state change
     BUTTON_ALT               alt was down during button state change
     ALL_MOUSE_EVENTS         report all button state changes
     REPORT_MOUSE_POSITION    report mouse movement
     ____________________________________________________________________

     Once a class of mouse events have been  made  visible  in  a
     window,  calling  the wgetch function on that window may re-
     turn 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 associ-
     ates 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 en-
     close the location of a mouse event.

MirOS BSD #10-current  Printed 03.04.2017                       2

curs_mouse(3)       UNIX Programmer's Manual        curs_mouse(3)

     The wmouse_trafo function transforms a given pair of coordi-
     nates  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 param-
     eters  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(0)  to disable click resolution. This function
     returns the previous interval value.  Use  mouseinterval(-1)
     to  obtain  the interval without altering it. 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 and ungetmouse return the integer ERR upon  failure
     or OK upon successful completion.

          getmouse
               returns an error. If no mouse driver was  initial-
               ized, or if the mask parameter is zero,

          ungetmouse
               returns an error if the FIFO is full.

     mousemask returns the mask of reportable events.

     mouseinterval returns the previous  interval  value,  unless
     the  terminal  was not initialized. In that case, it returns
     the maximum interval value (166).

MirOS BSD #10-current  Printed 03.04.2017                       3

curs_mouse(3)       UNIX Programmer's Manual        curs_mouse(3)

     wenclose and wmouse_trafo are  boolean  functions  returning
     TRUE or FALSE depending on their test result.

PORTABILITY

     These calls were designed for ncurses(3), 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.  If  the  interface  is  changed,  the   value   of
     NCURSES_MOUSE_VERSION  will be incremented. These values for
     NCURSES_MOUSE_VERSION  may  be  specified  when  configuring
     ncurses:

          1  has definitions for reserved events. The  mask  uses
             28 bits.

          2  adds definitions for button 5, removes  the  defini-
             tions for reserved events. The mask uses 29 bits.

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

     Under ncurses(3), these calls are implemented  using  either
     xterm's  built-in  mouse-tracking  API  or platform-specific
     drivers including
          Alessandro Rubini's gpm server.
          FreeBSD sysmouse
          OS/2 EMX
     If you are using an unsupported configuration, mouse  events
     will  not be visible to ncurses(3) (and the wmousemask func-
     tion will always return 0).

     If the terminfo entry contains a XM string, this is used  in
     the  xterm  mouse  driver to control the way the terminal is
     initialized for mouse operation. The default, if XM  is  not
     found, corresponds to private mode 1000 of xterm:
          \E[?1000%?%p1%{1}%=%th%el%;
     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. In-
     stead, 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

MirOS BSD #10-current  Printed 03.04.2017                       4

curs_mouse(3)       UNIX Programmer's Manual        curs_mouse(3)

     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 termi-
     nal description, then the terminal may send mouse events.

SEE ALSO

     curses(3).

MirOS BSD #10-current  Printed 03.04.2017                       5

Generated on 2017-04-03 16:26:17 by $MirOS: src/scripts/roff2htm,v 1.88 2017/01/29 00:51:06 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002–2017 The MirOS Project, Germany.
This product includes material provided by mirabilos.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.