1curs_mouse(3X) curs_mouse(3X)
2
6 has_mouse, getmouse, ungetmouse, mousemask, wenclose, mouse_trafo,
7 wmouse_trafo, mouseinterval - mouse interface through curses
8
10 #include <curses.h>
11 typedef unsigned long mmask_t;
13 typedef struct {
15 short id; /* ID to distinguish multiple devices */
16 int x, y, z; /* event coordinates */
17 mmask_t bstate; /* button state bits */
18 } MEVENT;
19 bool has_mouse(void);
21 int getmouse(MEVENT *event);
23 int ungetmouse(MEVENT *event);
24 mmask_t mousemask(mmask_t newmask, mmask_t *oldmask);
26 bool wenclose(const WINDOW *win, int y, int x);
28 bool mouse_trafo(int* pY, int* pX, bool to_screen);
30 bool wmouse_trafo(const WINDOW* win,
31 int* pY, int* pX, bool to_screen);
32 int mouseinterval(int erval);
34
36 These functions provide an interface to mouse events from ncurses(3X).
37 Mouse events are represented by KEY_MOUSE pseudo-key values in the
38 wgetch(3X) input stream.
39 mousemask
41 To make mouse events visible, use the mousemask function. This sets
42 the mouse events to be reported. By default, no mouse events are re‐
43 ported.
44 • The function returns an updated copy of newmask to indicate which
46 of the specified mouse events can be reported.
47 If the screen has not been initialized, or if the terminal does not
49 support mouse-events, this function returns 0.
50 • If oldmask is non-NULL, this function fills the indicated location
52 with the previous value of the current screen's mouse event mask.
53 As a side effect, setting a zero mousemask may turn off the mouse
55 pointer; setting a nonzero mask may turn it on. Whether this happens
56 is device-dependent.
57 Mouse events
59 Here are the mouse event type masks which may be defined:
60 Name Description
62 ─────────────────────────────────────────────────────────────────────
63 BUTTON1_PRESSED mouse button 1 down
64 BUTTON1_RELEASED mouse button 1 up
65 BUTTON1_CLICKED mouse button 1 clicked
66 BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
68 BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
69 ─────────────────────────────────────────────────────────────────────
70 BUTTON2_PRESSED mouse button 2 down
71 BUTTON2_RELEASED mouse button 2 up
72 BUTTON2_CLICKED mouse button 2 clicked
73 BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
74 BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
75 ─────────────────────────────────────────────────────────────────────
76 BUTTON3_PRESSED mouse button 3 down
77 BUTTON3_RELEASED mouse button 3 up
78 BUTTON3_CLICKED mouse button 3 clicked
79 BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
80 BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
81 ─────────────────────────────────────────────────────────────────────
82 BUTTON4_PRESSED mouse button 4 down
83 BUTTON4_RELEASED mouse button 4 up
84 BUTTON4_CLICKED mouse button 4 clicked
85 BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
86 BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
87 ─────────────────────────────────────────────────────────────────────
88 BUTTON5_PRESSED mouse button 5 down
89 BUTTON5_RELEASED mouse button 5 up
90 BUTTON5_CLICKED mouse button 5 clicked
91 BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked
92 BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked
93 ─────────────────────────────────────────────────────────────────────
94 BUTTON_SHIFT shift was down during button state change
95 BUTTON_CTRL control was down during button state change
96 BUTTON_ALT alt was down during button state change
97 ALL_MOUSE_EVENTS report all button state changes
98 REPORT_MOUSE_POSITION report mouse movement
99 ─────────────────────────────────────────────────────────────────────
100 getmouse
102 Once a class of mouse events has been made visible in a window, calling
103 the wgetch function on that window may return KEY_MOUSE as an indicator
104 that a mouse event has been queued. To read the event data and pop the
105 event off the queue, call getmouse. This function will return OK if a
106 mouse event is actually visible in the given window, ERR otherwise.
107 When getmouse returns OK, the data deposited as y and x in the event
108 structure coordinates will be screen-relative character-cell coordi‐
109 nates. The returned state mask will have exactly one bit set to indi‐
110 cate the event type. The corresponding data in the queue is marked in‐
111 valid. A subsequent call to getmouse will retrieve the next older item
112 from the queue.
113 ungetmouse
115 The ungetmouse function behaves analogously to ungetch. It pushes a
116 KEY_MOUSE event onto the input queue, and associates with that event
117 the given state data and screen-relative character-cell coordinates.
118 wenclose
120 The wenclose function tests whether a given pair of screen-relative
121 character-cell coordinates is enclosed by a given window, returning
122 TRUE if it is and FALSE otherwise. It is useful for determining what
123 subset of the screen windows enclose the location of a mouse event.
124 wmouse_trafo
126 The wmouse_trafo function transforms a given pair of coordinates from
127 stdscr-relative coordinates to coordinates relative to the given window
128 or vice versa. The resulting stdscr-relative coordinates are not al‐
129 ways identical to window-relative coordinates due to the mechanism to
130 reserve lines on top or bottom of the screen for other purposes (see
131 the ripoffline and slk_init(3X) calls, for example).
132 • If the parameter to_screen is TRUE, the pointers pY, pX must refer‐
134 ence the coordinates of a location inside the window win. They are
135 converted to window-relative coordinates and returned through the
136 pointers. If the conversion was successful, the function returns
137 TRUE.
138 • If one of the parameters was NULL or the location is not inside the
140 window, FALSE is returned.
141 • If to_screen is FALSE, the pointers pY, pX must reference window-
143 relative coordinates. They are converted to stdscr-relative coor‐
144 dinates if the window win encloses this point. In this case the
145 function returns TRUE.
146 • If one of the parameters is NULL or the point is not inside the
148 window, FALSE is returned. The referenced coordinates are only re‐
149 placed by the converted coordinates if the transformation was suc‐
150 cessful.
151 mouse_trafo
153 The mouse_trafo function performs the same translation as wmouse_trafo,
154 using stdscr for win.
155 mouseinterval
157 The mouseinterval function sets the maximum time (in thousands of a
158 second) that can elapse between press and release events for them to be
159 recognized as a click. Use mouseinterval(0) to disable click resolu‐
160 tion. This function returns the previous interval value. Use mousein‐
161 terval(-1) to obtain the interval without altering it. The default is
162 one sixth of a second.
163 has_mouse
165 The has_mouse function returns TRUE if the mouse driver has been suc‐
166 cessfully initialized.
167 Note that mouse events will be ignored when input is in cooked mode,
169 and will cause an error beep when cooked mode is being simulated in a
170 window by a function such as getstr that expects a linefeed for input-
171 loop termination.
172
174 getmouse and ungetmouse return the integer ERR upon failure or OK upon
175 successful completion:
176 getmouse
178 returns an error.
179 • If no mouse driver was initialized, or if the mask parameter is
181 zero,
182 • It returns an error if a mouse event was detected which did not
184 match the current mousemask.
185 • It also returns an error if no more events remain in the queue.
187 ungetmouse
189 returns an error if the FIFO is full.
190 mousemask returns the mask of reportable events.
192 mouseinterval returns the previous interval value, unless the terminal
194 was not initialized. In that case, it returns the maximum interval
195 value (166).
196 wenclose and wmouse_trafo are boolean functions returning TRUE or FALSE
198 depending on their test result.
199
201 These calls were designed for ncurses(3X), and are not found in SVr4
202 curses, 4.4BSD curses, or any other previous version of curses.
203 SVr4 curses had support for the mouse in a variant of xterm(1). It is
205 mentioned in a few places, but with no supporting documentation:
206 • the “libcurses” manual page lists functions for this feature which
208 are prototyped in curses.h:
209 extern int mouse_set(long int);
211 extern int mouse_on(long int);
212 extern int mouse_off(long int);
213 extern int request_mouse_pos(void);
214 extern int map_button(unsigned long);
215 extern void wmouse_position(WINDOW *, int *, int *);
216 extern unsigned long getmouse(void), getbmap(void);
217 • the “terminfo” manual page lists capabilities for the feature
219 buttons btns BT Number of buttons on the mouse
221 get_mouse getm Gm Curses should get button events
222 key_mouse kmous Km 0631, Mouse event has occurred
223 mouse_info minfo Mi Mouse status information
224 req_mouse_pos reqmp RQ Request mouse position report
225 • the interface made assumptions (as does ncurses) about the escape
227 sequences sent to and received from the terminal.
228 For instance the SVr4 curses library used the get_mouse capability
230 to tell the terminal which mouse button events it should send,
231 passing the mouse-button bit-mask to the terminal. Also, it could
232 ask the terminal where the mouse was using the req_mouse_pos capa‐
233 bility.
234 Those features required a terminal which had been modified to work
236 with curses. They were not part of the X Consortium's xterm.
237 When developing the xterm mouse support for ncurses in September 1995,
239 Eric Raymond was uninterested in using the same interface due to its
240 lack of documentation. Later, in 1998, Mark Hesseling provided support
241 in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not
242 use video terminals, making it unnecessary to be concerned about com‐
243 patibility with the escape sequences.
244 The feature macro NCURSES_MOUSE_VERSION is provided so the preprocessor
246 can be used to test whether these features are present. If the inter‐
247 face is changed, the value of NCURSES_MOUSE_VERSION will be increment‐
248 ed. These values for NCURSES_MOUSE_VERSION may be specified when con‐
249 figuring ncurses:
250 1 has definitions for reserved events. The mask uses 28 bits.
252 2 adds definitions for button 5, removes the definitions for re‐
254 served events. The mask uses 29 bits.
255 The order of the MEVENT structure members is not guaranteed. Addition‐
257 al fields may be added to the structure in the future.
258 Under ncurses(3X), these calls are implemented using either xterm's
260 built-in mouse-tracking API or platform-specific drivers including
261 • Alessandro Rubini's gpm server
263 • FreeBSD sysmouse
265 • OS/2 EMX
267 If you are using an unsupported configuration, mouse events will not be
269 visible to ncurses(3X) (and the mousemask function will always return
270 0).
271 If the terminfo entry contains a XM string, this is used in the xterm
273 mouse driver to control the way the terminal is initialized for mouse
274 operation. The default, if XM is not found, corresponds to private
275 mode 1000 of xterm:
276 \E[?1000%?%p1%{1}%=%th%el%;
278 The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
280 \E[?1006;1000%?%p1%{1}%=%th%el%;
282 The z member in the event structure is not presently used. It is in‐
284 tended for use with touch screens (which may be pressure-sensitive) or
285 with 3D-mice/trackballs/power gloves.
286 The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION.
288 They are distinct. For example, in xterm, wheel/scrolling mice send
289 position reports as a sequence of presses of buttons 4 or 5 without
290 matching button-releases.
291
293 Mouse events under xterm will not in fact be ignored during cooked
294 mode, if they have been enabled by mousemask. Instead, the xterm mouse
295 report sequence will appear in the string read.
296 Mouse events under xterm will not be detected correctly in a window
298 with its keypad bit off, since they are interpreted as a variety of
299 function key. Your terminfo description should have kmous set to
300 “\E[M” (the beginning of the response from xterm for mouse clicks).
301 Other values for kmous are permitted, but under the same assumption,
302 i.e., it is the beginning of the response.
303 Because there are no standard terminal responses that would serve to
305 identify terminals which support the xterm mouse protocol, ncurses as‐
306 sumes that if kmous is defined in the terminal description, or if the
307 terminal description's primary name or aliases contain the string
308 “xterm”, then the terminal may send mouse events. The kmous capability
309 is checked first, allowing the use of newer xterm mouse protocols such
310 as xterm's private mode 1006.
311
313 curses(3X), curs_inopts(3X), curs_kernel(3X), curs_slk(3X), curs_vari‐
314 ables(3X).
315 curs_mouse(3X)