Debian Codegraph @

upstream/debian-trixie/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.119 2025/02/15 19:36:18 tom Exp $
32 .TH mouse 3NCURSES 2025-02-15 "ncurses 6.5" "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 canonical mode is simulated in a window
124 by a function such as \fB\%getstr\fP(3NCURSES) that expects a linefeed to
125 terminate its input loop.
126 .SS has_mouse
127 The terminal type or operating system interface
128 must support the encoding of mouse events.
129 .B \%has_mouse
130 returns
131 .B TRUE
132 if
133 .IR \%ncurses 's
134 mouse driver initialized successfully,
135 and
136 .B FALSE
137 otherwise.
138 .SS mousemask
139 Use
140 .B \%mousemask
141 to select the varieties of mouse event your application wishes to
142 receive.
143 By default,
144 .I \%ncurses
145 reports no mouse events.
146 .bP
147 The function returns an updated copy of
148 .I new-mask
149 indicating which of the specified mouse events can be reported.
150 .IP
151 If the screen is not initialized,
152 or the terminal interface does report mouse events,
153 .B \%mousemask
154 returns 0.
155 .bP
156 If
157 .I old-mask
158 is not a null pointer,
159 .B \%mousemask
160 stores the previous value
161 of the screen's mouse event mask there.
162 .PP
163 As a side effect,
164 setting a zero mouse mask may turn off the mouse cursor;
165 setting a nonzero mask may turn it on.
166 Whether this happens is device-dependent.
167 .SS "Mouse Events"
168 Several mouse event types may be selected;
169 construct a mask by logically \*(``or\*(''-ing their values.
170 .PP
171 .TS
172 Lb Lb
173 Lb Lx.
174 Name Description
175 =
176 BUTTON1_PRESSED mouse button 1 down
177 BUTTON1_RELEASED mouse button 1 up
178 BUTTON1_CLICKED mouse button 1 clicked
179 BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
180 BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
181 _
182 BUTTON2_PRESSED mouse button 2 down
183 BUTTON2_RELEASED mouse button 2 up
184 BUTTON2_CLICKED mouse button 2 clicked
185 BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
186 BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
187 _
188 BUTTON3_PRESSED mouse button 3 down
189 BUTTON3_RELEASED mouse button 3 up
190 BUTTON3_CLICKED mouse button 3 clicked
191 BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
192 BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
193 _
194 BUTTON4_PRESSED mouse button 4 down
195 BUTTON4_RELEASED mouse button 4 up
196 BUTTON4_CLICKED mouse button 4 clicked
197 BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
198 BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
199 _
200 BUTTON5_PRESSED mouse button 5 down
201 BUTTON5_RELEASED mouse button 5 up
202 BUTTON5_CLICKED mouse button 5 clicked
203 BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked
204 BUTTON5_TRIPLE_CLICKED mouse button 5 triple clicked
205 _
206 BUTTON_SHIFT T{
207 a shift key was down during button state change
208 T}
209 BUTTON_CTRL T{
210 a control key was down during button state change
211 T}
212 BUTTON_ALT T{
213 an alt key was down during button state change
214 T}
215 ALL_MOUSE_EVENTS report all button state changes
216 REPORT_MOUSE_POSITION report mouse movement
217 _
218 .TE
219 .SS getmouse
220 Once a class of mouse events has been made visible in a window,
221 calling the input character reading function on that window may return
222 .B \%KEY_MOUSE
223 as an indicator that a mouse event is enqueued.
224 To read the event data and pop the event off the queue,
225 call
226 .BR \%getmouse ","
227 which returns
228 .B OK
229 if a mouse event is visible in the given window
230 and
231 .B ERR
232 otherwise.
233 When
234 .B \%getmouse
235 returns
236 .BR OK ","
237 it deposits data describing the mouse event in the
238 .I event
239 pointer you supply.
240 A subsequent
241 .B \%getmouse
242 call retrieves the next older event from the queue.
243 .SS ungetmouse
244 .B \%ungetmouse
245 behaves analogously to \fB\%ungetch\fP(3NCURSES).
246 It pushes a
247 .B \%KEY_MOUSE
248 event onto the screen's input queue,
249 and
250 .I event
251 onto the mouse event queue.
252 .SS wenclose
253 .B \%wenclose
254 returns
255 .B TRUE
256 if the pair of screen-relative coordinates
257 .RI ( y ,
258 .IR x ")"
259 is enclosed by the given window
260 .IR win ","
261 and
262 .B FALSE
263 otherwise.
264 If
265 .I win
266 is a pad,
267 .B \%wenclose
268 uses its most recent screen coordinates as specified in
269 a \fB\%prefresh\fP(3NCURSES) or \fB\%pnoutrefresh\fP(3NCURSES) call.
270 .PP
271 .B \%wenclose
272 is useful for determining what subset of the screen's windows
273 encloses the location of a mouse event;
274 it is otherwise independent of the
275 .I \%ncurses
276 mouse API.
277 .SS wmouse_trafo
278 .B \%wmouse_trafo
279 transforms the given pair of coordinate pointers
280 .RI ( pY ,
281 .IR pX ")"
282 from a
283 .IR win -relative
284 basis to a screen-relative one or
285 .IR "vice versa" ","
286 as
287 .I to-screen
288 is
289 .B TRUE
290 or
291 .BR FALSE ","
292 respectively.
293 .BR \%stdscr -relative
294 coordinates are not always identical to screen coordinates:
295 .I curses
296 supports reservation of screen lines at the top and/or bottom
297 for other purposes;
298 see \fB\%ripoffline\fP(3NCURSES) and \fB\%slk_init\fP(3NCURSES).
299 .PP
300 If
301 .I to-screen is
302 .B TRUE
303 and the pointers
304 .RI ( pY ,
305 .IR pX ")"
306 reference coordinates inside
307 .IR win ","
308 .I \%ncurses
309 updates their values to
310 .BR \%stdscr -relative
311 coordinates and returns
312 .BR TRUE "."
313 If either
314 .I pY
315 or
316 .I pX
317 is a null pointer,
318 or
319 .RI ( pY ,
320 .IR pX ")"
321 is not inside
322 .IR win ","
323 .B \%wmouse_trafo
324 returns
325 .BR FALSE "."
326 .PP
327 If
328 .I to-screen is
329 .B FALSE
330 and the pointers
331 .RI ( pY ,
332 .IR pX ")"
333 reference coordinates inside
334 .BR stdscr ","
335 .I \%ncurses
336 updates their values to
337 .IR win -relative
338 coordinates and returns
339 .BR TRUE "."
340 If either
341 .I pY
342 or
343 .I pX
344 is a null pointer,
345 or
346 .RI ( pY ,
347 .IR pX ")"
348 is not inside
349 .BR stdscr ","
350 .B \%wmouse_trafo
351 returns
352 .BR FALSE "."
353 .SS mouse_trafo
354 .B \%mouse_trafo
355 applies the
356 .B \%wmouse_trafo
357 translation to
358 .BR \%stdscr "."
359 If no screen lines are reserved by \fB\%ripoffline\fP(3NCURSES) or
360 \fB\%slk_init\fP(3NCURSES),
361 this is the identity transformation.
362 .SS mouseinterval
363 .B \%mouseinterval
364 sets the maximum time
365 (in thousandths of a second)
366 that can elapse between press and release events for them to
367 be resolved as a
368 .IR click .
369 An application might interpret button press and release events separated
370 by more than the mouse interval as a \*(``long press\*('',
371 or,
372 with motion,
373 as a \*(``drag\*(''.
374 .PP
375 Calling
376 .B \%mouseinterval(0)
377 disables click resolution.
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 (which would happen with a zero interval),
386 then no click resolution occurs.
387 .PP
388 This function returns the previous interval value.
389 Use
390 .B \%mouseinterval(\-1)
391 to obtain the interval without altering it.
392 .PP
393 The mouse interval is set to one sixth of a second
394 when the corresponding screen is initialized,
395 e.g., in \fB\%initscr\fP(3NCURSES) or \fB\%setupterm\fP(3NCURSES).
396 .SH RETURN VALUE
397 .BR \%has_mouse ","
398 .BR \%wenclose ","
399 .BR \%mouse_trafo ","
400 and
401 .B \%wmouse_trafo
402 return
403 .B TRUE
404 or
405 .B FALSE
406 as noted above.
407 .PP
408 .B \%getmouse
409 and
410 .B \%ungetmouse
411 return
412 .B ERR
413 upon failure and
414 .B OK
415 upon success.
416 .PP
417 .B \%getmouse
418 fails if:
419 .bP
420 no mouse driver was initialized,
421 .bP
422 the mask of reportable events is zero,
423 .bP
424 a mouse event was detected that does not match the mask,
425 or
426 .bP
427 no more events remain in the queue.
428 .PP
429 .B \%ungetmouse
430 returns
431 .B ERR
432 if the event queue is full.
433 .PP
434 .B \%mousemask
435 returns the mask of reportable events.
436 .PP
437 .B \%mouseinterval
438 returns the previous interval value, unless
439 the terminal was not initialized.
440 In that case, it returns the maximum interval value (166).
441 .SH NOTES
442 The order of the
443 .B \%MEVENT
444 structure members is not guaranteed.
445 Additional fields may be added to the structure in the future.
446 .PP
447 Under
448 .IR \%ncurses ,
449 these calls are implemented using either
450 .IR \%xterm 's
451 built-in mouse-tracking API or
452 platform-specific drivers including
453 .RS 3
454 .bP
455 Alessandro Rubini's gpm server
456 .bP
457 FreeBSD sysmouse
458 .bP
459 OS/2 EMX
460 .RE
461 .PP
462 If you are using an unsupported configuration,
463 mouse events are not visible to
464 .I \%ncurses
465 (and the
466 .B \%mousemask
467 function always returns
468 .BR 0 ")."
469 .PP
470 If the terminal type possesses the (nonstandard)
471 .I \%term\%info
472 string capability
473 .BR XM ","
474 .IR \%ncurses "'s"
475 .I \%xterm
476 mouse driver uses it when initializing the terminal for mouse operation.
477 The default,
478 if
479 .B XM
480 is not found,
481 corresponds to private mode 1000 of
482 .IR \%xterm "."
483 .PP
484 .RS 3
485 .EX
486 \eE[?1000%?%p1%{1}%=%th%el%;
487 .EE
488 .RE
489 .PP
490 .I \%ncurses
491 also recognizes
492 .IR \%xterm 's
493 newer private mode 1006.
494 .PP
495 .RS 3
496 .EX
497 \eE[?1006;1000%?%p1%{1}%=%th%el%;
498 .EE
499 .RE
500 .PP
501 The
502 .I id
503 member of the mouse event structure is not presently used;
504 no terminal type or operating system interface supports reporting events
505 from distinguishable pointing devices.
506 If you synthesize an
507 .IR \%MEVENT ","
508 use an
509 .I id
510 of 0.
511 .PP
512 The
513 .I z
514 member of the mouse event structure is not presently used.
515 It is intended
516 for use with touch screens (which may be pressure-sensitive) or with
517 3D-mice/trackballs/power gloves.
518 .PP
519 The
520 .B \%ALL_MOUSE_EVENTS
521 class does not include
522 .BR \%REPORT_MOUSE_POSITION "."
523 They are distinct.
524 For example,
525 in
526 .IR \%xterm ,
527 wheel/scrolling mice send position reports as a sequence of
528 presses of buttons 4 or 5 without matching button-releases.
529 .SH EXTENSIONS
530 These functions are
531 .I \%ncurses
532 extensions,
533 and are not found in SVr4
534 .IR curses ,
535 4.4BSD
536 .IR curses ,
537 or any other previous
538 .I curses
539 implementation.
540 (SVr4
541 .I curses
542 did have a
543 .I \%getmouse
544 function,
545 which took no argument and returned an
546 .IR "unsigned long" ".)"
547 .SH PORTABILITY
548 Applications employing the
549 .I \%ncurses
550 mouse extension should condition its use on the visibility of the
551 .B \%NCURSES_MOUSE_VERSION
552 preprocessor macro.
553 When the interface changes,
554 the macro's value increments.
555 Multiple versions are available when
556 .I \%ncurses
557 is configured;
558 see section \*(``ALTERNATE CONFIGURATIONS\*('' of \fB\%ncurses\fP(3NCURSES).
559 The following values may be specified.
560 .RS 3
561 .TP 3
562 .B 1
563 has definitions for reserved events.
564 The mask uses 28 bits.
565 .TP 3
566 .B 2
567 adds definitions for button 5,
568 removes the definitions for reserved events.
569 The mask uses 29 bits.
570 .RE
571 .SH HISTORY
572 SVr4 (1989) added mouse support to its variant of \fI\%xterm\fP(1).
573 It is mentioned in a few places,
574 with little supporting documentation.
575 .bP
576 Its \*(``libcurses\*('' manual page lists functions for this feature
577 prototyped in
578 .IR \%curses.h "."
579 .PP
580 .RS 8
581 .EX
582 extern int mouse_set(long int);
583 extern int mouse_on(long int);
584 extern int mouse_off(long int);
585 extern int request_mouse_pos(void);
586 extern int map_button(unsigned long);
587 extern void wmouse_position(WINDOW *, int *, int *);
588 extern unsigned long getmouse(void), getbmap(void);
589 .EE
590 .RE
591 .bP
592 Its \*(``terminfo\*('' manual page lists capabilities for the feature.
593 .PP
594 .\" These don't appear in the SVID 4th edition, Volume 3,
595 .\" terminfo(TI_ENV) man page. They can be found in, e.g., the "z/OS
596 .\" V1R1.0 C Curses" book, Chapter 17, pp. 179-186 (PDF 213-220).
597 .RS 8
598 .TS
599 Lb Lb Lb Lx.
600 buttons btns BT T{
601 Number of buttons on the mouse
602 T}
603 get_mouse getm Gm T{
604 Curses should get button events
605 T}
606 key_mouse kmous Km T{
607 0631, Mouse event has occurred
608 T}
609 mouse_info minfo Mi T{
610 Mouse status information
611 T}
612 req_mouse_pos reqmp RQ T{
613 Request mouse position report
614 T}
615 .TE
616 .RE
617 .bP
618 The interface made assumptions
619 (as does
620 .IR \%ncurses )
621 about the escape sequences sent to and received from the terminal.
622 .IP
623 For instance,
624 the SVr4
625 .I curses
626 library used the
627 .B \%get_mouse
628 .RB ( getm )
629 capability to tell the terminal which
630 mouse button events it should send,
631 passing the mouse-button bit mask to the terminal.
632 Also, it could ask the terminal
633 where the mouse was using the
634 .B \%req_mouse_pos
635 .RB ( reqmp )
636 capability.
637 .IP
638 Those features required a terminal program that had been modified
639 to work with SVr4
640 .IR curses .
641 They were not part of the X Consortium's
642 .IR \%xterm .
643 .PP
644 When developing the
645 .I \%xterm
646 mouse support for
647 .I \%ncurses
648 in September 1995,
649 Eric Raymond was uninterested in using the same interface due to its
650 lack of documentation.
651 Later, in 1998, Mark Hesseling provided support in
652 .I \%PDCurses
653 2.3 using the SVr4 interface.
654 .IR \%PDCurses ,
655 however,
656 does not use video terminals,
657 making it unnecessary to be concerned about compatibility with the
658 escape sequences.
659 .SH BUGS
660 Mouse events from
661 .I \%xterm
662 are
663 .I not
664 ignored in canonical mode if they have been enabled by
665 .BR \%mousemask "."
666 Instead,
667 the
668 .I \%xterm
669 mouse report sequence appears in the string read.
670 .PP
671 An
672 .I \%ncurses
673 window must enable \fB\%keypad\fP(3NCURSES) to correctly receive mouse event
674 reports from
675 .I \%xterm
676 since they are encoded like function keys.
677 Set the terminal's
678 .I \%term\%info
679 capability
680 .B \%key_mouse
681 .RB ( \%kmous )
682 to \*(``\eE[M\*(''
683 (the beginning of the response from
684 .I \%xterm
685 for mouse clicks).
686 Other values of
687 .B \%key_mouse
688 are permitted under the same assumption,
689 that is,
690 the report begins with that sequence.
691 .PP
692 Because there are no standard response sequences that serve to identify
693 terminals supporting the
694 .I \%xterm
695 mouse protocol,
696 .I \%ncurses
697 assumes that if
698 .B \%key_mouse
699 .RB ( \%kmous )
700 is defined in the terminal description,
701 or if the terminal type's primary name or aliases contain the string
702 \%\*(``xterm\*('',
703 then the terminal may send mouse events.
704 .I \%ncurses
705 checks the
706 .B \%kmous
707 cap-code first,
708 allowing use of newer
709 .I \%xterm
710 mouse protocols,
711 such as its private mode 1006.
712 .SH SEE ALSO
713 \fB\%ncurses\fP(3NCURSES),
714 \fB\%inopts\fP(3NCURSES),
715 \fB\%kernel\fP(3NCURSES),
716 \fB\%pad\fP(3NCURSES),
717 \fB\%slk\fP(3NCURSES),
718 \fB\%curses_variables\fP(3NCURSES)