]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/curs_mouse.3x.html
projects / ncurses.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
ncurses 6.5 - patch 20240511
[ncurses.git] / doc / html / man / curs_mouse.3x.html
diff --git a/doc/html/man/curs_mouse.3x.html b/doc/html/man/curs_mouse.3x.html
index 167ed4ff0b83b67c03b38d5b90eb7278804cfc01..1b266fd4bd03dec8e947ce7a4116e2cdf16ad6b7 100644 (file)
--- a/doc/html/man/curs_mouse.3x.html
+++ b/doc/html/man/curs_mouse.3x.html
@@ -28,19 +28,19 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_mouse.3x,v 1.89 2024/02/17 21:43:03 tom Exp @
+  * @Id: curs_mouse.3x,v 1.99 2024/05/11 20:39:53 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_mouse 3x 2024-02-17 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_mouse 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
 <link rel="author" href="mailto:bug-ncurses@gnu.org">
 
 </HEAD>
 <BODY>
 <link rel="author" href="mailto:bug-ncurses@gnu.org">
 
 </HEAD>
 <BODY>
-<H1 class="no-header">curs_mouse 3x 2024-02-17 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_mouse 3x 2024-05-11 ncurses 6.5 Library calls</H1>
 <PRE>
 <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>
 
 <PRE>
 <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>
 
@@ -65,11 +65,11 @@
 
        <STRONG>bool</STRONG> <STRONG>has_mouse(void);</STRONG>
 
 
        <STRONG>bool</STRONG> <STRONG>has_mouse(void);</STRONG>
 
+       <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>
+
        <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
        <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
 
        <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
        <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
 
-       <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>
-
        <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>
 
        <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>
        <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>
 
        <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>
@@ -85,6 +85,16 @@
        <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> input stream.
 
 
        <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> input stream.
 
 
+</PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>
+       The <STRONG>has_mouse</STRONG> function returns  <STRONG>TRUE</STRONG>  if  the  mouse  driver  has  been
+       successfully initialized, and <STRONG>FALSE</STRONG> otherwise.
+
+       Mouse  events  are  ignored  when input is in cooked mode, and cause an
+       error beep when cooked mode  is  being  simulated  in  a  window  by  a
+       function  such  as  <STRONG>getstr</STRONG>  that  expects  a  linefeed  for  input-loop
+       termination.
+
+
 </PRE><H3><a name="h3-mousemask">mousemask</a></H3><PRE>
        To make mouse events visible, use the <STRONG>mousemask</STRONG>  function.   This  sets
        the  mouse  events  to  be  reported.   By default, no mouse events are
 </PRE><H3><a name="h3-mousemask">mousemask</a></H3><PRE>
        To make mouse events visible, use the <STRONG>mousemask</STRONG>  function.   This  sets
        the  mouse  events  to  be  reported.   By default, no mouse events are
@@ -99,7 +109,7 @@
        <STRONG>o</STRONG>   If <EM>oldmask</EM> is non-<STRONG>NULL</STRONG>, this function fills the indicated  location
            with the previous value of the current screen's mouse event mask.
 
        <STRONG>o</STRONG>   If <EM>oldmask</EM> is non-<STRONG>NULL</STRONG>, this function fills the indicated  location
            with the previous value of the current screen's mouse event mask.
 
-       As  a  side  effect,  setting  a  zero mousemask may turn off the mouse
+       As  a  side  effect,  setting  a zero mouse mask may turn off the mouse
        pointer; setting a nonzero mask may turn it on.  Whether  this  happens
        is device-dependent.
 
        pointer; setting a nonzero mask may turn it on.  Whether  this  happens
        is device-dependent.
 
@@ -112,7 +122,6 @@
        <STRONG>BUTTON1_PRESSED</STRONG>          mouse button 1 down
        <STRONG>BUTTON1_RELEASED</STRONG>         mouse button 1 up
        <STRONG>BUTTON1_CLICKED</STRONG>          mouse button 1 clicked
        <STRONG>BUTTON1_PRESSED</STRONG>          mouse button 1 down
        <STRONG>BUTTON1_RELEASED</STRONG>         mouse button 1 up
        <STRONG>BUTTON1_CLICKED</STRONG>          mouse button 1 clicked
-
        <STRONG>BUTTON1_DOUBLE_CLICKED</STRONG>   mouse button 1 double clicked
        <STRONG>BUTTON1_TRIPLE_CLICKED</STRONG>   mouse button 1 triple clicked
        ------------------------------------------------------------------------
        <STRONG>BUTTON1_DOUBLE_CLICKED</STRONG>   mouse button 1 double clicked
        <STRONG>BUTTON1_TRIPLE_CLICKED</STRONG>   mouse button 1 triple clicked
        ------------------------------------------------------------------------
