ncurses 5.9 - patch 20131221
[ncurses.git] / doc / html / man / curs_mouse.3x.html
index 522c1a7c4735dc6a0bf717830050702d24d34fb5..72382d87d4ee5c660d1aa173da3bc1dfc79dca0f 100644 (file)
@@ -1,8 +1,8 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <!-- 
   * t
   ****************************************************************************
-  * Copyright (c) 1998-2003,2005 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2010,2013 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
@@ -28,7 +28,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_mouse.3x,v 1.28 2005/05/15 16:18:19 tom Exp @
+  * @Id: curs_mouse.3x,v 1.39 2013/06/22 18:09:42 tom Exp @
 -->
 <HTML>
 <HEAD>
@@ -48,9 +48,9 @@
 
 </PRE>
 <H2>NAME</H2><PRE>
-       <STRONG>getmouse</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>,
-       <STRONG>wmouse_trafo</STRONG>, <STRONG>mouseinterval</STRONG> - mouse interface through
-       curses
+       <STRONG>has_mouse</STRONG>, <STRONG>getmouse</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>wenclose</STRONG>,
+       <STRONG>mouse_trafo</STRONG>, <STRONG>wmouse_trafo</STRONG>, <STRONG>mouseinterval</STRONG> - mouse interface
+       through curses
 
 
 </PRE>
 
        <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG>
 
-       typedef struct
-       {
-           short id;         <EM>/*</EM> <EM>ID</EM> <EM>to</EM> <EM>distinguish</EM> <EM>multiple</EM> <EM>devices</EM> <EM>*/</EM>
+       <STRONG>typedef</STRONG> <STRONG>struct</STRONG> <STRONG>{</STRONG>
+           <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>
            <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG>      <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM>
            <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG>   <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM>
-       <STRONG>}</STRONG>
-       <STRONG>MEVENT;</STRONG>
+       <STRONG>}</STRONG> <STRONG>MEVENT;</STRONG>
+
+       <STRONG>bool</STRONG> <STRONG>has_mouse(void);</STRONG>
        <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
        <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
        <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <STRONG>newmask,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*oldmask);</STRONG>
@@ -97,7 +97,6 @@
 
        Here are the mouse event type masks which may be defined:
 
-
        <EM>Name</EM>                     <EM>Description</EM>
        ---------------------------------------------------------------------
        BUTTON1_PRESSED          mouse button 1 down
        BUTTON2_DOUBLE_CLICKED   mouse button 2 double clicked
        BUTTON2_TRIPLE_CLICKED   mouse button 2 triple clicked
        ---------------------------------------------------------------------
-
        BUTTON3_PRESSED          mouse button 3 down
+
        BUTTON3_RELEASED         mouse button 3 up
        BUTTON3_CLICKED          mouse button 3 clicked
        BUTTON3_DOUBLE_CLICKED   mouse button 3 double clicked
        as  y  and  x  in  the event structure coordinates will be
        screen-relative character-cell coordinates.  The  returned
        state  mask  will have exactly one bit set to indicate the
-       event type.
+       event type.  The corresponding data in the queue is marked
+       invalid.   A subsequent call to <STRONG>getmouse</STRONG> will retrieve the
+       next older item from the queue.
 
        The <STRONG>ungetmouse</STRONG> function behaves  analogously  to  <STRONG>ungetch</STRONG>.
        It  pushes a <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and as-
        screen windows enclose the location of a mouse event.
 
        The <STRONG>wmouse_trafo</STRONG> function transforms a given pair of coor-
