Debian Codegraph @

upstream/debian-unstable/man3/mouse.3ncurses

raw
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
4 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
5 .\" *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
13 .\" *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
16 .\" *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
28 .\" authorization. *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: curs_mouse.3x,v 1.131 2025/11/12 01:06:36 tom Exp $
32 .TH mouse 3NCURSES 2025-11-11 "ncurses 6.6" "Library calls"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el .ds `` ""
40 .ie t .ds '' ''
41 .el .ds '' ""
42 .\}
43 .
44 .de bP
45 .ie n .IP \(bu 4
46 .el .IP \(bu 2
47 ..
48 .SH NAME
49 \fB\%has_mouse\fP,
50 \fB\%getmouse\fP,
51 \fB\%ungetmouse\fP,
52 \fB\%mousemask\fP,
53 \fB\%wenclose\fP,
54 \fB\%mouse_trafo\fP,
55 \fB\%wmouse_trafo\fP,
56 \fB\%mouseinterval\fP,
57 \fB\%mmask_t\fP,
58 \fB\%MEVENT\fP \-
59 get mouse events in \fIncurses\fR
60 .SH SYNOPSIS
61 .nf
62 \fB#include <curses.h>
63 .PP
64 \fI/* data types */
65 \fBtypedef unsigned long mmask_t;
66 .PP
67 \fBtypedef struct {
68 \fB short id; \fI/* ID to distinguish multiple devices */
69 \fB int x, y, z; \fI/* event coordinates */
70 \fB mmask_t bstate; \fI/* button state bits */
71 \fB} MEVENT;
72 .PP
73 \fI/* functions */
74 \fBbool has_mouse(void);
75 .PP
76 \fBmmask_t mousemask(mmask_t \fInew-mask\fP, mmask_t * \fIold-mask\fP);
77 .PP
78 \fBint getmouse(MEVENT * \fIevent\fP);
79 \fBint ungetmouse(MEVENT * \fIevent\fP);
80 .PP
81 \fBbool wenclose(const WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP);
82 .PP
83 \fBbool mouse_trafo(int * \fIpY\fP, int * \fIpX\fP, bool \fIto-screen\fP);
84 \fBbool wmouse_trafo(const WINDOW * \fIwin\fP,
85 \fBint * \fIpY\fB, int * \fIpX\fB, bool \fIto-screen\fB);
86 .PP
87 \fBint mouseinterval(int \fIerval\fB);\fR
88 .fi
89 .SH DESCRIPTION
90 .I \%ncurses
91 provides an interface to the mouse or other pointing device.
92 An application can register its interest in such events;
93 the library then exposes the availability of a mouse event via an
94 .IR "input character reading function" ":"
95 this is \fB\%wgetch\fP(3NCURSES) in the non-wide character
96 .I curses
97 API and \fB\%wget_wch\fP(3NCURSES) in the wide character API.
98 A queue distinct from that used for keyboard events
99 accumulates the details of mouse events.
100 The input character reading function
101 reports the
102 .B \%KEY_MOUSE
103 key code when a mouse event is available for collection.
104 A single mouse event queue serves all windows
105 associated with the screen.
106 .PP
107 The
108 .I \%MEVENT
109 structure describes a mouse event.
110 Its
111 .I y
112 and
113 .I x
114 coordinates are screen-,
115 not window-,
116 relative.
117 The
118 .I \%bstate
119 member has exactly one bit set indicating the event type.
120 .PP
121 .I \%ncurses
122 ignores mouse events when input is in canonical (\*(``cooked\*('') mode,
123 and produces an error beep when they occur
124 while the library simulates canonical mode in a window,
125 as with \fB\%getstr\fP(3NCURSES)
126 (wide-character API users: \fB\%get_wstr\fP(3NCURSES)),
127 which expects a line feed to terminate its input loop.
128 .SS has_mouse
129 The terminal type or operating system interface
130 must support the encoding of mouse events.
131 .B \%has_mouse
132 returns
133 .B TRUE
134 if
135 .IR \%ncurses 's
136 mouse driver initialized successfully,
137 and
138 .B FALSE
139 otherwise.
140 .SS mousemask
141 Use
142 .B \%mousemask
143 to select the varieties of mouse event your application wishes to
144 receive.
145 By default,
146 .I \%ncurses
147 reports no mouse events.
148 .bP
149 The function returns an updated copy of
150 .I new-mask
151 indicating which event types of interest
152 are reportable by the terminal's mouse protocol.
153 .IP
154 If the screen is not initialized,
155 or the terminal interface does not report mouse events,
156 .B \%mousemask
157 returns 0.
158 .bP
159 If
160 .I old-mask
161 is not a null pointer,
162 .B \%mousemask
163 stores the previous value
164 of the screen's mouse event mask there.
165 .PP
166 As a side effect,
167 setting a zero mouse mask may turn off the mouse cursor;
168 setting a nonzero mask may turn it on.
169 Whether this happens is device-dependent.
170 .SS "Mouse Events"
171 Several mouse event types may be selected;
172 construct a mask by logically \*(``or\*(''-ing their values.
173 .PP
174 .TS
175 Lb Lb
176 Lb Lw(33n)x.
177 Name Description
178 =
179 BUTTON1_PRESSED mouse button 1 down
180 BUTTON1_RELEASED mouse button 1 up
181 BUTTON1_CLICKED mouse button 1 clicked
182 BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
183 BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
184 _
185 BUTTON2_PRESSED mouse button 2 down
186 BUTTON2_RELEASED mouse button 2 up
187 BUTTON2_CLICKED mouse button 2 clicked
188 BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
189 BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
190 _
191 BUTTON3_PRESSED mouse button 3 down
192 BUTTON3_RELEASED mouse button 3 up
193 BUTTON3_CLICKED mouse button 3 clicked
194 BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
195 BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
196 _
197 BUTTON4_PRESSED mouse button 4 down
198 BUTTON4_RELEASED mouse button 4 up
199 BUTTON4_CLICKED mouse button 4 clicked
200 BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
201 BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
202 _
203 BUTTON5_PRESSED mouse button 5 down
204 BUTTON5_RELEASED mouse button 5 up
205 BUTTON5_CLICKED mouse button 5 clicked
206 BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked
207 BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked
208 _
209 BUTTON_SHIFT T{
210 a shift key was down during button state change
211 T}
212 BUTTON_CTRL T{
213 a control key was down during button state change
214 T}
215 BUTTON_ALT T{
216 an alt key was down during button state change
217 T}
218 ALL_MOUSE_EVENTS report all button state changes
219 REPORT_MOUSE_POSITION report mouse movement
220 _
221 .TE
222 .SS getmouse
223 When a window is configured to report a non-empty set of event types,
224 calling the input character reading function on that window may return
225 .B \%KEY_MOUSE
226 to indicate availability of an enqueued mouse event.
227 To read the event data and remove it from the queue,
228 call
229 .BR \%getmouse ","
230 which returns
231 .B OK
232 if a mouse event is visible in the given window
233 and
234 .B ERR
235 otherwise.
236 When
237 .B \%getmouse
238 returns
239 .BR OK ","
240 it deposits data describing the mouse event in the
241 .I event
242 pointer you supply.
243 A subsequent
244 .B \%getmouse
245 call retrieves the next older event from the queue.
246 .SS ungetmouse
247 .B \%ungetmouse
248 behaves analogously to \fB\%ungetch\fP(3NCURSES).
249 It pushes a
250 .B \%KEY_MOUSE
251 event onto the screen's input queue,
252 and
253 .I event
254 onto the mouse event queue.
255 .SS wenclose
256 .B \%wenclose
257 returns
258 .B TRUE
259 if the pair of screen-relative coordinates
260 .RI ( y ,
261 .IR x ")"
262 is enclosed by the given window
263 .IR win ","
264 and
265 .B FALSE
266 otherwise.
267 If
268 .I win
269 is a pad,
270 .B \%wenclose
271 uses its most recent screen coordinates as specified in
272 a \fB\%prefresh\fP(3NCURSES) or \fB\%pnoutrefresh\fP(3NCURSES) call.
273 .PP
274 .B \%wenclose
275 is useful for determining what subset of the screen's windows
276 encloses the location of a mouse event;
277 it is otherwise independent of the
278 .I \%ncurses
279 mouse API.
280 .SS wmouse_trafo
281 .B \%wmouse_trafo
282 transforms the given pair of coordinate pointers
283 .RI ( pY ,
284 .IR pX ")"
285 from a
286 .IR win -relative
287 basis to a screen-relative one or
288 .IR "vice versa" ","
289 as
290 .I to-screen
291 is
292 .B TRUE
293 or
294 .BR FALSE ","
295 respectively.
296 .BR \%stdscr -relative
297 coordinates are not always identical to screen coordinates:
298 .I curses
299 supports reservation of screen lines at the top and/or bottom
300 for other purposes;
301 see \fB\%ripoffline\fP(3NCURSES) and \fB\%slk_init\fP(3NCURSES).
302 .PP
303 If
304 .I to-screen is
305 .B TRUE
306 and the pointers
307 .RI ( pY ,
308 .IR pX ")"
309 reference coordinates inside
310 .IR win ","
311 .I \%ncurses
312 updates their values to
313 .BR \%stdscr -relative
314 coordinates and returns
315 .BR TRUE "."
316 If either
317 .I pY
318 or
319 .I pX
320 is a null pointer,
321 or
322 .RI ( pY ,
323 .IR pX ")"
324 is not inside
325 .IR win ","
326 .B \%wmouse_trafo
327 returns
328 .BR FALSE "."
329 .PP
330 If
331 .I to-screen is
332 .B FALSE
333 and the pointers
334 .RI ( pY ,
335 .IR pX ")"
336 reference coordinates inside
337 .BR stdscr ","
338 .I \%ncurses
339 updates their values to
340 .IR win -relative
341 coordinates and returns
342 .BR TRUE "."
343 If either
344 .I pY
345 or
346 .I pX
347 is a null pointer,
348 or
349 .RI ( pY ,
350 .IR pX ")"
351 is not inside
352 .BR stdscr ","
353 .B \%wmouse_trafo
354 returns
355 .BR FALSE "."
356 .SS mouse_trafo
357 .B \%mouse_trafo
358 applies the
359 .B \%wmouse_trafo
360 translation to
361 .BR \%stdscr "."
362 If no screen lines are reserved by \fB\%ripoffline\fP(3NCURSES) or
363 \fB\%slk_init\fP(3NCURSES),
364 this is the identity transformation.
365 .SS mouseinterval
366 .B \%mouseinterval
367 sets the maximum time
368 (in thousandths of a second)
369 that can elapse between press and release events for them to
370 be resolved as a
371 .IR click .
372 An application might interpret button press and release events separated
373 by more than the mouse interval as a \*(``long press\*('',
374 or,
375 with motion,
376 as a \*(``drag\*(''.
377 .PP
378 When
379 .I \%ncurses
380 detects a mouse event,
381 it awaits further input activity up to this interval,
382 and then checks for a subsequent mouse event which can be combined
383 with the first event.
384 If the timeout expires without input activity,
385 then no click resolution occurs.
386 Calling
387 .B \%mouseinterval(0)
388 disables click resolution.
389 .PP
390 .B \%mouseinterval
391 returns the previous interval value.
392 Use
393 .B \%mouseinterval(\-1)
394 to obtain the interval without altering it.
395 .PP
396 The mouse interval is set to one sixth of a second
397 when the corresponding screen is initialized,
398 e.g., in \fBinitscr\fP(3NCURSES) or \fBsetupterm\fP(3NCURSES).
399 .SH RETURN VALUE
400 .BR \%has_mouse ","
401 .BR \%wenclose ","
402 .BR \%mouse_trafo ","
403 and
404 .B \%wmouse_trafo
405 return
406 .B TRUE
407 or
408 .B FALSE
409 as noted above.
410 .PP
411 .B \%getmouse
412 and
413 .B \%ungetmouse
414 return
415 .B ERR
416 upon failure and
417 .B OK
418 upon success.
419 .PP
420 .B \%getmouse
421 fails if:
422 .bP
423 no mouse driver was initialized,
424 .bP
425 the mask of reportable events is zero,
426 .bP
427 a mouse event was detected that does not match the mask,
428 or
429 .bP
430 no more events remain in the queue.
431 .PP
432 .B \%ungetmouse
433 returns
434 .B ERR
435 if the event queue is full.
436 .PP
437 .B \%mousemask
438 returns the mask of reportable events.
439 .PP
440 .B \%mouseinterval
441 returns the previous interval value, unless
442 the terminal was not initialized.
443 In that case, it returns the maximum interval value (166).
444 .SH NOTES
445 The order of the
446 .B \%MEVENT
447 structure members is not guaranteed.
448 Additional fields may be added to the structure in the future.
449 .PP
450 Under
451 .IR \%ncurses ,
452 these calls are implemented using either
453 .IR \%xterm 's
454 built-in mouse-tracking API or
455 platform-specific drivers including
456 .RS 3
457 .bP
458 Alessandro Rubini's gpm server
459 .bP
460 FreeBSD sysmouse
461 .bP
462 OS/2 EMX
463 .RE
464 .PP
465 If you are using an unsupported configuration,
466 mouse events are not visible to
467 .I \%ncurses
468 (and the
469 .B \%mousemask
470 function always returns
471 .BR 0 ")."
472 .PP
473 If the terminal type possesses the (nonstandard)
474 .I \%term\%info
475 string capability
476 .BR XM ","
477 .IR \%ncurses "'s"
478 .I \%xterm
479 mouse driver uses it when initializing the terminal for mouse operation.
480 The default,
481 if
482 .B XM
483 is not found,
484 corresponds to private mode 1000 of
485 .IR \%xterm "."
486 .PP
487 .RS 3
488 .EX
489 \eE[?1000%?%p1%{1}%=%th%el%;
490 .EE
491 .RE
492 .PP
493 .I \%ncurses
494 also recognizes
495 .IR \%xterm 's
496 newer private mode 1006.
497 .PP
498 .RS 3
499 .EX
500 \eE[?1006;1000%?%p1%{1}%=%th%el%;
501 .EE
502 .RE
503 .PP
504 The
505 .I id
506 member of the mouse event structure is not presently used;
507 no terminal type or operating system interface supports reporting events
508 from distinguishable pointing devices.
509 If you synthesize an
510 .IR \%MEVENT ","
511 use an
512 .I id
513 of 0.
514 .PP
515 The
516 .I z
517 member of the mouse event structure is not presently used.
518 It is intended
519 for use with touch screens (which may be pressure-sensitive) or with
520 3D-mice/trackballs/power gloves.
521 .PP
522 The
523 .B \%ALL_MOUSE_EVENTS
524 class does not include
525 .BR \%REPORT_MOUSE_POSITION "."
526 They are distinct.
527 For example,
528 in
529 .IR \%xterm ,
530 wheel/scrolling mice send position reports as a sequence of
531 presses of buttons 4 or 5 without matching button-releases.
532 .SH EXTENSIONS
533 These functions are
534 .I \%ncurses
535 extensions,
536 and are not found in SVr4
537 .IR curses ,
538 4.4BSD
539 .IR curses ,
540 or any other previous
541 .I curses
542 implementation.
543 (SVr4
544 .I curses
545 did have a
546 .I \%getmouse
547 function,
548 which took no argument and returned an
549 .IR "unsigned long" ".)"
550 .SH PORTABILITY
551 Applications employing the
552 .I \%ncurses
553 mouse extension should condition its use on the visibility of the
554 .B \%NCURSES_MOUSE_VERSION
555 preprocessor macro.
556 When the interface changes,
557 the macro's value increments.
558 Multiple versions are available when
559 .I \%ncurses
560 is configured;
561 see section \*(``ALTERNATE CONFIGURATIONS\*('' of \fB\%ncurses\fP(3NCURSES).
562 The following values may be specified.
563 .RS 3
564 .TP 3
565 .B 1
566 has definitions for reserved events.
567 The mask uses 28 bits.
568 .TP 3
569 .B 2
570 adds definitions for button 5,
571 removes the definitions for reserved events.
572 The mask uses 29 bits.
573 .RE
574 .SH HISTORY
575 SVr4 (1989) added mouse support to its variant of \fI\%xterm\fP(1).
576 It is mentioned in a few places,
577 with little supporting documentation.
578 .bP
579 Its \*(``libcurses\*('' manual page lists functions for this feature
580 prototyped in
581 .IR \%curses.h "."
582 .PP
583 .RS 8
584 .EX
585 .nf
586 extern int mouse_set(long int);
587 extern int mouse_on(long int);
588 extern int mouse_off(long int);
589 extern int request_mouse_pos(void);
590 extern int map_button(unsigned long);
591 extern void wmouse_position(WINDOW *, int *, int *);
592 extern unsigned long getmouse(void), getbmap(void);
593 .fi
594 .EE
595 .RE
596 .bP
597 Its \*(``terminfo\*('' manual page lists capabilities for the feature.
598 .PP
599 .\" These don't appear in the SVID 4th edition, Volume 3,
600 .\" terminfo(TI_ENV) man page. They can be found in, e.g., the "z/OS
601 .\" V1R1.0 C Curses" book, Chapter 17, pp. 179-186 (PDF 213-220).
602 .RS 8
603 .TS
604 Lb Lb Lb Lw(23n)x.
605 buttons btns BT T{
606 Number of buttons on the mouse
607 T}
608 get_mouse getm Gm T{
609 Curses should get button events
610 T}
611 key_mouse kmous Km T{
612 0631, Mouse event has occurred
613 T}
614 mouse_info minfo Mi T{
615 Mouse status information
616 T}
617 req_mouse_pos reqmp RQ T{
618 Request mouse position report
619 T}
620 .TE
621 .RE
622 .bP
623 The interface made assumptions
624 (as does
625 .IR \%ncurses )
626 about the escape sequences sent to and received from the terminal.
627 .IP
628 For instance,
629 the SVr4
630 .I curses
631 library used the
632 .B \%get_mouse
633 .RB ( getm )
634 capability to tell the terminal which
635 mouse button events it should send,
636 passing the mouse-button bit mask to the terminal.
637 Also, it could ask the terminal
638 where the mouse was using the
639 .B \%req_mouse_pos
640 .RB ( reqmp )
641 capability.
642 .IP
643 Those features required a terminal program that had been modified
644 to work with SVr4
645 .IR curses .
646 They were not part of the X Consortium's
647 .IR \%xterm .
648 .PP
649 When developing the
650 .I \%xterm
651 mouse support for
652 .I \%ncurses
653 in September 1995,
654 Eric Raymond was uninterested in using the same interface due to its
655 lack of documentation.
656 Later, in 1998, Mark Hesseling provided support in
657 .I \%PDCurses
658 2.3 using the SVr4 interface.
659 .IR \%PDCurses ,
660 however,
661 does not use video terminals,
662 making it unnecessary to be concerned about compatibility with the
663 escape sequences.
664 .SH BUGS
665 Mouse events from
666 .I \%xterm
667 are
668 .I not
669 ignored in canonical (\*(``cooked\*('') mode
670 if they have been enabled by
671 .BR \%mousemask "."
672 Instead,
673 the
674 .I \%xterm
675 mouse report sequence appears in the string read.
676 .PP
677 An
678 .I \%ncurses
679 window must enable \fB\%keypad\fP(3NCURSES) to correctly receive mouse event
680 reports from
681 .I \%xterm
682 since they are encoded like function keys.
683 Set the terminal's
684 .I \%term\%info
685 capability
686 .B \%key_mouse
687 .RB ( \%kmous )
688 to \*(``\eE[M\*(''
689 (the beginning of the response from
690 .I \%xterm
691 for mouse clicks).
692 Other values of
693 .B \%key_mouse
694 are permitted under the same assumption \(em
695 that is,
696 a mouse report begins with the value of the
697 .B \%key_mouse
698 .RB ( \%kmous )
699 string capability.
700 .PP
701 Because there are no standard response sequences that serve to identify
702 terminals supporting the
703 .I \%xterm
704 mouse protocol,
705 .I \%ncurses
706 assumes that if
707 .B \%key_mouse
708 .RB ( \%kmous )
709 is defined in the terminal description,
710 or if the terminal type's primary name or aliases contain the string
711 \%\*(``xterm\*('',
712 then the terminal may send mouse events.
713 .I \%ncurses
714 checks the
715 .B \%kmous
716 cap-code first,
717 allowing use of newer
718 .I \%xterm
719 mouse protocols,
720 such as its private mode 1006.
721 .SH SEE ALSO
722 \fB\%ncurses\fP(3NCURSES),
723 \fB\%inopts\fP(3NCURSES),
724 \fB\%kernel\fP(3NCURSES),
725 \fB\%pad\fP(3NCURSES),
726 \fB\%slk\fP(3NCURSES),
727 \fB\%curses_variables\fP(3NCURSES)