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

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   5   * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp @
  32 -->
  33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  34 <HTML>
  35 <HEAD>
  36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  38 <TITLE>curs_mouse 3x 2024-04-20 ncurses 6.4 Library calls</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">curs_mouse 3x 2024-04-20 ncurses 6.4 Library calls</H1>
  44 <PRE>
  45 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>                   Library calls                  <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
  46
  47
  48
  49
  50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <STRONG>has_mouse</STRONG>,  <STRONG>getmouse</STRONG>,  <STRONG>ungetmouse</STRONG>,  <STRONG>mousemask</STRONG>,  <STRONG>wenclose</STRONG>,  <STRONG>mouse_trafo</STRONG>,
  52        <STRONG>wmouse_trafo</STRONG>, <STRONG>mouseinterval</STRONG> - get mouse events in <EM>curses</EM>
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG>
  59
  60        <STRONG>typedef</STRONG> <STRONG>struct</STRONG> <STRONG>{</STRONG>
  61            <STRONG>short</STRONG> <STRONG>id;</STRONG>         <EM>/*</EM> <EM>ID</EM> <EM>to</EM> <EM>distinguish</EM> <EM>multiple</EM> <EM>devices</EM> <EM>*/</EM>
  62            <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG>      <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM>
  63            <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG>   <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM>
  64        <STRONG>}</STRONG> <STRONG>MEVENT;</STRONG>
  65
  66        <STRONG>bool</STRONG> <STRONG>has_mouse(void);</STRONG>
  67
  68        <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <EM>newmask</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*</STRONG><EM>oldmask</EM><STRONG>);</STRONG>
  69
  70        <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
  72
  73        <STRONG>bool</STRONG> <STRONG>wenclose(const</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
  74
  75        <STRONG>bool</STRONG> <STRONG>mouse_trafo(int*</STRONG> <EM>pY</EM><STRONG>,</STRONG> <STRONG>int*</STRONG> <EM>pX</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>to</EM><STRONG>_</STRONG><EM>screen</EM><STRONG>);</STRONG>
  76        <STRONG>bool</STRONG> <STRONG>wmouse_trafo(const</STRONG> <STRONG>WINDOW*</STRONG> <EM>win</EM><STRONG>,</STRONG>
  77                          <STRONG>int*</STRONG> <EM>pY</EM><STRONG>,</STRONG> <STRONG>int*</STRONG> <EM>pX</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>to</EM><STRONG>_</STRONG><EM>screen</EM><STRONG>);</STRONG>
  78
  79        <STRONG>int</STRONG> <STRONG>mouseinterval(int</STRONG> <EM>erval</EM><STRONG>);</STRONG>
  80
  81
  82 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  83        These functions provide an interface to mouse events from  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
  84        Mouse  events  are  represented  by  <STRONG>KEY_MOUSE</STRONG> pseudo-key values in the
  85        <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> input stream.
  86
  87
  88 </PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>
  89        The <STRONG>has_mouse</STRONG> function returns  <STRONG>TRUE</STRONG>  if  the  mouse  driver  has  been
  90        successfully initialized, and <STRONG>FALSE</STRONG> otherwise.
  91
  92        Mouse  events  are  ignored  when input is in cooked mode, and cause an
  93        error beep when cooked mode  is  being  simulated  in  a  window  by  a
  94        function  such  as  <STRONG>getstr</STRONG>  that  expects  a  linefeed  for  input-loop
  95        termination.
  96
  97
  98 </PRE><H3><a name="h3-mousemask">mousemask</a></H3><PRE>
  99        To make mouse events visible, use the <STRONG>mousemask</STRONG>  function.   This  sets
 100        the  mouse  events  to  be  reported.   By default, no mouse events are
 101        reported.
 102
 103        <STRONG>o</STRONG>   The function returns an updated copy of <EM>newmask</EM> to  indicate  which
 104            of the specified mouse events can be reported.
 105
 106            If the screen has not been initialized, or if the terminal does not
 107            support mouse-events, this function returns 0.
 108
 109        <STRONG>o</STRONG>   If <EM>oldmask</EM> is non-<STRONG>NULL</STRONG>, this function fills the indicated  location
 110            with the previous value of the current screen's mouse event mask.
 111
 112        As  a  side  effect,  setting  a zero mouse mask may turn off the mouse
 113        pointer; setting a nonzero mask may turn it on.  Whether  this  happens
 114        is device-dependent.
 115
 116
 117 </PRE><H3><a name="h3-Mouse-Events">Mouse Events</a></H3><PRE>
 118        Here are the mouse event type masks which may be defined:
 119
 120        <STRONG>Name</STRONG>                     <STRONG>Description</STRONG>
 121        ------------------------------------------------------------------------
 122        <STRONG>BUTTON1_PRESSED</STRONG>          mouse button 1 down
 123        <STRONG>BUTTON1_RELEASED</STRONG>         mouse button 1 up
 124        <STRONG>BUTTON1_CLICKED</STRONG>          mouse button 1 clicked
 125        <STRONG>BUTTON1_DOUBLE_CLICKED</STRONG>   mouse button 1 double clicked
 126        <STRONG>BUTTON1_TRIPLE_CLICKED</STRONG>   mouse button 1 triple clicked
 127        ------------------------------------------------------------------------
 128        <STRONG>BUTTON2_PRESSED</STRONG>          mouse button 2 down
 129        <STRONG>BUTTON2_RELEASED</STRONG>         mouse button 2 up
 130        <STRONG>BUTTON2_CLICKED</STRONG>          mouse button 2 clicked
 131        <STRONG>BUTTON2_DOUBLE_CLICKED</STRONG>   mouse button 2 double clicked
 132        <STRONG>BUTTON2_TRIPLE_CLICKED</STRONG>   mouse button 2 triple clicked
 133        ------------------------------------------------------------------------
 134        <STRONG>BUTTON3_PRESSED</STRONG>          mouse button 3 down
 135        <STRONG>BUTTON3_RELEASED</STRONG>         mouse button 3 up
 136        <STRONG>BUTTON3_CLICKED</STRONG>          mouse button 3 clicked
 137        <STRONG>BUTTON3_DOUBLE_CLICKED</STRONG>   mouse button 3 double clicked
 138        <STRONG>BUTTON3_TRIPLE_CLICKED</STRONG>   mouse button 3 triple clicked
 139        ------------------------------------------------------------------------
 140        <STRONG>BUTTON4_PRESSED</STRONG>          mouse button 4 down
 141        <STRONG>BUTTON4_RELEASED</STRONG>         mouse button 4 up
 142        <STRONG>BUTTON4_CLICKED</STRONG>          mouse button 4 clicked
 143        <STRONG>BUTTON4_DOUBLE_CLICKED</STRONG>   mouse button 4 double clicked
 144        <STRONG>BUTTON4_TRIPLE_CLICKED</STRONG>   mouse button 4 triple clicked
 145        ------------------------------------------------------------------------
 146        <STRONG>BUTTON5_PRESSED</STRONG>          mouse button 5 down
 147        <STRONG>BUTTON5_RELEASED</STRONG>         mouse button 5 up
 148        <STRONG>BUTTON5_CLICKED</STRONG>          mouse button 5 clicked
 149        <STRONG>BUTTON5_DOUBLE_CLICKED</STRONG>   mouse button 5 double clicked
 150        <STRONG>BUTTON5_TRIPLE_CLICKED</STRONG>   mouse button 5 triple clicked
 151        ------------------------------------------------------------------------
 152        <STRONG>BUTTON_SHIFT</STRONG>             shift was down during button state change
 153        <STRONG>BUTTON_CTRL</STRONG>              control was down during button state change
 154        <STRONG>BUTTON_ALT</STRONG>               alt was down during button state change
 155        <STRONG>ALL_MOUSE_EVENTS</STRONG>         report all button state changes
 156        <STRONG>REPORT_MOUSE_POSITION</STRONG>    report mouse movement
 157        ------------------------------------------------------------------------
 158
 159
 160 </PRE><H3><a name="h3-getmouse">getmouse</a></H3><PRE>
 161        Once a class of mouse events has been made visible in a window, calling
 162        the <STRONG>wgetch</STRONG> function on that window may return <STRONG>KEY_MOUSE</STRONG> as an indicator
 163        that a mouse event has been queued.  To read the event data and pop the
 164        event off the queue, call <STRONG>getmouse</STRONG>.  This function will return <STRONG>OK</STRONG> if  a
 165        mouse  event  is  actually  visible in the given window, <STRONG>ERR</STRONG> otherwise.
 166        When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited as y and x  in  the  event
 167        structure    coordinates   will   be   screen-relative   character-cell
 168        coordinates.  The returned state mask will have exactly one bit set  to
 169        indicate the event type.  The corresponding data in the queue is marked
 170        invalid.  A subsequent call to <STRONG>getmouse</STRONG> will retrieve  the  next  older
 171        item from the queue.
 172
 173
 174 </PRE><H3><a name="h3-ungetmouse">ungetmouse</a></H3><PRE>
 175        The  <STRONG>ungetmouse</STRONG>  function  behaves analogously to <STRONG>ungetch</STRONG>.  It pushes a
 176        <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and associates  with  that  event
 177        the given state data and screen-relative character-cell coordinates.
 178
 179
 180 </PRE><H3><a name="h3-wenclose">wenclose</a></H3><PRE>
 181        The  <STRONG>wenclose</STRONG>  function  tests  whether a given pair of screen-relative
 182        character-cell coordinates is enclosed by  a  given  window,  returning
 183        <STRONG>TRUE</STRONG>  if  it is and <STRONG>FALSE</STRONG> otherwise.  It is useful for determining what
 184        subset of the screen windows enclose the location of a mouse event.
 185
 186        If the parameter is  a  pad,  <STRONG>wenclose</STRONG>  uses  the  most  recent  screen
 187        coordinates used for this pad in <STRONG><A HREF="curs_pad.3x.html">prefresh(3x)</A></STRONG> or <STRONG><A HREF="curs_pad.3x.html">pnoutrefresh(3x)</A></STRONG>.
 188
 189
 190 </PRE><H3><a name="h3-wmouse_trafo">wmouse_trafo</a></H3><PRE>
 191        The  <STRONG>wmouse_trafo</STRONG>  function transforms a given pair of coordinates from
 192        <STRONG>stdscr</STRONG>-relative coordinates to coordinates relative to the given window
 193        or  vice  versa.   The  resulting  <STRONG>stdscr</STRONG>-relative  coordinates are not
 194        always identical to screen coordinates due to the mechanism to  reserve
 195        lines  on  top  or  bottom  of  the  screen for other purposes (see the
 196        <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> and <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> calls, for example).
 197
 198        <STRONG>o</STRONG>   If the parameter <EM>to</EM><STRONG>_</STRONG><EM>screen</EM>  is  <STRONG>TRUE</STRONG>,  the  pointers  <EM>pY,</EM>  <EM>pX</EM>  must
 199            reference  the  coordinates  of  a  location inside the window <EM>win</EM>.
 200            They are converted  to  <STRONG>stdscr</STRONG>-relative  coordinates  and  returned
 201            through  the  pointers.   If  the  conversion  was  successful, the
 202            function returns <STRONG>TRUE</STRONG>.
 203
 204            If one of the parameters was <STRONG>NULL</STRONG> or the location is not inside the
 205            window, <STRONG>FALSE</STRONG> is returned.
 206
 207        <STRONG>o</STRONG>   If   <EM>to</EM><STRONG>_</STRONG><EM>screen</EM>  is  <STRONG>FALSE</STRONG>,  the  pointers  <EM>pY,</EM>  <EM>pX</EM>  must  reference
 208            <STRONG>stdscr</STRONG>-relative coordinates.  They are converted to window-relative
 209            coordinates  if  the  window <EM>win</EM> encloses this point.  In this case
 210            the function returns <STRONG>TRUE</STRONG>.
 211
 212            If one of the parameters is <STRONG>NULL</STRONG> or the point  is  not  inside  the
 213            window, <STRONG>FALSE</STRONG> is returned.
 214
 215        The   referenced   coordinates  are  only  replaced  by  the  converted
 216        coordinates if the transformation was successful.
 217
 218
 219 </PRE><H3><a name="h3-mouse_trafo">mouse_trafo</a></H3><PRE>
 220        The <STRONG>mouse_trafo</STRONG> function performs the same translation as <STRONG>wmouse_trafo</STRONG>,
 221        using <STRONG>stdscr</STRONG> for <EM>win</EM>.
 222
 223
 224 </PRE><H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE>
 225        The  <STRONG>mouseinterval</STRONG>  function  sets  the maximum time (in thousands of a
 226        second) that can elapse between press and release events for them to be
 227        resolved  as  a <EM>click</EM>.  An application might interpret button press and
 228        release events separated by more than the mouse  interval  as  a  "long
 229        press", or, with motion, as a "drag".
 230
 231        Calling  <STRONG>mouseinterval(0)</STRONG>  disables  click  resolution.   When  <EM>ncurses</EM>
 232        detects a mouse event, it awaits further  input  activity  up  to  this
 233        interval,  and  then  checks  for a subsequent mouse event which can be
 234        combined with the first event.  If the timeout  expires  without  input
 235        activity  (which  would  happen  with  a  zero interval), then no click
 236        resolution will occur.
 237
 238        This   function   returns   the   previous   interval    value.     Use
 239        <STRONG>mouseinterval(-1)</STRONG> to obtain the interval without altering it.
 240
 241        The  mouse  interval  is  set  to  one  sixth  of  a  second  when  the
 242        corresponding  screen  is  initialized,   e.g.,   in   <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>   or
 243        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.
 244
 245
 246 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 247        <STRONG>has_mouse</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, and <STRONG>wmouse_trafo</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
 248        as noted above.
 249
 250        <STRONG>getmouse</STRONG> and <STRONG>ungetmouse</STRONG> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
 251
 252        <STRONG>getmouse</STRONG> fails if:
 253
 254        <STRONG>o</STRONG>   no mouse driver was initialized,
 255
 256        <STRONG>o</STRONG>   the mask of reportable events is zero,
 257
 258        <STRONG>o</STRONG>   a mouse event was detected that does not match the mask,
 259
 260        <STRONG>o</STRONG>   or if no more events remain in the queue.
 261
 262        <STRONG>ungetmouse</STRONG> returns an error if the event queue is full.
 263
 264        <STRONG>mousemask</STRONG> returns the mask of reportable events.
 265
 266        <STRONG>mouseinterval</STRONG> returns the previous interval value, unless the  terminal
 267        was  not  initialized.   In  that case, it returns the maximum interval
 268        value (166).
 269
 270
 271 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 272        The  order  of  the  <STRONG>MEVENT</STRONG>  structure  members  is   not   guaranteed.
 273        Additional fields may be added to the structure in the future.
 274
 275        Under  <EM>ncurses</EM>, these calls are implemented using either <EM>xterm</EM>'s built-
 276        in mouse-tracking API or platform-specific drivers including
 277
 278           <STRONG>o</STRONG>   Alessandro Rubini's gpm server
 279
 280           <STRONG>o</STRONG>   FreeBSD sysmouse
 281
 282           <STRONG>o</STRONG>   OS/2 EMX
 283
 284        If you are using an unsupported configuration, mouse events will not be
 285        visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function will always return <STRONG>0</STRONG>).
 286
 287        If  the  <EM>terminfo</EM> entry contains a <STRONG>XM</STRONG> string, this is used in the <EM>xterm</EM>
 288        mouse driver to control the way the terminal is initialized  for  mouse
 289        operation.   The  default,  if  <STRONG>XM</STRONG> is not found, corresponds to private
 290        mode 1000 of <EM>xterm:</EM>
 291
 292           \E[?1000%?%p1%{1}%=%th%el%;
 293
 294        The mouse driver also recognizes a newer <EM>xterm</EM> private mode 1006, e.g.,
 295
 296           \E[?1006;1000%?%p1%{1}%=%th%el%;
 297
 298        The <EM>z</EM> member in the event structure  is  not  presently  used.   It  is
 299        intended  for  use with touch screens (which may be pressure-sensitive)
 300        or with 3D-mice/trackballs/power gloves.
 301
 302        The <STRONG>ALL_MOUSE_EVENTS</STRONG>  class  does  not  include  <STRONG>REPORT_MOUSE_POSITION</STRONG>.
 303        They  are  distinct.   For example, in <EM>xterm</EM>, wheel/scrolling mice send
 304        position reports as a sequence of presses of buttons  4  or  5  without
 305        matching button-releases.
 306
 307
 308 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 309        These  functions  were  designed  for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and are not found in
 310        SVr4  <EM>curses</EM>,   4.4BSD   <EM>curses</EM>,   or   any   other   previous   curses
 311        implementation.   (SVr4 <EM>curses</EM> did have a <EM>getmouse</EM> function, which took
 312        no argument and returned a different type.)
 313
 314
 315 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 316        Applications employing the <EM>ncurses</EM> mouse extension should condition its
 317        use  on the visibility of the <STRONG>NCURSES_MOUSE_VERSION</STRONG> preprocessor macro.
 318        When the interface changes, the  macro's  value  increments.   Multiple
 319        versions   are  available  when  <EM>ncurses</EM>  is  configured;  see  section
 320        "ALTERNATE CONFIGURATIONS" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.  The following values may be
 321        specified.
 322
 323           1  has definitions for reserved events.  The mask uses 28 bits.
 324
 325           2  adds  definitions  for  button  5,  removes  the  definitions for
 326              reserved events.  The mask uses 29 bits.
 327
 328        SVr4 <EM>curses</EM> had support for the mouse in a variant of <STRONG>xterm(1)</STRONG>.  It  is
 329        mentioned in a few places, with little supporting documentation.
 330
 331        <STRONG>o</STRONG>   Its  "libcurses"  manual  page  lists  functions  for  this feature
 332            prototyped in <EM>curses.h</EM>.
 333
 334                extern int mouse_set(long int);
 335                extern int mouse_on(long int);
 336                extern int mouse_off(long int);
 337                extern int request_mouse_pos(void);
 338                extern int map_button(unsigned long);
 339                extern void wmouse_position(WINDOW *, int *, int *);
 340                extern unsigned long getmouse(void), getbmap(void);
 341
 342        <STRONG>o</STRONG>   Its "terminfo" manual page lists capabilities for the feature.
 343
 344                <STRONG>buttons</STRONG>         <STRONG>btns</STRONG>    <STRONG>BT</STRONG>   Number of buttons on the mouse
 345                <STRONG>get_mouse</STRONG>       <STRONG>getm</STRONG>    <STRONG>Gm</STRONG>   Curses should get button events
 346                <STRONG>key_mouse</STRONG>       <STRONG>kmous</STRONG>   <STRONG>Km</STRONG>   0631, Mouse event has occurred
 347                <STRONG>mouse_info</STRONG>      <STRONG>minfo</STRONG>   <STRONG>Mi</STRONG>   Mouse status information
 348                <STRONG>req_mouse_pos</STRONG>   <STRONG>reqmp</STRONG>   <STRONG>RQ</STRONG>   Request mouse position report
 349
 350        <STRONG>o</STRONG>   The interface made assumptions (as does <EM>ncurses</EM>) about  the  escape
 351            sequences sent to and received from the terminal.
 352
 353            For instance, the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> capability
 354            to tell the terminal which mouse  button  events  it  should  send,
 355            passing  the mouse-button bit mask to the terminal.  Also, it could
 356            ask the terminal  where  the  mouse  was  using  the  <STRONG>req_mouse_pos</STRONG>
 357            capability.
 358
 359            Those  features  required a terminal program that had been modified
 360            to work with SVr4 <EM>curses</EM>.  They were not part of the X Consortium's
 361            <EM>xterm</EM>.
 362
 363        When  developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995,
 364        Eric Raymond was uninterested in using the same interface  due  to  its
 365        lack of documentation.  Later, in 1998, Mark Hesseling provided support
 366        in <EM>PDCurses</EM> 2.3 using the SVr4 interface.  <EM>PDCurses</EM>, however, does  not
 367        use  video  terminals,  making  it  unnecessary  to  be concerned about
 368        compatibility with the escape sequences.
 369
 370
 371 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
 372        Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in cooked  mode  if  they  have
 373        been  enabled  by  <STRONG>mousemask</STRONG>.  Instead, the <EM>xterm</EM> mouse report sequence
 374        appears in the string read.
 375
 376        Mouse event reports from <EM>xterm</EM> are not detected correctly in  a  window
 377        with  keypad application mode disabled, since they are interpreted as a
 378        variety of function key.  Set the terminal's <EM>terminfo</EM> capability  <STRONG>kmous</STRONG>
 379        to  "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse clicks).
 380        Other values of <STRONG>kmous</STRONG> are permitted under the same assumption, that is,
 381        the report begins with that sequence.
 382
 383        Because there are no standard response sequences that serve to identify
 384        terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that  if
 385        <STRONG>kmous</STRONG> is defined in the terminal description, or if the terminal type's
 386        primary name or aliases contain the string "xterm", then  the  terminal
 387        may send mouse events.  The <STRONG>kmous</STRONG> capability is checked first, allowing
 388        use of newer <EM>xterm</EM> mouse protocols, such as its private mode 1006.
 389
 390
 391 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 392        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,     <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,     <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,     <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>,
 393        <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 394
 395
 396
 397 ncurses 6.4                       2024-04-20                    <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
 398 </PRE>
 399 <div class="nav">
 400 <ul>
 401 <li><a href="#h2-NAME">NAME</a></li>
 402 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 403 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 404 <ul>
 405 <li><a href="#h3-has_mouse">has_mouse</a></li>
 406 <li><a href="#h3-mousemask">mousemask</a></li>
 407 <li><a href="#h3-Mouse-Events">Mouse Events</a></li>
 408 <li><a href="#h3-getmouse">getmouse</a></li>
 409 <li><a href="#h3-ungetmouse">ungetmouse</a></li>
 410 <li><a href="#h3-wenclose">wenclose</a></li>
 411 <li><a href="#h3-wmouse_trafo">wmouse_trafo</a></li>
 412 <li><a href="#h3-mouse_trafo">mouse_trafo</a></li>
 413 <li><a href="#h3-mouseinterval">mouseinterval</a></li>
 414 </ul>
 415 </li>
 416 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 417 <li><a href="#h2-NOTES">NOTES</a></li>
 418 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 419 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 420 <li><a href="#h2-BUGS">BUGS</a></li>
 421 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 422 </ul>
 423 </div>
 424 </BODY>
 425 </HTML>