-       dinates from stdscr-relative coordinates  to  screen-rela-
-       tive  coordinates  or  vice  versa.  Please remember, that
-       stdscr-relative coordinates are not  always  identical  to
-       screen-relative  coordinates  due  to the mechanism to re-
-       serve lines on top or bottom of the screen for other  pur-
-       poses  (ripoff()  call,  see also slk_...  functions).  If
-       the parameter <STRONG>to_screen</STRONG> is <STRONG>TRUE</STRONG>, the pointers <STRONG>pY,</STRONG> <STRONG>pX</STRONG>  must
-       reference  the coordinates of a location inside the window
-       <STRONG>win</STRONG>.  They are converted  to  screen-relative  coordinates
-       and  returned through the pointers.  If the conversion was
-       successful, the function returns <STRONG>TRUE</STRONG>.  If one of the  pa-
-       rameters  was  NULL or the location is not inside the win-
-       dow, <STRONG>FALSE</STRONG> is returned.  If <STRONG>to_screen</STRONG> is <STRONG>FALSE</STRONG>, the point-
-       ers  <STRONG>pY,</STRONG>  <STRONG>pX</STRONG>  must  reference screen-relative coordinates.
-       They are converted to stdscr-relative coordinates  if  the
-       window <STRONG>win</STRONG> encloses this point.  In this case the function
-       returns <STRONG>TRUE</STRONG>.  If one of the parameters  is  NULL  or  the
-       point is not inside the window, <STRONG>FALSE</STRONG> is returned.  Please
-       notice, that the referenced coordinates are only  replaced
-       by  the  converted  coordinates  if the transformation was
-       successful.
+       dinates from stdscr-relative  coordinates  to  coordinates
+       relative to the given window or vice versa.  Please remem-
+       ber, that stdscr-relative coordinates are not always iden-
+       tical  to window-relative 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>slk_init</STRONG> calls, for ex-
+       ample).  If the parameter <STRONG>to_screen</STRONG> is <STRONG>TRUE</STRONG>, the  pointers
+       <STRONG>pY,</STRONG> <STRONG>pX</STRONG> must reference the coordinates of a location inside
+       the window <STRONG>win</STRONG>.  They are converted to window-relative co-
+       ordinates  and returned through the pointers.  If the con-
+       version was successful, the function returns <STRONG>TRUE</STRONG>.  If one
+       of  the  parameters was NULL or the location is not inside
+       the window, <STRONG>FALSE</STRONG> is returned.  If <STRONG>to_screen</STRONG> is <STRONG>FALSE</STRONG>, the
+       pointers  <STRONG>pY,</STRONG>  <STRONG>pX</STRONG>  must  reference window-relative coordi-
+       nates.  They are converted to stdscr-relative  coordinates
+       if  the  window <STRONG>win</STRONG> encloses this point.  In this case the
+       function returns <STRONG>TRUE</STRONG>.  If one of the parameters  is  NULL
+       or  the point is not inside the window, <STRONG>FALSE</STRONG> is returned.
+       Please notice, that the referenced  coordinates  are  only
+       replaced  by  the converted coordinates if the transforma-
+       tion was successful.
+
+       The <STRONG>mouse_trafo</STRONG> function performs the same translation  as
+       <STRONG>wmouse_trafo</STRONG>, using stdscr for <STRONG>win</STRONG>.
 
        The <STRONG>mouseinterval</STRONG> function sets the maximum time (in thou-
-       sands  of  a second) that can elapse between press and re-
-       lease events for them to be recognized as  a  click.   Use
-       <STRONG>mouseinterval(0)</STRONG>  to disable click resolution.  This func-
+       sands of a second) that can elapse between press  and  re-
+       lease  events  for  them to be recognized as a click.  Use
+       <STRONG>mouseinterval(0)</STRONG> to disable click resolution.  This  func-
        tion returns the previous interval value.  Use <STRONG>mouseinter-</STRONG>
-       <STRONG>val(-1)</STRONG>  to  obtain the interval without altering it.  The
+       <STRONG>val(-1)</STRONG> to obtain the interval without altering  it.   The
        default is one sixth of a second.
 
+       The  <STRONG>has_mouse</STRONG>  function  returns TRUE if the mouse driver
+       has been successfully initialized.
+
        Note that mouse events will be ignored when  input  is  in
        cooked mode, and will cause an error beep when cooked mode
        is being simulated in a window by a function such as  <STRONG>get-</STRONG>
 
               <STRONG>getmouse</STRONG>
                    returns an error.  If no mouse driver was ini-
-                   tialized, or if the mask parameter is zero,
+                   tialized, or if the mask parameter is zero, it
+                   also returns an error if no more events remain
+                   in the queue.
 
               <STRONG>ungetmouse</STRONG>
                    returns an error if the FIFO is full.
        Under <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, these calls are implemented  using  ei-
        ther  xterm's built-in mouse-tracking API or platform-spe-
        cific drivers including
-              Alessandro Rubini's gpm server.
+              Alessandro Rubini's gpm server
               FreeBSD sysmouse
               OS/2 EMX
        If you  are  using  an  unsupported  configuration,  mouse
-       events will not be visible to <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> (and the <STRONG>wmouse-</STRONG>
+       events  will not be visible to <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> (and the <STRONG>mouse-</STRONG>
        <STRONG>mask</STRONG> function will always return <STRONG>0</STRONG>).
 
        If the terminfo entry contains a <STRONG>XM</STRONG> string, this  is  used
 </PRE>
 <H2>BUGS</H2><PRE>
        Mouse events under xterm will not in fact be ignored  dur-
-       ing  cooked mode, if they have been enabled by <STRONG>wmousemask</STRONG>.
+       ing  cooked  mode, if they have been enabled by <STRONG>mousemask</STRONG>.
        Instead, the xterm mouse report sequence  will  appear  in
        the string read.
 
        Mouse events under xterm will not be detected correctly in
        a window with its keypad bit off, since  they  are  inter-
        preted  as  a  variety of function key.  Your terminfo de-
-       scription must have <STRONG>kmous</STRONG> set to "\E[M" (the beginning  of
-       the response from xterm for mouse clicks).
+       scription should have <STRONG>kmous</STRONG> set to "\E[M"  (the  beginning
+       of  the response from xterm for mouse clicks).  Other val-
+       ues for <STRONG>kmous</STRONG> are permitted, but under  the  same  assump-
+       tion, i.e., it is the beginning of the response.
 
        Because  there  are  no  standard  terminal responses that
        would serve to identify terminals which support the  xterm
 
 </PRE>
 <H2>SEE ALSO</H2><PRE>
-       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
+       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,   <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>,   <STRONG>curs_vari-</STRONG>
+       <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>.