4 <STRONG>getmouse</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>wmouse_trafo</STRONG>,
5 <STRONG>mouseinterval</STRONG> - mouse interface through curses
10 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
12 <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG>
14 <STRONG>typedef</STRONG> <STRONG>struct</STRONG>
16 <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>
17 <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG> <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM>
18 <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG> <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM>
20 <STRONG>MEVENT;</STRONG>
21 <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
22 <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
23 <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <STRONG>newmask,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*oldmask);</STRONG>
24 <STRONG>bool</STRONG> <STRONG>wenclose(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
25 <STRONG>bool</STRONG> <STRONG>wmouse_trafo(const</STRONG> <STRONG>WINDOW*</STRONG> <STRONG>win,</STRONG> <STRONG>int*</STRONG> <STRONG>pY,</STRONG> <STRONG>int*</STRONG> <STRONG>pX,</STRONG>
26 <STRONG>bool</STRONG> <STRONG>to_screen);</STRONG>
27 <STRONG>int</STRONG> <STRONG>mouseinterval(int</STRONG> <STRONG>erval);</STRONG>
31 <H2>DESCRIPTION</H2><PRE>
32 These functions provide an interface to mouse events from
33 <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>. Mouse events are represented by <STRONG>KEY_MOUSE</STRONG>
34 pseudo-key values in the <STRONG>wgetch</STRONG> input stream.
36 To make mouse events visible, use the <STRONG>mousemask</STRONG> function.
37 This will set the mouse events to be reported. By
38 default, no mouse events are reported. The function will
39 return a mask to indicate which of the specified mouse
40 events can be reported; on complete failure it returns 0.
41 If oldmask is non-NULL, this function fills the indicated
42 location with the previous value of the given window's
45 As a side effect, setting a zero mousemask may turn off
46 the mouse pointer; setting a nonzero mask may turn it on.
47 Whether this happens is device-dependent.
49 Here are the mouse event type masks:
51 l l _ _ l l. <EM>Name</EM> <EM>Description</EM> BUTTON1_PRESSED mouse
52 button 1 down BUTTON1_RELEASED mouse button 1 up
53 BUTTON1_CLICKED mouse button 1 clicked
54 BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
55 BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
56 BUTTON2_PRESSED mouse button 2 down
57 BUTTON2_RELEASED mouse button 2 up
58 BUTTON2_CLICKED mouse button 2 clicked
59 BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
60 BUTTON3_RELEASED mouse button 3 up
61 BUTTON3_CLICKED mouse button 3 clicked
62 BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
63 BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
64 BUTTON4_PRESSED mouse button 4 down
65 BUTTON4_RELEASED mouse button 4 up
66 BUTTON4_CLICKED mouse button 4 clicked
67 BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
68 BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
69 BUTTON_SHIFT shift was down during button state change
70 BUTTON_CTRL control was down during button state change
71 BUTTON_ALT alt was down during button state change
72 ALL_MOUSE_EVENTS report all button state changes
73 REPORT_MOUSE_POSITION report mouse movement
75 Once a class of mouse events have been made visible in a
76 window, calling the <STRONG>wgetch</STRONG> function on that window may
77 return <STRONG>KEY_MOUSE</STRONG> as an indicator that a mouse event has
78 been queued. To read the event data and pop the event off
79 the queue, call <STRONG>getmouse</STRONG>. This function will return <STRONG>OK</STRONG> if
80 a mouse event is actually visible in the given window, <STRONG>ERR</STRONG>
81 otherwise. When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited
82 as y and x in the event structure coordinates will be
83 screen-relative character-cell coordinates. The returned
84 state mask will have exactly one bit set to indicate the
87 The <STRONG>ungetmouse</STRONG> function behaves analogously to <STRONG>ungetch</STRONG>.
88 It pushes a <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and
89 associates with that event the given state data and
90 screen-relative character-cell coordinates.
92 The <STRONG>wenclose</STRONG> function tests whether a given pair of
93 screen-relative character-cell coordinates is enclosed by
94 a given window, returning TRUE if it is and FALSE other-
95 wise. It is useful for determining what subset of the
96 screen windows enclose the location of a mouse event.
98 The <STRONG>wmouse_trafo</STRONG> function transforms a given pair of coor-
99 dinates from stdscr-relative coordinates to screen-rela-
100 tive coordinates or vice versa. Please remember, that
101 stdscr-relative coordinates are not always identical to
102 screen-relative coordinates due to the mechanism to
103 reserve lines on top or bottom of the screen for other
104 purposes (ripoff() call, see also slk_... functions). If
105 the parameter <STRONG>to_screen</STRONG> is <STRONG>TRUE</STRONG>, the pointers <STRONG>pY,</STRONG> <STRONG>pX</STRONG> must
106 reference the coordinates of a location inside the window
107 <STRONG>win</STRONG>. They are converted to screen-relative coordinates and
108 returned through the pointers. If the conversion was suc-
109 cessful, the function returns <STRONG>TRUE</STRONG>. If one of the parame-
110 ters was NULL or the location is not inside the window,
111 <STRONG>FALSE</STRONG> is returned. If <STRONG>to_screen</STRONG> is <STRONG>FALSE</STRONG>, the pointers <STRONG>pY,</STRONG>
112 encloses this point. In this case the function returns
113 <STRONG>TRUE</STRONG>. If one of the parameters is NULL or the point is not
114 inside the window, <STRONG>FALSE</STRONG> is returned. Please notice, that
115 the referenced coordinates are only replaced by the con-
116 verted coordinates if the transformation was successful.
118 The <STRONG>mouseinterval</STRONG> function sets the maximum time (in thou-
119 sands of a second) that can elapse between press and
120 release events in order for them to be recognized as a
121 click. This function returns the previous interval value.
122 The default is one fifth of a second.
124 Note that mouse events will be ignored when input is in
125 cooked mode, and will cause an error beep when cooked mode
126 is being simulated in a window by a function such as <STRONG>get-</STRONG>
127 <STRONG>str</STRONG> that expects a linefeed for input-loop termination.
132 <H2>RETURN VALUE</H2><PRE>
133 <STRONG>getmouse</STRONG>, <STRONG>ungetmouse</STRONG> and <STRONG>mouseinterval</STRONG> return the integer
134 <STRONG>ERR</STRONG> upon failure or <STRONG>OK</STRONG> upon successful completion. <STRONG>mouse-</STRONG>
135 <STRONG>mask</STRONG> returns the mask of reportable events. <STRONG>wenclose</STRONG> and
136 <STRONG>wmouse_trafo</STRONG> are boolean functions returning <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
137 depending on their test result.
141 <H2>PORTABILITY</H2><PRE>
142 These calls were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>, and are not
143 found in SVr4 curses, 4.4BSD curses, or any other previous
146 The feature macro <STRONG>NCURSES_MOUSE_VERSION</STRONG> is provided so the
147 preprocessor can be used to test whether these features
148 are present (its value is 1). NOTE: THIS INTERFACE IS
149 EXPERIMENTAL AND IS SUBJECT TO CHANGE WITHOUT NOTICE! If
150 the interface is changed, the value of <STRONG>NCURSES_MOUSE_VER-</STRONG>
151 <STRONG>SION</STRONG> will be incremented.
153 The order of the <STRONG>MEVENT</STRONG> structure members is not guaran-
154 teed. Additional fields may be added to the structure in
157 Under <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>, these calls are implemented using
158 either xterm's built-in mouse-tracking API or Alessandro
159 Rubini's gpm server. If you are using something other
160 than xterm there is no gpm daemon running on your machine,
161 mouse events will not be visible to <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG> (and the
162 <STRONG>wmousemask</STRONG> function will always return <STRONG>0</STRONG>).
164 The z member in the event structure is not presently used.
165 It is intended for use with touch screens (which may be
166 pressure-sensitive) or with 3D-mice/trackballs/power
168 Mouse events under xterm will not in fact be ignored dur-
169 ing cooked mode, if they have been enabled by <STRONG>wmousemask</STRONG>.
170 Instead, the xterm mouse report sequence will appear in
173 Mouse events under xterm will not be detected correctly in
174 a window with its keypad bit off.
178 <H2>SEE ALSO</H2><PRE>
179 <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>.