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.96 2024/03/23 20:38:57 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-03-23 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-03-23 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>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
  70
  71        <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>
  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-mousemask">mousemask</a></H3><PRE>
  89        To make mouse events visible, use the <STRONG>mousemask</STRONG>  function.   This  sets
  90        the  mouse  events  to  be  reported.   By default, no mouse events are
  91        reported.
  92
  93        <STRONG>o</STRONG>   The function returns an updated copy of <EM>newmask</EM> to  indicate  which
  94            of the specified mouse events can be reported.
  95
  96            If the screen has not been initialized, or if the terminal does not
  97            support mouse-events, this function returns 0.
  98
  99        <STRONG>o</STRONG>   If <EM>oldmask</EM> is non-<STRONG>NULL</STRONG>, this function fills the indicated  location
 100            with the previous value of the current screen's mouse event mask.
 101
 102        As  a  side  effect,  setting  a zero mouse mask may turn off the mouse
 103        pointer; setting a nonzero mask may turn it on.  Whether  this  happens
 104        is device-dependent.
 105
 106
 107 </PRE><H3><a name="h3-Mouse-Events">Mouse Events</a></H3><PRE>
 108        Here are the mouse event type masks which may be defined:
 109
 110        <STRONG>Name</STRONG>                     <STRONG>Description</STRONG>
 111        ------------------------------------------------------------------------
 112        <STRONG>BUTTON1_PRESSED</STRONG>          mouse button 1 down
 113        <STRONG>BUTTON1_RELEASED</STRONG>         mouse button 1 up
 114        <STRONG>BUTTON1_CLICKED</STRONG>          mouse button 1 clicked
 115
 116        <STRONG>BUTTON1_DOUBLE_CLICKED</STRONG>   mouse button 1 double clicked
 117        <STRONG>BUTTON1_TRIPLE_CLICKED</STRONG>   mouse button 1 triple clicked
 118        ------------------------------------------------------------------------
 119        <STRONG>BUTTON2_PRESSED</STRONG>          mouse button 2 down
 120        <STRONG>BUTTON2_RELEASED</STRONG>         mouse button 2 up
 121        <STRONG>BUTTON2_CLICKED</STRONG>          mouse button 2 clicked
 122        <STRONG>BUTTON2_DOUBLE_CLICKED</STRONG>   mouse button 2 double clicked
 123        <STRONG>BUTTON2_TRIPLE_CLICKED</STRONG>   mouse button 2 triple clicked
 124        ------------------------------------------------------------------------
 125        <STRONG>BUTTON3_PRESSED</STRONG>          mouse button 3 down
 126        <STRONG>BUTTON3_RELEASED</STRONG>         mouse button 3 up
 127        <STRONG>BUTTON3_CLICKED</STRONG>          mouse button 3 clicked
 128        <STRONG>BUTTON3_DOUBLE_CLICKED</STRONG>   mouse button 3 double clicked
 129        <STRONG>BUTTON3_TRIPLE_CLICKED</STRONG>   mouse button 3 triple clicked
 130        ------------------------------------------------------------------------
 131        <STRONG>BUTTON4_PRESSED</STRONG>          mouse button 4 down
 132        <STRONG>BUTTON4_RELEASED</STRONG>         mouse button 4 up
 133        <STRONG>BUTTON4_CLICKED</STRONG>          mouse button 4 clicked
 134        <STRONG>BUTTON4_DOUBLE_CLICKED</STRONG>   mouse button 4 double clicked
 135        <STRONG>BUTTON4_TRIPLE_CLICKED</STRONG>   mouse button 4 triple clicked
 136        ------------------------------------------------------------------------
 137        <STRONG>BUTTON5_PRESSED</STRONG>          mouse button 5 down
 138        <STRONG>BUTTON5_RELEASED</STRONG>         mouse button 5 up
 139        <STRONG>BUTTON5_CLICKED</STRONG>          mouse button 5 clicked
 140        <STRONG>BUTTON5_DOUBLE_CLICKED</STRONG>   mouse button 5 double clicked
 141        <STRONG>BUTTON5_TRIPLE_CLICKED</STRONG>   mouse button 5 triple clicked
 142        ------------------------------------------------------------------------
 143        <STRONG>BUTTON_SHIFT</STRONG>             shift was down during button state change
 144        <STRONG>BUTTON_CTRL</STRONG>              control was down during button state change
 145        <STRONG>BUTTON_ALT</STRONG>               alt was down during button state change
 146        <STRONG>ALL_MOUSE_EVENTS</STRONG>         report all button state changes
 147        <STRONG>REPORT_MOUSE_POSITION</STRONG>    report mouse movement
 148        ------------------------------------------------------------------------
 149
 150
 151 </PRE><H3><a name="h3-getmouse">getmouse</a></H3><PRE>
 152        Once a class of mouse events has been made visible in a window, calling
 153        the <STRONG>wgetch</STRONG> function on that window may return <STRONG>KEY_MOUSE</STRONG> as an indicator
 154        that a mouse event has been queued.  To read the event data and pop the
 155        event off the queue, call <STRONG>getmouse</STRONG>.  This function will return <STRONG>OK</STRONG> if  a
 156        mouse  event  is  actually  visible in the given window, <STRONG>ERR</STRONG> otherwise.
 157        When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited as y and x  in  the  event
 158        structure    coordinates   will   be   screen-relative   character-cell
 159        coordinates.  The returned state mask will have exactly one bit set  to
 160        indicate the event type.  The corresponding data in the queue is marked
 161        invalid.  A subsequent call to <STRONG>getmouse</STRONG> will retrieve  the  next  older
 162        item from the queue.
 163
 164
 165 </PRE><H3><a name="h3-ungetmouse">ungetmouse</a></H3><PRE>
 166        The  <STRONG>ungetmouse</STRONG>  function  behaves analogously to <STRONG>ungetch</STRONG>.  It pushes a
 167        <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and associates  with  that  event
 168        the given state data and screen-relative character-cell coordinates.
 169
 170
 171 </PRE><H3><a name="h3-wenclose">wenclose</a></H3><PRE>
 172        The  <STRONG>wenclose</STRONG>  function  tests  whether a given pair of screen-relative
 173        character-cell coordinates is enclosed by  a  given  window,  returning
 174        <STRONG>TRUE</STRONG>  if  it is and <STRONG>FALSE</STRONG> otherwise.  It is useful for determining what
 175        subset of the screen windows enclose the location of a mouse event.
 176
 177        If the parameter is  a  pad,  <STRONG>wenclose</STRONG>  uses  the  most  recent  screen
 178        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>.
 179
 180
 181 </PRE><H3><a name="h3-wmouse_trafo">wmouse_trafo</a></H3><PRE>
 182        The  <STRONG>wmouse_trafo</STRONG>  function transforms a given pair of coordinates from
 183        <STRONG>stdscr</STRONG>-relative coordinates to coordinates relative to the given window
 184        or  vice  versa.   The  resulting  <STRONG>stdscr</STRONG>-relative  coordinates are not
 185        always identical to screen coordinates due to the mechanism to  reserve
 186        lines  on  top  or  bottom  of  the  screen for other purposes (see the
 187        <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).
 188
 189        <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
 190            reference  the  coordinates  of  a  location inside the window <EM>win</EM>.
 191            They are converted  to  <STRONG>stdscr</STRONG>-relative  coordinates  and  returned
 192            through  the  pointers.   If  the  conversion  was  successful, the
 193            function returns <STRONG>TRUE</STRONG>.
 194
 195            If one of the parameters was <STRONG>NULL</STRONG> or the location is not inside the
 196            window, <STRONG>FALSE</STRONG> is returned.
 197
 198        <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
 199            <STRONG>stdscr</STRONG>-relative coordinates.  They are converted to window-relative
 200            coordinates  if  the  window <EM>win</EM> encloses this point.  In this case
 201            the function returns <STRONG>TRUE</STRONG>.
 202
 203            If one of the parameters is <STRONG>NULL</STRONG> or the point  is  not  inside  the
 204            window, <STRONG>FALSE</STRONG> is returned.
 205
 206        The   referenced   coordinates  are  only  replaced  by  the  converted
 207        coordinates if the transformation was successful.
 208
 209
 210 </PRE><H3><a name="h3-mouse_trafo">mouse_trafo</a></H3><PRE>
 211        The <STRONG>mouse_trafo</STRONG> function performs the same translation as <STRONG>wmouse_trafo</STRONG>,
 212        using <STRONG>stdscr</STRONG> for <EM>win</EM>.
 213
 214
 215 </PRE><H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE>
 216        The  <STRONG>mouseinterval</STRONG>  function  sets  the maximum time (in thousands of a
 217        second) that can elapse between press and release events for them to be
 218        resolved  as  a <EM>click</EM>.  An application might interpret button press and
 219        release events separated by more than the mouse  interval  as  a  "long
 220        press", or, with motion, as a "drag".
 221
 222        Calling  <STRONG>mouseinterval(0)</STRONG>  disables  click  resolution.   When  <EM>ncurses</EM>
 223        detects a mouse event, it awaits further  input  activity  up  to  this
 224        interval,  and  then  checks  for a subsequent mouse event which can be
 225        combined with the first event.  If the timeout  expires  without  input
 226        activity  (which  would  happen  with  a  zero interval), then no click
 227        resolution will occur.
 228
 229        This   function   returns   the   previous   interval    value.     Use
 230        <STRONG>mouseinterval(-1)</STRONG> to obtain the interval without altering it.
 231
 232        The  mouse  interval  is  set  to  one  sixth  of  a  second  when  the
 233        corresponding  screen  is  initialized,   e.g.,   in   <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>   or
 234        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.
 235
 236
 237 </PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>
 238        The  <STRONG>has_mouse</STRONG>  function  returns  <STRONG>TRUE</STRONG>  if  the  mouse driver has been
 239        successfully initialized, and <STRONG>FALSE</STRONG> otherwise.
 240
 241        Mouse events are ignored when input is in cooked  mode,  and  cause  an
 242        error  beep  when  cooked  mode  is  being  simulated  in a window by a
 243        function  such  as  <STRONG>getstr</STRONG>  that  expects  a  linefeed  for  input-loop
 244        termination.
 245
 246
 247 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 248        <STRONG>has_mouse</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, and <STRONG>wmouse_trafo</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
 249        as noted above.
 250
 251        <STRONG>getmouse</STRONG> and <STRONG>ungetmouse</STRONG> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
 252
 253        <STRONG>getmouse</STRONG> fails if:
 254
 255        <STRONG>o</STRONG>   no mouse driver was initialized,
 256
 257        <STRONG>o</STRONG>   the mask of reportable events is zero,
 258
 259        <STRONG>o</STRONG>   a mouse event was detected that does not match the mask,
 260
 261        <STRONG>o</STRONG>   or if no more events remain in the queue.
 262
 263        <STRONG>ungetmouse</STRONG> returns an error if the event queue is full.
 264
 265        <STRONG>mousemask</STRONG> returns the mask of reportable events.
 266
 267        <STRONG>mouseinterval</STRONG> returns the previous interval value, unless the  terminal
 268        was  not  initialized.   In  that case, it returns the maximum interval
 269        value (166).
 270
 271
 272 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 273        The  order  of  the  <STRONG>MEVENT</STRONG>  structure  members  is   not   guaranteed.
 274        Additional fields may be added to the structure in the future.
 275
 276        Under  <EM>ncurses</EM>, these calls are implemented using either <EM>xterm</EM>'s built-
 277        in mouse-tracking API or platform-specific drivers including
 278
 279           <STRONG>o</STRONG>   Alessandro Rubini's gpm server
 280
 281           <STRONG>o</STRONG>   FreeBSD sysmouse
 282
 283           <STRONG>o</STRONG>   OS/2 EMX
 284
 285        If you are using an unsupported configuration, mouse events will not be
 286        visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function will always return <STRONG>0</STRONG>).
 287
 288        If  the  <EM>terminfo</EM> entry contains a <STRONG>XM</STRONG> string, this is used in the <EM>xterm</EM>
 289        mouse driver to control the way the terminal is initialized  for  mouse
 290        operation.   The  default,  if  <STRONG>XM</STRONG> is not found, corresponds to private
 291        mode 1000 of <EM>xterm:</EM>
 292
 293           \E[?1000%?%p1%{1}%=%th%el%;
 294
 295        The mouse driver also recognizes a newer <EM>xterm</EM> private mode 1006, e.g.,
 296
 297           \E[?1006;1000%?%p1%{1}%=%th%el%;
 298
 299        The <EM>z</EM> member in the event structure  is  not  presently  used.   It  is
 300        intended  for  use with touch screens (which may be pressure-sensitive)
 301        or with 3D-mice/trackballs/power gloves.
 302
 303        The <STRONG>ALL_MOUSE_EVENTS</STRONG>  class  does  not  include  <STRONG>REPORT_MOUSE_POSITION</STRONG>.
 304        They  are  distinct.   For example, in <EM>xterm</EM>, wheel/scrolling mice send
 305        position reports as a sequence of presses of buttons  4  or  5  without
 306        matching button-releases.
 307
 308
 309 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 310        These  functions  were  designed  for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and are not found in
 311        SVr4  <EM>curses</EM>,   4.4BSD   <EM>curses</EM>,   or   any   other   previous   curses
 312        implementation.   (SVr4 <EM>curses</EM> did have a <EM>getmouse</EM> function, which took
 313        no argument and returned a different type.)
 314
 315
 316 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 317        Applications employing the <EM>ncurses</EM> mouse extension should condition its
 318        use  on the visibility of the <STRONG>NCURSES_MOUSE_VERSION</STRONG> preprocessor macro.
 319        When the interface changes, the  macro's  value  increments.   Multiple
 320        versions   are  available  when  <EM>ncurses</EM>  is  configured;  see  section
 321        "ALTERNATE CONFIGURATIONS" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.  The following values may be
 322        specified.
 323
 324           1  has definitions for reserved events.  The mask uses 28 bits.
 325
 326           2  adds  definitions  for  button  5,  removes  the  definitions for
 327              reserved events.  The mask uses 29 bits.
 328
 329        SVr4 <EM>curses</EM> had support for the mouse in a variant of <STRONG>xterm(1)</STRONG>.  It  is
 330        mentioned in a few places, with little supporting documentation.
 331
 332        <STRONG>o</STRONG>   Its  "libcurses"  manual  page  lists  functions  for  this feature
 333            prototyped in <EM>curses.h</EM>.
 334
 335                extern int mouse_set(long int);
 336                extern int mouse_on(long int);
 337                extern int mouse_off(long int);
 338                extern int request_mouse_pos(void);
 339                extern int map_button(unsigned long);
 340                extern void wmouse_position(WINDOW *, int *, int *);
 341                extern unsigned long getmouse(void), getbmap(void);
 342
 343        <STRONG>o</STRONG>   Its "terminfo" manual page lists capabilities for the feature.
 344
 345                <STRONG>buttons</STRONG>         <STRONG>btns</STRONG>    <STRONG>BT</STRONG>   Number of buttons on the mouse
 346                <STRONG>get_mouse</STRONG>       <STRONG>getm</STRONG>    <STRONG>Gm</STRONG>   Curses should get button events
 347                <STRONG>key_mouse</STRONG>       <STRONG>kmous</STRONG>   <STRONG>Km</STRONG>   0631, Mouse event has occurred
 348                <STRONG>mouse_info</STRONG>      <STRONG>minfo</STRONG>   <STRONG>Mi</STRONG>   Mouse status information
 349                <STRONG>req_mouse_pos</STRONG>   <STRONG>reqmp</STRONG>   <STRONG>RQ</STRONG>   Request mouse position report
 350
 351        <STRONG>o</STRONG>   The interface made assumptions (as does <EM>ncurses</EM>) about  the  escape
 352            sequences sent to and received from the terminal.
 353
 354            For instance, the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> capability
 355            to tell the terminal which mouse  button  events  it  should  send,
 356            passing  the mouse-button bit mask to the terminal.  Also, it could
 357            ask the terminal  where  the  mouse  was  using  the  <STRONG>req_mouse_pos</STRONG>
 358            capability.
 359
 360            Those  features  required a terminal program that had been modified
 361            to work with SVr4 <EM>curses</EM>.  They were not part of the X Consortium's
 362            <EM>xterm</EM>.
 363
 364        When  developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995,
 365        Eric Raymond was uninterested in using the same interface  due  to  its
 366        lack of documentation.  Later, in 1998, Mark Hesseling provided support
 367        in <EM>PDCurses</EM> 2.3 using the SVr4 interface.  <EM>PDCurses</EM>, however, does  not
 368        use  video  terminals,  making  it  unnecessary  to  be concerned about
 369        compatibility with the escape sequences.
 370
 371
 372 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
 373        Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in cooked  mode  if  they  have
 374        been  enabled  by  <STRONG>mousemask</STRONG>.  Instead, the <EM>xterm</EM> mouse report sequence
 375        appears in the string read.
 376
 377        Mouse event reports from <EM>xterm</EM> are not detected correctly in  a  window
 378        with  keypad application mode disabled, since they are interpreted as a
 379        variety of function key.  Set the terminal's <EM>terminfo</EM> capability  <STRONG>kmous</STRONG>
 380        to  "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse clicks).
 381        Other values of <STRONG>kmous</STRONG> are permitted under the same assumption, that is,
 382        the report begins with that sequence.
 383
 384        Because there are no standard response sequences that serve to identify
 385        terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that  if
 386        <STRONG>kmous</STRONG> is defined in the terminal description, or if the terminal type's
 387        primary name or aliases contain the string "xterm", then  the  terminal
 388        may send mouse events.  The <STRONG>kmous</STRONG> capability is checked first, allowing
 389        use of newer <EM>xterm</EM> mouse protocols, such as its private mode 1006.
 390
 391
 392 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 393        <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>,
 394        <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 395
 396
 397
 398 ncurses 6.4                       2024-03-23                    <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
 399 </PRE>
 400 <div class="nav">
 401 <ul>
 402 <li><a href="#h2-NAME">NAME</a></li>
 403 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 404 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 405 <ul>
 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 <li><a href="#h3-has_mouse">has_mouse</a></li>
 415 </ul>
 416 </li>
 417 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 418 <li><a href="#h2-NOTES">NOTES</a></li>
 419 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 420 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 421 <li><a href="#h2-BUGS">BUGS</a></li>
 422 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 423 </ul>
 424 </div>
 425 </BODY>
 426 </HTML>