curs\_mouse(3X) Library calls curs\_mouse(3X) # [NAME](#NAME) **has\_mouse**, **getmouse**, **ungetmouse**, **mousemask**, **wenclose**, **mouse\_trafo**, **wmouse\_trafo**, **mouseinterval**, **mmask\_t**, **MEVENT** - get mouse events in *ncurses* # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` /* data types */ typedef unsigned long mmask_t; ``` ``` typedef struct { short id; /* ID to distinguish multiple devices */ int x, y, z; /* event coordinates */ mmask_t bstate; /* button state bits */ } MEVENT; ``` ``` /* functions */ bool has_mouse(void); ``` ``` mmask_t mousemask(mmask_t new-mask, mmask_t * old-mask); ``` ``` int getmouse(MEVENT * event); int ungetmouse(MEVENT * event); ``` ``` bool wenclose(const WINDOW * win, int y, int x); ``` ``` bool mouse_trafo(int * pY, int * pX, bool to-screen); bool wmouse_trafo(const WINDOW * win, int * pY, int * pX, bool to-screen); ``` ``` int mouseinterval(int erval); ``` # [DESCRIPTION](#DESCRIPTION) *ncurses* provides an interface to the mouse or other pointing device. An application can register its interest in such events; the library then exposes the availability of a mouse event via an *input character reading function*: this is [**wgetch**(3X)](/man/os/ncurses/wgetch.3X) in the non-wide character *curses* API and [**wget\_wch**(3X)](/man/os/ncurses/wget_wch.3X) in the wide character API. A queue distinct from that used for keyboard events accumulates the details of mouse events. The input character reading function reports the **KEY\_MOUSE** key code when a mouse event is available for collection. A single mouse event queue serves all windows associated with the screen. The *MEVENT* structure describes a mouse event. Its *y* and *x* coordinates are screen-, not window-, relative. The *bstate* member has exactly one bit set indicating the event type, and up to 3 additional bits indicating the use of modifier keys. *ncurses* ignores mouse events when input is in canonical (“cooked”) mode, and produces an error beep when they occur while the library simulates canonical mode in a window, as with [**getstr**(3X)](/man/os/ncurses/getstr.3X) (wide-character API users: [**get\_wstr**(3X)](/man/os/ncurses/get_wstr.3X)), which expects a line feed to terminate its input loop. ## [has\_mouse](#has_mouse) The terminal type or operating system interface must support the encoding of mouse events. **has\_mouse** returns **TRUE** if *ncurses*'s mouse driver initialized successfully, and **FALSE** otherwise. ## [mousemask](#mousemask) Use **mousemask** to select the varieties of mouse event your application wishes to receive. By default, *ncurses* reports no mouse events. • The function returns an updated copy of *new-mask* indicating which event types of interest are reportable by the terminal's mouse protocol. If the screen is not initialized, or the terminal interface does not report mouse events, **mousemask** returns 0. • If *old-mask* is not a null pointer, **mousemask** stores the previous value of the screen's mouse event mask there. As a side effect, setting a zero mouse mask may turn off the mouse cursor; setting a nonzero mask may turn it on. Whether this happens is device-dependent. ## [Mouse Events](#Mouse_Events) Several mouse event types may be selected; construct a mask by logically “or”-ing their values. **Name** **Description** **BUTTON1\_PRESSED** mouse button 1 down **BUTTON1\_RELEASED** mouse button 1 up **BUTTON1\_CLICKED** mouse button 1 clicked **BUTTON1\_DOUBLE\_CLICKED** mouse button 1 double clicked **BUTTON1\_TRIPLE\_CLICKED** mouse button 1 triple clicked **BUTTON2\_PRESSED** mouse button 2 down **BUTTON2\_RELEASED** mouse button 2 up **BUTTON2\_CLICKED** mouse button 2 clicked **BUTTON2\_DOUBLE\_CLICKED** mouse button 2 double clicked **BUTTON2\_TRIPLE\_CLICKED** mouse button 2 triple clicked **BUTTON3\_PRESSED** mouse button 3 down **BUTTON3\_RELEASED** mouse button 3 up **BUTTON3\_CLICKED** mouse button 3 clicked **BUTTON3\_DOUBLE\_CLICKED** mouse button 3 double clicked **BUTTON3\_TRIPLE\_CLICKED** mouse button 3 triple clicked **BUTTON4\_PRESSED** mouse button 4 down **BUTTON4\_RELEASED** mouse button 4 up **BUTTON4\_CLICKED** mouse button 4 clicked **BUTTON4\_DOUBLE\_CLICKED** mouse button 4 double clicked **BUTTON4\_TRIPLE\_CLICKED** mouse button 4 triple clicked **BUTTON5\_PRESSED** mouse button 5 down **BUTTON5\_RELEASED** mouse button 5 up **BUTTON5\_CLICKED** mouse button 5 clicked **BUTTON5\_DOUBLE\_CLICKED** mouse button 5 double clicked **BUTTON5\_TRIPLE\_CLICKED** mouse button 5 triple clicked **BUTTON\_SHIFT** a shift key was down during button state change **BUTTON\_CTRL** a control key was down during button state change **BUTTON\_ALT** an alt key was down during button state change **ALL\_MOUSE\_EVENTS** report all button state changes **REPORT\_MOUSE\_POSITION** report mouse movement ## [getmouse](#getmouse) When a window is configured to report a non-empty set of event types, calling the input character reading function on that window may return **KEY\_MOUSE** to indicate availability of an enqueued mouse event. To read the event data and remove it from the queue, call **getmouse**, which returns **OK** if a mouse event is visible in the given window and **ERR** otherwise. When **getmouse** returns **OK**, it deposits data describing the mouse event in the *event* pointer you supply. A subsequent **getmouse** call retrieves the next older event from the queue. ## [ungetmouse](#ungetmouse) **ungetmouse** behaves analogously to [**ungetch**(3X)](/man/os/ncurses/ungetch.3X). It pushes a **KEY\_MOUSE** event onto the screen's input queue, and *event* onto the mouse event queue. ## [wenclose](#wenclose) **wenclose** returns **TRUE** if the pair of screen-relative coordinates (*y*, *x*) is enclosed by the given window *win*, and **FALSE** otherwise. If *win* is a pad, **wenclose** uses its most recent screen coordinates as specified in a [**prefresh**(3X)](/man/os/ncurses/prefresh.3X) or [**pnoutrefresh**(3X)](/man/os/ncurses/pnoutrefresh.3X) call. **wenclose** is useful for determining what subset of the screen's windows encloses the location of a mouse event; it is otherwise independent of the *ncurses* mouse API. ## [wmouse\_trafo](#wmouse_trafo) **wmouse\_trafo** transforms the given pair of coordinate pointers (*pY*, *pX*) from a *win*-relative basis to a screen-relative one or *vice versa*, as *to-screen* is **TRUE** or **FALSE**, respectively. **stdscr**-relative coordinates are not always identical to screen coordinates: *curses* supports reservation of screen lines at the top and/or bottom for other purposes; see [**ripoffline**(3X)](/man/os/ncurses/ripoffline.3X) and [**slk\_init**(3X)](/man/os/ncurses/slk_init.3X). If *to-screen is* **TRUE** and the pointers (*pY*, *pX*) reference coordinates inside *win*, *ncurses* updates their values to **stdscr**-relative coordinates and returns **TRUE**. If either *pY* or *pX* is a null pointer, or (*pY*, *pX*) is not inside *win*, **wmouse\_trafo** returns **FALSE**. If *to-screen is* **FALSE** and the pointers (*pY*, *pX*) reference coordinates inside **stdscr**, *ncurses* updates their values to *win*-relative coordinates and returns **TRUE**. If either *pY* or *pX* is a null pointer, or (*pY*, *pX*) is not inside **stdscr**, **wmouse\_trafo** returns **FALSE**. **wmouse\_trafo** is useful for performing coordinate transforms between windows; it is otherwise independent of the *ncurses* mouse API. ## [mouse\_trafo](#mouse_trafo) **mouse\_trafo** applies the **wmouse\_trafo** translation to **stdscr**. If no screen lines are reserved by [**ripoffline**(3X)](/man/os/ncurses/ripoffline.3X) or [**slk\_init**(3X)](/man/os/ncurses/slk_init.3X), this is the identity transformation. ## [mouseinterval](#mouseinterval) **mouseinterval** sets the maximum time (in thousandths of a second) that can elapse between press and release events for them to be *resolved* as (combined into) a *click*. An application might interpret button press and release events separated by more than the mouse interval as a “long press”, or, with motion, as a “drag”. When *ncurses* detects a mouse event, it awaits further input activity up to this interval, and then checks for a subsequent mouse event that is combinable with the first event. If the timeout expires without input activity, then no click resolution occurs. Calling **mouseinterval(0)** disables click resolution. **mouseinterval** returns the previous interval value. Use **mouseinterval(-1)** to obtain the interval without altering it. The mouse interval is set to one sixth of a second when the corresponding screen is initialized, e.g., in [**initscr**(3X)](/man/os/ncurses/initscr.3X) or [**setupterm**(3X)](/man/os/ncurses/setupterm.3X). # [RETURN VALUE](#RETURN_VALUE) **has\_mouse**, **wenclose**, **mouse\_trafo**, and **wmouse\_trafo** return **TRUE** or **FALSE** as noted above. **getmouse** and **ungetmouse** return **ERR** upon failure and **OK** upon success. **getmouse** fails if: - no mouse driver was initialized, - the mask of reportable events is zero, - a mouse event was detected that does not match the mask, or - no more events remain in the queue. **ungetmouse** returns **ERR** if the event queue is full. **mousemask** returns the mask of reportable events. **mouseinterval** returns the previous interval value, unless the terminal was not initialized. In that case, it returns the maximum interval value (166). # [NOTES](#NOTES) The order of the **MEVENT** structure members is not guaranteed. Additional fields may be added to the structure in the future. Under *ncurses*, these calls are implemented using either *xterm*'s built-in mouse-tracking API or platform-specific drivers including - Alessandro Rubini's gpm server - FreeBSD sysmouse - OS/2 EMX If you are using an unsupported configuration, mouse events are not visible to *ncurses* (and the **mousemask** function always returns **0**). If the terminal type possesses the (nonstandard) *terminfo* string capability **XM**, *ncurses*'s *xterm* mouse driver uses it when initializing the terminal for mouse operation. The default, if **XM** is not found, corresponds to private mode 1000 of *xterm*. ``` \E[?1000%?%p1%{1}%=%th%el%; ``` *ncurses* also recognizes *xterm*'s newer private mode 1006. ``` \E[?1006;1000%?%p1%{1}%=%th%el%; ``` The *id* member of the mouse event structure is not presently used; no terminal type or operating system interface supports reporting events from distinguishable pointing devices. If you synthesize an *MEVENT*, use an *id* of 0. The *z* member of the mouse event structure is not presently used. It is intended for use with touch screens (which may be pressure-sensitive) or with 3D-mice/trackballs/power gloves. The **ALL\_MOUSE\_EVENTS** class does not include **REPORT\_MOUSE\_POSITION**. They are distinct. For example, in *xterm*, wheel/scrolling mice send position reports as a sequence of presses of buttons 4 or 5 without matching button-releases. # [EXTENSIONS](#EXTENSIONS) These functions are *ncurses* extensions, and are not found in SVr4 *curses*, 4.4BSD *curses*, or any other previous *curses* implementation. (SVr4 *curses* did have a *getmouse* function, which took no argument and returned an *unsigned long*.) # [PORTABILITY](#PORTABILITY) Applications employing the *ncurses* mouse extension should condition its use on the visibility of the **NCURSES\_MOUSE\_VERSION** preprocessor macro. When the interface changes, the macro's value increments. Multiple versions are available when *ncurses* is configured; see section “ALTERNATE CONFIGURATIONS” of [**ncurses**(3X)](/man/os/ncurses/ncurses.3X). The following values may be specified. **1** has definitions for reserved events. The mask uses 28 bits. **2** adds definitions for button 5, removes the definitions for reserved events. The mask uses 29 bits. # [HISTORY](#HISTORY) SVr4 (1989) added mouse support to its variant of [*xterm*(1)](/man/os/ncurses/xterm.1). It is mentioned in a few places, with little supporting documentation. • Its “libcurses” manual page lists functions for this feature prototyped in *curses.h*. ``` extern int mouse_set(long int); extern int mouse_on(long int); extern int mouse_off(long int); extern int request_mouse_pos(void); extern int map_button(unsigned long); extern void wmouse_position(WINDOW *, int *, int *); extern unsigned long getmouse(void), getbmap(void); ``` • Its “terminfo” manual page lists capabilities for the feature. **buttons** **btns** **BT** Number of buttons on the mouse **get\_mouse** **getm** **Gm** Curses should get button events **key\_mouse** **kmous** **Km** 0631, Mouse event has occurred **mouse\_info** **minfo** **Mi** Mouse status information **req\_mouse\_pos** **reqmp** **RQ** Request mouse position report • The interface made assumptions (as does *ncurses*) about the escape sequences sent to and received from the terminal. For instance, the SVr4 *curses* library used the **get\_mouse** (**getm**) capability to tell the terminal which mouse button events it should send, passing the mouse-button bit mask to the terminal. Also, it could ask the terminal where the mouse was using the **req\_mouse\_pos** (**reqmp**) capability. Those features required a terminal program that had been modified to work with SVr4 *curses*. They were not part of the X Consortium's *xterm*. When developing the *xterm* mouse support for *ncurses* in September 1995, Eric Raymond was uninterested in using the same interface due to its lack of documentation. Later, in 1998, Mark Hesseling provided support in *PDCurses* 2.3 using the SVr4 interface. *PDCurses*, however, does not use video terminals, making it unnecessary to be concerned about compatibility with the escape sequences. # [BUGS](#BUGS) Mouse events from *xterm* are *not* ignored in canonical (“cooked”) mode if they have been enabled by **mousemask**. Instead, the *xterm* mouse report sequence appears in the string read. An *ncurses* window must enable [**keypad**(3X)](/man/os/ncurses/keypad.3X) to correctly receive mouse event reports from *xterm* since they are encoded like function keys. Set the terminal's *terminfo* capability **key\_mouse** (**kmous**) to “\\E[M” (the beginning of the response from *xterm* for mouse clicks). Other values of **key\_mouse** are permitted under the same assumption — that is, a mouse report begins with the value of the **key\_mouse** (**kmous**) string capability. Because there are no standard response sequences that serve to identify terminals supporting the *xterm* mouse protocol, *ncurses* assumes that if **key\_mouse** (**kmous**) is defined in the terminal description, or if the terminal type's primary name or aliases contain the string “xterm”, then the terminal may send mouse events. *ncurses* checks the **kmous** cap-code first, allowing use of newer *xterm* mouse protocols, such as its private mode 1006. # [SEE ALSO](#SEE_ALSO) [**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_inopts**(3X)](/man/os/ncurses/curs_inopts.3X), [**curs\_kernel**(3X)](/man/os/ncurses/curs_kernel.3X), [**curs\_pad**(3X)](/man/os/ncurses/curs_pad.3X), [**curs\_slk**(3X)](/man/os/ncurses/curs_slk.3X), [**curs\_variables**(3X)](/man/os/ncurses/curs_variables.3X) 2026-09-19 ncurses 6.6 --- Document: getmouse(3x) from ncurses 6.6.20260926-r0 (Chainguard OS) Source: https://github.com/ThomasDickey/ncurses-snapshots