doc/html/man/curs_mouse.3x.html

   1 <HTML>
   2 <BODY>
   3 <PRE>
   4 <!-- Manpage converted by man2html 3.0.1 -->
   5
   6 </PRE>
   7 <H2>NAME</H2><PRE>
   8        <B>getmouse</B>,  <B>ungetmouse</B>,  <B>mousemask</B>,  <B>wenclose</B>, <B>mouse_trafo</B>,
   9        <B>wmouse_trafo</B>,  <B>mouseinterval</B>  -  mouse  interface  through
  10        curses
  11
  12
  13 </PRE>
  14 <H2>SYNOPSIS</H2><PRE>
  15        <B>#include</B> <B>&lt;curses.h&gt;</B>
  16
  17        <B>typedef</B> <B>unsigned</B> <B>long</B> <B>mmask_t;</B>
  18
  19        <B>typedef</B> <B>struct</B>
  20        <B>{</B>
  21            <B>short</B> <B>id;</B>         <I>/*</I> <I>ID</I> <I>to</I> <I>distinguish</I> <I>multiple</I> <I>devices</I> <I>*/</I>
  22            <B>int</B> <B>x,</B> <B>y,</B> <B>z;</B>      <I>/*</I> <I>event</I> <I>coordinates</I> <I>*/</I>
  23            <B>mmask_t</B> <B>bstate;</B>   <I>/*</I> <I>button</I> <I>state</I> <I>bits</I> <I>*/</I>
  24        <B>}</B>
  25        <B>MEVENT;</B>
  26        <B>int</B> <B>getmouse(MEVENT</B> <B>*event);</B>
  27        <B>int</B> <B>ungetmouse(MEVENT</B> <B>*event);</B>
  28        <B>mmask_t</B> <B>mousemask(mmask_t</B> <B>newmask,</B> <B>mmask_t</B> <B>*oldmask);</B>
  29        <B>bool</B> <B>wenclose(WINDOW</B> <B>*win,</B> <B>int</B> <B>y,</B> <B>int</B> <B>x);</B>
  30        <B>bool</B> <B>mouse_trafo(int*</B> <B>pY,</B> <B>int*</B> <B>pX,</B> <B>bool</B> <B>to_screen);</B>
  31        <B>bool</B> <B>wmouse_trafo(const</B> <B>WINDOW*</B> <B>win,</B> <B>int*</B> <B>pY,</B> <B>int*</B> <B>pX,</B>
  32             <B>bool</B> <B>to_screen);</B>
  33        <B>int</B> <B>mouseinterval(int</B> <B>erval);</B>
  34
  35
  36 </PRE>
  37 <H2>DESCRIPTION</H2><PRE>
  38        These  functions provide an interface to mouse events from
  39        <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>.  Mouse events are  represented  by  <B>KEY_MOUSE</B>
  40        pseudo-key values in the <B>wgetch</B> input stream.
  41
  42        To  make mouse events visible, use the <B>mousemask</B> function.
  43        This will  set  the  mouse  events  to  be  reported.   By
  44        default,  no mouse events are reported.  The function will
  45        return a mask to indicate which  of  the  specified  mouse
  46        events  can be reported; on complete failure it returns 0.
  47        If oldmask is non-NULL, this function fills the  indicated
  48        location  with  the  previous  value of the given window's
  49        mouse event mask.
  50
  51        As a side effect, setting a zero mousemask  may  turn  off
  52        the  mouse pointer; setting a nonzero mask may turn it on.
  53        Whether this happens is device-dependent.
  54
  55        Here are the mouse event type masks:
  56
  57        <I>Name</I>                     <I>Description</I>
  58        ---------------------------------------------------------------------
  59        BUTTON1_PRESSED          mouse button 1 down
  60        BUTTON1_RELEASED         mouse button 1 up
  61        BUTTON1_CLICKED          mouse button 1 clicked
  62        BUTTON1_DOUBLE_CLICKED   mouse button 1 double clicked
  63        BUTTON1_TRIPLE_CLICKED   mouse button 1 triple clicked
  64
  65        BUTTON2_PRESSED          mouse button 2 down
  66        BUTTON2_RELEASED         mouse button 2 up
  67        BUTTON2_CLICKED          mouse button 2 clicked
  68        BUTTON2_DOUBLE_CLICKED   mouse button 2 double clicked
  69        BUTTON2_TRIPLE_CLICKED   mouse button 2 triple clicked
  70        BUTTON3_PRESSED          mouse button 3 down
  71        BUTTON3_RELEASED         mouse button 3 up
  72        BUTTON3_CLICKED          mouse button 3 clicked
  73        BUTTON3_DOUBLE_CLICKED   mouse button 3 double clicked
  74        BUTTON3_TRIPLE_CLICKED   mouse button 3 triple clicked
  75        BUTTON4_PRESSED          mouse button 4 down
  76        BUTTON4_RELEASED         mouse button 4 up
  77        BUTTON4_CLICKED          mouse button 4 clicked
  78        BUTTON4_DOUBLE_CLICKED   mouse button 4 double clicked
  79        BUTTON4_TRIPLE_CLICKED   mouse button 4 triple clicked
  80        BUTTON_SHIFT             shift was down during button state change
  81        BUTTON_CTRL              control was down during button state change
  82        BUTTON_ALT               alt was down during button state change
  83        ALL_MOUSE_EVENTS         report all button state changes
  84        REPORT_MOUSE_POSITION    report mouse movement
  85
  86        Once a class of mouse events have been made visible  in  a
  87        window,  calling  the  <B>wgetch</B>  function on that window may
  88        return <B>KEY_MOUSE</B> as an indicator that a  mouse  event  has
  89        been queued.  To read the event data and pop the event off
  90        the queue, call <B>getmouse</B>.  This function will return <B>OK</B> if
  91        a mouse event is actually visible in the given window, <B>ERR</B>
  92        otherwise.  When <B>getmouse</B> returns <B>OK</B>, the  data  deposited
  93        as  y  and  x  in  the event structure coordinates will be
  94        screen-relative character-cell coordinates.  The  returned
  95        state  mask  will have exactly one bit set to indicate the
  96        event type.
  97
  98        The <B>ungetmouse</B> function behaves  analogously  to  <B>ungetch</B>.
  99        It  pushes  a  <B>KEY_MOUSE</B>  event  onto the input queue, and
 100        associates with  that  event  the  given  state  data  and
 101        screen-relative character-cell coordinates.
 102
 103        The  <B>wenclose</B>  function  tests  whether  a  given  pair of
 104        screen-relative character-cell coordinates is enclosed  by
 105        a  given  window, returning TRUE if it is and FALSE other-
 106        wise.  It is useful for determining  what  subset  of  the
 107        screen windows enclose the location of a mouse event.
 108
 109        The <B>wmouse_trafo</B> function transforms a given pair of coor-
 110        dinates from stdscr-relative coordinates  to  screen-rela-
 111        tive  coordinates  or  vice  versa.  Please remember, that
 112        stdscr-relative coordinates are not  always  identical  to
 113        screen-relative   coordinates  due  to  the  mechanism  to
 114        reserve lines on top or bottom of  the  screen  for  other
 115        purposes  (ripoff() call, see also slk_...  functions). If
 116        the parameter <B>to_screen</B> is <B>TRUE</B>, the pointers <B>pY,</B> <B>pX</B>  must
 117        reference  the coordinates of a location inside the window
 118        <B>win</B>. They are converted to screen-relative coordinates and
 119        returned  through the pointers. If the conversion was suc-
 120        cessful, the function returns <B>TRUE</B>. If one of the  parame-
 121        ters  was  NULL  or the location is not inside the window,
 122        <B>FALSE</B> is returned. If <B>to_screen</B> is <B>FALSE</B>, the pointers <B>pY,</B>
 123        <B>pX</B>  must  reference  screen-relative coordinates. They are
 124        converted to stdscr-relative coordinates if the window <B>win</B>
 125        encloses  this  point.  In  this case the function returns
 126        <B>TRUE</B>. If one of the parameters is NULL or the point is not
 127        inside  the window, <B>FALSE</B> is returned. Please notice, that
 128        the referenced coordinates are only replaced by  the  con-
 129        verted coordinates if the transformation was successful.
 130
 131        The <B>mouseinterval</B> function sets the maximum time (in thou-
 132        sands of a second)  that  can  elapse  between  press  and
 133        release  events  in  order  for them to be recognized as a
 134        click.  This function returns the previous interval value.
 135        The default is one fifth of a second.
 136
 137        Note  that  mouse  events will be ignored when input is in
 138        cooked mode, and will cause an error beep when cooked mode
 139        is  being simulated in a window by a function such as <B>get-</B>
 140        <B>str</B> that expects a linefeed for input-loop termination.
 141
 142
 143
 144 </PRE>
 145 <H2>RETURN VALUE</H2><PRE>
 146        <B>getmouse</B>, <B>ungetmouse</B> and <B>mouseinterval</B> return the  integer
 147        <B>ERR</B>  upon failure or <B>OK</B> upon successful completion. <B>mouse-</B>
 148        <B>mask</B> returns the mask of reportable events.  <B>wenclose</B>  and
 149        <B>wmouse_trafo</B> are boolean functions returning <B>TRUE</B> or <B>FALSE</B>
 150        depending on their test result.
 151
 152
 153 </PRE>
 154 <H2>PORTABILITY</H2><PRE>
 155        These calls were designed for  <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>,  and  are  not
 156        found in SVr4 curses, 4.4BSD curses, or any other previous
 157        version of curses.
 158
 159        The feature macro <B>NCURSES_MOUSE_VERSION</B> is provided so the
 160        preprocessor  can  be  used to test whether these features
 161        are present  (its  value  is  1).   If  the  interface  is
 162        changed, the value of <B>NCURSES_MOUSE_VERSION</B> will be incre-
 163        mented.
 164
 165        The order of the <B>MEVENT</B> structure members is  not  guaran-
 166        teed.   Additional fields may be added to the structure in
 167        the future.
 168
 169        Under  <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>,  these  calls  are  implemented  using
 170        either  xterm's  built-in mouse-tracking API or Alessandro
 171        Rubini's gpm server.  If you  are  using  something  other
 172        than  xterm  and  there  is  no gpm daemon running on your
 173        machine, mouse events will not be visible  to  <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>
 174        (and the <B>wmousemask</B> function will always return <B>0</B>).
 175
 176        The z member in the event structure is not presently used.
 177        It is intended for use with touch screens  (which  may  be
 178        pressure-sensitive)   or   with   3D-mice/trackballs/power
 179        gloves.
 180
 181
 182 </PRE>
 183 <H2>BUGS</H2><PRE>
 184        Mouse events under xterm will not in fact be ignored  dur-
 185        ing  cooked mode, if they have been enabled by <B>wmousemask</B>.
 186        Instead, the xterm mouse report sequence  will  appear  in
 187        the string read.
 188
 189        Mouse events under xterm will not be detected correctly in
 190        a window with its keypad bit off, since  they  are  inter-
 191        preted  as  a  variety  of  function  key.   Your terminfo
 192        description must have <B>kmous</B> set to "\E[M"  (the  beginning
 193        of the response from xterm for mouse clicks).
 194
 195        Because  there  are  no  standard  terminal responses that
 196        would serve to identify terminals which support the  xterm
 197        mouse  protocol,  <B>ncurses</B>  assumes  that  if your $DISPLAY
 198        environment variable is set, and <B>kmous</B> is defined  in  the
 199        terminal  description,  then  the  terminal may send mouse
 200        events.
 201
 202
 203 </PRE>
 204 <H2>SEE ALSO</H2><PRE>
 205        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>.
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235 </PRE>
 236 <HR>
 237 <ADDRESS>
 238 Man(1) output converted with
 239 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 240 </ADDRESS>
 241 </BODY>
 242 </HTML>