@@ -184,7 +193,7 @@
        or  vice  versa.   The  resulting  <STRONG>stdscr</STRONG>-relative  coordinates are not
        always identical to screen coordinates due to the mechanism to  reserve
        lines  on  top  or  bottom  of  the  screen for other purposes (see the
        or  vice  versa.   The  resulting  <STRONG>stdscr</STRONG>-relative  coordinates are not
        always identical to screen coordinates due to the mechanism to  reserve
        lines  on  top  or  bottom  of  the  screen for other purposes (see the
-       <STRONG>ripoffline</STRONG> and <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> calls, for example).
+       <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).
 
        <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
            reference  the  coordinates  of  a  location inside the window <EM>win</EM>.
 
        <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
            reference  the  coordinates  of  a  location inside the window <EM>win</EM>.
@@ -215,9 +224,11 @@
 </PRE><H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE>
        The  <STRONG>mouseinterval</STRONG>  function  sets  the maximum time (in thousands of a
        second) that can elapse between press and release events for them to be
 </PRE><H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE>
        The  <STRONG>mouseinterval</STRONG>  function  sets  the maximum time (in thousands of a
        second) that can elapse between press and release events for them to be
-       resolved as a click.
+       resolved  as  a <EM>click</EM>.  An application might interpret button press and
+       release events separated by more than the mouse  interval  as  a  "long
+       press", or, with motion, as a "drag".
 
 
-       Calling  <STRONG>mouseinterval(0)</STRONG>  disables  click  resolution.   When  ncurses
+       Calling  <STRONG>mouseinterval(0)</STRONG>  disables  click  resolution.   When  <EM>ncurses</EM>
        detects a mouse event, it awaits further  input  activity  up  to  this
        interval,  and  then  checks  for a subsequent mouse event which can be
        combined with the first event.  If the timeout  expires  without  input
        detects a mouse event, it awaits further  input  activity  up  to  this
        interval,  and  then  checks  for a subsequent mouse event which can be
        combined with the first event.  If the timeout  expires  without  input
@@ -232,16 +243,6 @@
        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.
 
 
        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.
 
 
-</PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>
-       The  <STRONG>has_mouse</STRONG>  function  returns  <STRONG>TRUE</STRONG>  if  the  mouse driver has been
-       successfully initialized, and <STRONG>FALSE</STRONG> otherwise.
-
-       Mouse events are ignored when input is in cooked  mode,  and  cause  an
-       error  beep  when  cooked  mode  is  being  simulated  in a window by a
-       function  such  as  <STRONG>getstr</STRONG>  that  expects  a  linefeed  for  input-loop
-       termination.
-
-
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
        <STRONG>has_mouse</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, and <STRONG>wmouse_trafo</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
        as noted above.
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
        <STRONG>has_mouse</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, and <STRONG>wmouse_trafo</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
        as noted above.
@@ -271,7 +272,7 @@
        The  order  of  the  <STRONG>MEVENT</STRONG>  structure  members  is   not   guaranteed.
        Additional fields may be added to the structure in the future.
 
        The  order  of  the  <STRONG>MEVENT</STRONG>  structure  members  is   not   guaranteed.
        Additional fields may be added to the structure in the future.
 
-       Under  <EM>ncurses,</EM> these calls are implemented using either <EM>xterm</EM>'s built-
+       Under  <EM>ncurses</EM>, these calls are implemented using either <EM>xterm</EM>'s built-
        in mouse-tracking API or platform-specific drivers including
 
           <STRONG>o</STRONG>   Alessandro Rubini's gpm server
        in mouse-tracking API or platform-specific drivers including
 
           <STRONG>o</STRONG>   Alessandro Rubini's gpm server
@@ -299,7 +300,7 @@
        or with 3D-mice/trackballs/power gloves.
 
        The <STRONG>ALL_MOUSE_EVENTS</STRONG>  class  does  not  include  <STRONG>REPORT_MOUSE_POSITION</STRONG>.
        or with 3D-mice/trackballs/power gloves.
 
        The <STRONG>ALL_MOUSE_EVENTS</STRONG>  class  does  not  include  <STRONG>REPORT_MOUSE_POSITION</STRONG>.
