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.89 2024/02/17 21:43:03 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-02-17 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-02-17 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 mousemask 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>ripoffline</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 click.
 219
 220        Calling  <STRONG>mouseinterval(0)</STRONG>  disables  click  resolution.   When  ncurses
 221        detects a mouse event, it awaits further  input  activity  up  to  this
 222        interval,  and  then  checks  for a subsequent mouse event which can be
 223        combined with the first event.  If the timeout  expires  without  input
 224        activity  (which  would  happen  with  a  zero interval), then no click
 225        resolution will occur.
 226
 227        This   function   returns   the   previous   interval    value.     Use
 228        <STRONG>mouseinterval(-1)</STRONG> to obtain the interval without altering it.
 229
 230        The  mouse  interval  is  set  to  one  sixth  of  a  second  when  the
 231        corresponding  screen  is  initialized,   e.g.,   in   <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>   or
 232        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.
 233
 234
 235 </PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>
 236        The  <STRONG>has_mouse</STRONG>  function  returns  <STRONG>TRUE</STRONG>  if  the  mouse driver has been
 237        successfully initialized, and <STRONG>FALSE</STRONG> otherwise.
 238
 239        Mouse events are ignored when input is in cooked  mode,  and  cause  an
 240        error  beep  when  cooked  mode  is  being  simulated  in a window by a
 241        function  such  as  <STRONG>getstr</STRONG>  that  expects  a  linefeed  for  input-loop
 242        termination.
 243
 244
 245 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 246        <STRONG>has_mouse</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, and <STRONG>wmouse_trafo</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
 247        as noted above.
 248
 249        <STRONG>getmouse</STRONG> and <STRONG>ungetmouse</STRONG> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
 250
 251        <STRONG>getmouse</STRONG> fails if:
 252
 253        <STRONG>o</STRONG>   no mouse driver was initialized,
 254
 255        <STRONG>o</STRONG>   the mask of reportable events is zero,
 256
 257        <STRONG>o</STRONG>   a mouse event was detected that does not match the mask,
 258
 259        <STRONG>o</STRONG>   or if no more events remain in the queue.
 260
 261        <STRONG>ungetmouse</STRONG> returns an error if the event queue is full.
 262
 263        <STRONG>mousemask</STRONG> returns the mask of reportable events.
 264
 265        <STRONG>mouseinterval</STRONG> returns the previous interval value, unless the  terminal
 266        was  not  initialized.   In  that case, it returns the maximum interval
 267        value (166).
 268
 269
 270 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 271        The  order  of  the  <STRONG>MEVENT</STRONG>  structure  members  is   not   guaranteed.
 272        Additional fields may be added to the structure in the future.
 273
 274        Under  <EM>ncurses,</EM> these calls are implemented using either <EM>xterm</EM>'s built-
 275        in mouse-tracking API or platform-specific drivers including
 276
 277           <STRONG>o</STRONG>   Alessandro Rubini's gpm server
 278
 279           <STRONG>o</STRONG>   FreeBSD sysmouse
 280
 281           <STRONG>o</STRONG>   OS/2 EMX
 282
 283        If you are using an unsupported configuration, mouse events will not be
 284        visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function will always return <STRONG>0</STRONG>).
 285
 286        If  the  <EM>terminfo</EM> entry contains a <STRONG>XM</STRONG> string, this is used in the <EM>xterm</EM>
 287        mouse driver to control the way the terminal is initialized  for  mouse
 288        operation.   The  default,  if  <STRONG>XM</STRONG> is not found, corresponds to private
 289        mode 1000 of <EM>xterm:</EM>
 290
 291           \E[?1000%?%p1%{1}%=%th%el%;
 292
 293        The mouse driver also recognizes a newer <EM>xterm</EM> private mode 1006, e.g.,
 294
 295           \E[?1006;1000%?%p1%{1}%=%th%el%;
 296
 297        The <EM>z</EM> member in the event structure  is  not  presently  used.   It  is
 298        intended  for  use with touch screens (which may be pressure-sensitive)
 299        or with 3D-mice/trackballs/power gloves.
 300
 301        The <STRONG>ALL_MOUSE_EVENTS</STRONG>  class  does  not  include  <STRONG>REPORT_MOUSE_POSITION</STRONG>.
 302        They  are  distinct.   For example, in <EM>xterm,</EM> wheel/scrolling mice send
 303        position reports as a sequence of presses of buttons  4  or  5  without
 304        matching button-releases.
 305
 306
 307 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 308        These  functions  were  designed  for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and are not found in
 309        SVr4  <EM>curses</EM>,   4.4BSD   <EM>curses</EM>,   or   any   other   previous   curses
 310        implementation.   (SVr4 <EM>curses</EM> did have a <EM>getmouse</EM> function, which took
 311        no argument and returned a different type.)
 312
 313
 314 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 315        Applications employing the <EM>ncurses</EM> mouse extension should condition its
 316        use  on the visibility of the <STRONG>NCURSES_MOUSE_VERSION</STRONG> preprocessor macro.
 317        When the interface changes, the  macro's  value  increments.   Multiple
 318        versions   are  available  when  <EM>ncurses</EM>  is  configured;  see  section
 319        "ALTERNATE CONFIGURATIONS" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.  The following values may be
 320        specified.
 321
 322           1  has definitions for reserved events.  The mask uses 28 bits.
 323
 324           2  adds  definitions  for  button  5,  removes  the  definitions for
 325              reserved events.  The mask uses 29 bits.
 326
 327        SVr4 <EM>curses</EM> had support for the mouse in a variant of <STRONG>xterm(1)</STRONG>.  It  is
 328        mentioned in a few places, with little supporting documentation.
 329
 330        <STRONG>o</STRONG>   Its  "libcurses"  manual  page  lists  functions  for  this feature
 331            prototyped in <EM>curses.h</EM>.
 332
 333                extern int mouse_set(long int);
 334                extern int mouse_on(long int);
 335                extern int mouse_off(long int);
 336                extern int request_mouse_pos(void);
 337                extern int map_button(unsigned long);
 338                extern void wmouse_position(WINDOW *, int *, int *);
 339                extern unsigned long getmouse(void), getbmap(void);
 340
 341        <STRONG>o</STRONG>   Its "terminfo" manual page lists capabilities for the feature.
 342
 343                <STRONG>buttons</STRONG>         <STRONG>btns</STRONG>    <STRONG>BT</STRONG>   Number of buttons on the mouse
 344                <STRONG>get_mouse</STRONG>       <STRONG>getm</STRONG>    <STRONG>Gm</STRONG>   Curses should get button events
 345                <STRONG>key_mouse</STRONG>       <STRONG>kmous</STRONG>   <STRONG>Km</STRONG>   0631, Mouse event has occurred
 346                <STRONG>mouse_info</STRONG>      <STRONG>minfo</STRONG>   <STRONG>Mi</STRONG>   Mouse status information
 347                <STRONG>req_mouse_pos</STRONG>   <STRONG>reqmp</STRONG>   <STRONG>RQ</STRONG>   Request mouse position report
 348
 349        <STRONG>o</STRONG>   The interface made assumptions (as does <EM>ncurses</EM>) about  the  escape
 350            sequences sent to and received from the terminal.
 351
 352            For instance, the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> capability
 353            to tell the terminal which mouse  button  events  it  should  send,
 354            passing  the mouse-button bit mask to the terminal.  Also, it could
 355            ask the terminal  where  the  mouse  was  using  the  <STRONG>req_mouse_pos</STRONG>
 356            capability.
 357
 358            Those  features  required a terminal program that had been modified
 359            to work with SVr4 <EM>curses.</EM>  They were not part of the X Consortium's
 360            <EM>xterm.</EM>
 361
 362        When  developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995,
 363        Eric Raymond was uninterested in using the same interface  due  to  its
 364        lack of documentation.  Later, in 1998, Mark Hesseling provided support
 365        in <EM>PDCurses</EM> 2.3 using the SVr4 interface.  <EM>PDCurses,</EM> however, does  not
 366        use  video  terminals,  making  it  unnecessary  to  be concerned about
 367        compatibility with the escape sequences.
 368
 369
 370 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
 371        Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in cooked  mode  if  they  have
 372        been  enabled  by  <STRONG>mousemask</STRONG>.  Instead, the <EM>xterm</EM> mouse report sequence
 373        appears in the string read.
 374
 375        Mouse event reports from <EM>xterm</EM> are not detected correctly in  a  window
 376        with  keypad application mode disabled, since they are interpreted as a
 377        variety of function key.  Set the terminal's <EM>terminfo</EM> capability  <STRONG>kmous</STRONG>
 378        to  "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse clicks).
 379        Other values of <STRONG>kmous</STRONG> are permitted under the same assumption, that is,
 380        the report begins with that sequence.
 381
 382        Because there are no standard response sequences that serve to identify
 383        terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that  if
 384        <STRONG>kmous</STRONG> is defined in the terminal description, or if the terminal type's
 385        primary name or aliases contain the string "xterm", then  the  terminal
 386        may send mouse events.  The <STRONG>kmous</STRONG> capability is checked first, allowing
 387        use of newer <EM>xterm</EM> mouse protocols, such as its private mode 1006.
 388
 389
 390 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 391        <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>,
 392        <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 393
 394
 395
 396 ncurses 6.4                       2024-02-17                    <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
 397 </PRE>
 398 <div class="nav">
 399 <ul>
 400 <li><a href="#h2-NAME">NAME</a></li>
 401 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 402 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 403 <ul>
 404 <li><a href="#h3-mousemask">mousemask</a></li>
 405 <li><a href="#h3-Mouse-Events">Mouse Events</a></li>
 406 <li><a href="#h3-getmouse">getmouse</a></li>
 407 <li><a href="#h3-ungetmouse">ungetmouse</a></li>
 408 <li><a href="#h3-wenclose">wenclose</a></li>
 409 <li><a href="#h3-wmouse_trafo">wmouse_trafo</a></li>
 410 <li><a href="#h3-mouse_trafo">mouse_trafo</a></li>
 411 <li><a href="#h3-mouseinterval">mouseinterval</a></li>
 412 <li><a href="#h3-has_mouse">has_mouse</a></li>
 413 </ul>
 414 </li>
 415 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 416 <li><a href="#h2-NOTES">NOTES</a></li>
 417 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 418 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 419 <li><a href="#h2-BUGS">BUGS</a></li>
 420 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 421 </ul>
 422 </div>
 423 </BODY>
 424 </HTML>