ncurses 5.1
[ncurses.git] / doc / html / man / curs_mouse.3x.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        <B>getmouse</B>,  <B>ungetmouse</B>,  <B>mousemask</B>,  <B>wenclose</B>, <B>mouse_trafo</B>,
9        <B>wmouse_trafo</B>,  <B>mouseinterval</B>  -  mouse  interface  through
10        curses
11
12
13 </PRE>
14 <H2>SYNOPSIS</H2><PRE>
15        <B>#include</B> <B>&lt;curses.h&gt;</B>
16
17        <B>typedef</B> <B>unsigned</B> <B>long</B> <B>mmask_t;</B>
18
19        <B>typedef</B> <B>struct</B>
20        <B>{</B>
21            <B>short</B> <B>id;</B>         <I>/*</I> <I>ID</I> <I>to</I> <I>distinguish</I> <I>multiple</I> <I>devices</I> <I>*/</I>
22            <B>int</B> <B>x,</B> <B>y,</B> <B>z;</B>      <I>/*</I> <I>event</I> <I>coordinates</I> <I>*/</I>
23            <B>mmask_t</B> <B>bstate;</B>   <I>/*</I> <I>button</I> <I>state</I> <I>bits</I> <I>*/</I>
24        <B>}</B>
25        <B>MEVENT;</B>
26        <B>int</B> <B>getmouse(MEVENT</B> <B>*event);</B>
27        <B>int</B> <B>ungetmouse(MEVENT</B> <B>*event);</B>
28        <B>mmask_t</B> <B>mousemask(mmask_t</B> <B>newmask,</B> <B>mmask_t</B> <B>*oldmask);</B>
29        <B>bool</B> <B>wenclose(WINDOW</B> <B>*win,</B> <B>int</B> <B>y,</B> <B>int</B> <B>x);</B>
30        <B>bool</B> <B>mouse_trafo(int*</B> <B>pY,</B> <B>int*</B> <B>pX,</B> <B>bool</B> <B>to_screen);</B>
31        <B>bool</B> <B>wmouse_trafo(const</B> <B>WINDOW*</B> <B>win,</B> <B>int*</B> <B>pY,</B> <B>int*</B> <B>pX,</B>
32             <B>bool</B> <B>to_screen);</B>
33        <B>int</B> <B>mouseinterval(int</B> <B>erval);</B>
34
35
36 </PRE>
37 <H2>DESCRIPTION</H2><PRE>
38        These  functions provide an interface to mouse events from
39        <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>.  Mouse events are  represented  by  <B>KEY_MOUSE</B>
40        pseudo-key values in the <B>wgetch</B> input stream.
41
42        To  make mouse events visible, use the <B>mousemask</B> function.
43        This will  set  the  mouse  events  to  be  reported.   By
44        default,  no mouse events are reported.  The function will
45        return a mask to indicate which  of  the  specified  mouse
46        events  can be reported; on complete failure it returns 0.
47        If oldmask is non-NULL, this function fills the  indicated
48        location  with  the  previous  value of the given window's
49        mouse event mask.
50
51        As a side effect, setting a zero mousemask  may  turn  off
52        the  mouse pointer; setting a nonzero mask may turn it on.
53        Whether this happens is device-dependent.
54
55        Here are the mouse event type masks:
56
57        <I>Name</I>                     <I>Description</I>
58        ---------------------------------------------------------------------
59        BUTTON1_PRESSED          mouse button 1 down
60        BUTTON1_RELEASED         mouse button 1 up
61        BUTTON1_CLICKED          mouse button 1 clicked
62        BUTTON1_DOUBLE_CLICKED   mouse button 1 double clicked
63        BUTTON1_TRIPLE_CLICKED   mouse button 1 triple clicked
64
65        BUTTON2_PRESSED          mouse button 2 down
66        BUTTON2_RELEASED         mouse button 2 up
67        BUTTON2_CLICKED          mouse button 2 clicked
68        BUTTON2_DOUBLE_CLICKED   mouse button 2 double clicked
69        BUTTON2_TRIPLE_CLICKED   mouse button 2 triple clicked
70        BUTTON3_PRESSED          mouse button 3 down
71        BUTTON3_RELEASED         mouse button 3 up
72        BUTTON3_CLICKED          mouse button 3 clicked
73        BUTTON3_DOUBLE_CLICKED   mouse button 3 double clicked
74        BUTTON3_TRIPLE_CLICKED   mouse button 3 triple clicked
75        BUTTON4_PRESSED          mouse button 4 down
76        BUTTON4_RELEASED         mouse button 4 up
77        BUTTON4_CLICKED          mouse button 4 clicked
78        BUTTON4_DOUBLE_CLICKED   mouse button 4 double clicked
79        BUTTON4_TRIPLE_CLICKED   mouse button 4 triple clicked
80        BUTTON_SHIFT             shift was down during button state change
81        BUTTON_CTRL              control was down during button state change
82        BUTTON_ALT               alt was down during button state change
83        ALL_MOUSE_EVENTS         report all button state changes
84        REPORT_MOUSE_POSITION    report mouse movement
85
86        Once a class of mouse events have been made visible  in  a
87        window,  calling  the  <B>wgetch</B>  function on that window may
88        return <B>KEY_MOUSE</B> as an indicator that a  mouse  event  has
89        been queued.  To read the event data and pop the event off
90        the queue, call <B>getmouse</B>.  This function will return <B>OK</B> if
91        a mouse event is actually visible in the given window, <B>ERR</B>
92        otherwise.  When <B>getmouse</B> returns <B>OK</B>, the  data  deposited
93        as  y  and  x  in  the event structure coordinates will be
94        screen-relative character-cell coordinates.  The  returned
95        state  mask  will have exactly one bit set to indicate the
96        event type.
97
98        The <B>ungetmouse</B> function behaves  analogously  to  <B>ungetch</B>.
99        It  pushes  a  <B>KEY_MOUSE</B>  event  onto the input queue, and
100        associates with  that  event  the  given  state  data  and
101        screen-relative character-cell coordinates.
102
103        The  <B>wenclose</B>  function  tests  whether  a  given  pair of
104        screen-relative character-cell coordinates is enclosed  by
105        a  given  window, returning TRUE if it is and FALSE other-
106        wise.  It is useful for determining  what  subset  of  the
107        screen windows enclose the location of a mouse event.
108
109        The <B>wmouse_trafo</B> function transforms a given pair of coor-
110        dinates from stdscr-relative coordinates  to  screen-rela-
111        tive  coordinates  or  vice  versa.  Please remember, that
112        stdscr-relative coordinates are not  always  identical  to
113        screen-relative   coordinates  due  to  the  mechanism  to
114        reserve lines on top or bottom of  the  screen  for  other
115        purposes  (ripoff() call, see also slk_...  functions). If
116        the parameter <B>to_screen</B> is <B>TRUE</B>, the pointers <B>pY,</B> <B>pX</B>  must
117        reference  the coordinates of a location inside the window
118        <B>win</B>. They are converted to screen-relative coordinates and
119        returned  through the pointers. If the conversion was suc-
120        cessful, the function returns <B>TRUE</B>. If one of the  parame-
121        ters  was  NULL  or the location is not inside the window,
122        <B>FALSE</B> is returned. If <B>to_screen</B> is <B>FALSE</B>, the pointers <B>pY,</B>
123        <B>pX</B>  must  reference  screen-relative coordinates. They are
124        converted to stdscr-relative coordinates if the window <B>win</B>
125        encloses  this  point.  In  this case the function returns
126        <B>TRUE</B>. If one of the parameters is NULL or the point is not
127        inside  the window, <B>FALSE</B> is returned. Please notice, that
128        the referenced coordinates are only replaced by  the  con-
129        verted coordinates if the transformation was successful.
130
131        The <B>mouseinterval</B> function sets the maximum time (in thou-
132        sands of a second)  that  can  elapse  between  press  and
133        release  events  in  order  for them to be recognized as a
134        click.  This function returns the previous interval value.
135        The default is one fifth of a second.
136
137        Note  that  mouse  events will be ignored when input is in
138        cooked mode, and will cause an error beep when cooked mode
139        is  being simulated in a window by a function such as <B>get-</B>
140        <B>str</B> that expects a linefeed for input-loop termination.
141
142
143
144 </PRE>
145 <H2>RETURN VALUE</H2><PRE>
146        <B>getmouse</B>, <B>ungetmouse</B> and <B>mouseinterval</B> return the  integer
147        <B>ERR</B>  upon failure or <B>OK</B> upon successful completion. <B>mouse-</B>
148        <B>mask</B> returns the mask of reportable events.  <B>wenclose</B>  and
149        <B>wmouse_trafo</B> are boolean functions returning <B>TRUE</B> or <B>FALSE</B>
150        depending on their test result.
151
152
153 </PRE>
154 <H2>PORTABILITY</H2><PRE>
155        These calls were designed for  <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>,  and  are  not
156        found in SVr4 curses, 4.4BSD curses, or any other previous
157        version of curses.
158
159        The feature macro <B>NCURSES_MOUSE_VERSION</B> is provided so the
160        preprocessor  can  be  used to test whether these features
161        are present  (its  value  is  1).   If  the  interface  is
162        changed, the value of <B>NCURSES_MOUSE_VERSION</B> will be incre-
163        mented.
164
165        The order of the <B>MEVENT</B> structure members is  not  guaran-
166        teed.   Additional fields may be added to the structure in
167        the future.
168
169        Under  <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>,  these  calls  are  implemented  using
170        either  xterm's  built-in mouse-tracking API or Alessandro
171        Rubini's gpm server.  If you  are  using  something  other
172        than  xterm  and  there  is  no gpm daemon running on your
173        machine, mouse events will not be visible  to  <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>
174        (and the <B>wmousemask</B> function will always return <B>0</B>).
175
176        The z member in the event structure is not presently used.
177        It is intended for use with touch screens  (which  may  be
178        pressure-sensitive)   or   with   3D-mice/trackballs/power
179        gloves.
180
181
182 </PRE>
183 <H2>BUGS</H2><PRE>
184        Mouse events under xterm will not in fact be ignored  dur-
185        ing  cooked mode, if they have been enabled by <B>wmousemask</B>.
186        Instead, the xterm mouse report sequence  will  appear  in
187        the string read.
188
189        Mouse events under xterm will not be detected correctly in
190        a window with its keypad bit off, since  they  are  inter-
191        preted  as  a  variety  of  function  key.   Your terminfo
192        description must have <B>kmous</B> set to "\E[M"  (the  beginning
193        of the response from xterm for mouse clicks).
194
195        Because  there  are  no  standard  terminal responses that
196        would serve to identify terminals which support the  xterm
197        mouse  protocol,  <B>ncurses</B>  assumes  that  if your $DISPLAY
198        environment variable is set, and <B>kmous</B> is defined  in  the
199        terminal  description,  then  the  terminal may send mouse
200        events.
201
202
203 </PRE>
204 <H2>SEE ALSO</H2><PRE>
205        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>.
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235 </PRE>
236 <HR>
237 <ADDRESS>
238 Man(1) output converted with
239 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
240 </ADDRESS>
241 </BODY>
242 </HTML>