-       They  are  distinct.   For example, in <EM>xterm,</EM> wheel/scrolling mice send
+       They  are  distinct.   For example, in <EM>xterm</EM>, wheel/scrolling mice send
        position reports as a sequence of presses of buttons  4  or  5  without
        matching button-releases.
 
        position reports as a sequence of presses of buttons  4  or  5  without
        matching button-releases.
 
@@ -356,13 +357,13 @@
            capability.
 
            Those  features  required a terminal program that had been modified
            capability.
 
            Those  features  required a terminal program that had been modified
-           to work with SVr4 <EM>curses.</EM>  They were not part of the X Consortium's
-           <EM>xterm.</EM>
+           to work with SVr4 <EM>curses</EM>.  They were not part of the X Consortium's
+           <EM>xterm</EM>.
 
        When  developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995,
        Eric Raymond was uninterested in using the same interface  due  to  its
        lack of documentation.  Later, in 1998, Mark Hesseling provided support
 
        When  developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995,
        Eric Raymond was uninterested in using the same interface  due  to  its
        lack of documentation.  Later, in 1998, Mark Hesseling provided support
-       in <EM>PDCurses</EM> 2.3 using the SVr4 interface.  <EM>PDCurses,</EM> however, does  not
+       in <EM>PDCurses</EM> 2.3 using the SVr4 interface.  <EM>PDCurses</EM>, however, does  not
        use  video  terminals,  making  it  unnecessary  to  be concerned about
        compatibility with the escape sequences.
 
        use  video  terminals,  making  it  unnecessary  to  be concerned about
        compatibility with the escape sequences.
 
@@ -372,12 +373,12 @@
        been  enabled  by  <STRONG>mousemask</STRONG>.  Instead, the <EM>xterm</EM> mouse report sequence
        appears in the string read.
 
        been  enabled  by  <STRONG>mousemask</STRONG>.  Instead, the <EM>xterm</EM> mouse report sequence
        appears in the string read.
 
-       Mouse event reports from <EM>xterm</EM> are not detected correctly in  a  window
-       with  keypad application mode disabled, since they are interpreted as a
-       variety of function key.  Set the terminal's <EM>terminfo</EM> capability  <STRONG>kmous</STRONG>
-       to  "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse clicks).
-       Other values of <STRONG>kmous</STRONG> are permitted under the same assumption, that is,
-       the report begins with that sequence.
+       An <EM>ncurses</EM> window must enable <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>  to  correctly  receive  mouse
+       event  reports  from  <EM>xterm</EM>  since they are encoded like function keys.
+       Set the terminal's <EM>terminfo</EM> capability <STRONG>kmous</STRONG> to "\E[M"  (the  beginning
+       of  the  response  from <EM>xterm</EM> for mouse clicks).  Other values of <STRONG>kmous</STRONG>
+       are permitted under the same assumption, that  is,  the  report  begins
+       with that sequence.
 
        Because there are no standard response sequences that serve to identify
        terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that  if
 
        Because there are no standard response sequences that serve to identify
        terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that  if
@@ -393,7 +394,7 @@
 
 
 
 
 
 
-ncurses 6.4                       2024-02-17                    <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
+ncurses 6.5                       2024-05-11                    <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
 </PRE>
 <div class="nav">
 <ul>
 </PRE>
 <div class="nav">
 <ul>
@@ -401,6 +402,7 @@ ncurses 6.4                       2024-02-17                    <STRONG><A HREF=
 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
+<li><a href="#h3-has_mouse">has_mouse</a></li>
 <li><a href="#h3-mousemask">mousemask</a></li>
 <li><a href="#h3-Mouse-Events">Mouse Events</a></li>
 <li><a href="#h3-getmouse">getmouse</a></li>
 <li><a href="#h3-mousemask">mousemask</a></li>
 <li><a href="#h3-Mouse-Events">Mouse Events</a></li>
 <li><a href="#h3-getmouse">getmouse</a></li>
@@ -409,7 +411,6 @@ ncurses 6.4                       2024-02-17                    <STRONG><A HREF=
 <li><a href="#h3-wmouse_trafo">wmouse_trafo</a></li>
 <li><a href="#h3-mouse_trafo">mouse_trafo</a></li>
 <li><a href="#h3-mouseinterval">mouseinterval</a></li>
 <li><a href="#h3-wmouse_trafo">wmouse_trafo</a></li>
 <li><a href="#h3-mouse_trafo">mouse_trafo</a></li>
 <li><a href="#h3-mouseinterval">mouseinterval</a></li>
-<li><a href="#h3-has_mouse">has_mouse</a></li>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
ncurses, with patches starting at ncurses-5.6; new users should use https://github.com/ThomasDickey/ncurses-snapshots/