iOS Reference Library Apple Developer
Search

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



curs_mouse(3X)                                                  curs_mouse(3X)



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(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 which may be defined:


       Name                     Description
       ---------------------------------------------------------------------BUTTON1_PRESSED --------------------------------------------------------------------BUTTON1_PRESSED
       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
       ---------------------------------------------------------------------BUTTON2_PRESSED --------------------------------------------------------------------BUTTON2_PRESSED
       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 --------------------------------------------------------------------BUTTON3_PRESSED
       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 --------------------------------------------------------------------BUTTON4_PRESSED
       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 --------------------------------------------------------------------BUTTON5_PRESSED
       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 --------------------------------------------------------------------BUTTON_SHIFT
       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 --------------------------------------------------------------------Once

       Once  a class of mouse events have been made visible in a window, call-ing calling
       ing the wgetch function on that window may return KEY_MOUSE as an indi-cator indicator
       cator  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 other-wise. otherwise.
       wise.  When getmouse returns OK, the data deposited as y and x  in  the
       event  structure coordinates will be screen-relative character-cell co-ordinates. coordinates.
       ordinates.  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 ver-sa. versa.
       sa.  Please remember, that stdscr-relative coordinates are  not  always
       identical  to  screen-relative  coordinates due to the mechanism to re-serve reserve
       serve 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 coordi-nates coordinates
       nates and returned through the pointers.  If the  conversion  was  suc-cessful, successful,
       cessful,  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 coordi-nates coordinates
       nates are only replaced by the converted coordinates if the transforma-tion transformation
       tion 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 resolu-tion. resolution.
       tion.  This function returns the previous interval value.  Use mousein-terval(-1) mouseinterval(-1)
       terval(-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 inputloop
       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  initialized,  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).

       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.  If the  inter-face interface
       face  is changed, the value of NCURSES_MOUSE_VERSION will be increment-ed. incremented.
       ed.  These values for NCURSES_MOUSE_VERSION may be specified when  con-figuring configuring
       figuring ncurses:

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

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

       The order of the MEVENT structure members is not guaranteed.  Addition-al Additional
       al 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 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(3X) (and the wmousemask function 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  in-tended intended
       tended  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  as-sumes assumes
       sumes  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).



                                                                curs_mouse(3X)
Did this document help you? Yes It's good, but... Not helpful...