1.\" $NetBSD: curses_mouse.3,v 1.2 2020/03/23 16:14:20 wiz Exp $ 2.\" 3.\" Copyright (c) 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Roy Marples. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" 31.Dd March 22, 2020 32.Dt CURSES_MOUSE 3 33.Os 34.Sh NAME 35.Nm has_mouse , 36.Nm getmouse , 37.Nm ungetmouse , 38.Nm mousemask , 39.Nm wenclose , 40.Nm mouse_trafo , 41.Nm wmouse_trafo , 42.Nm mouseinterval 43.Nd Curses mouse interface 44.Sh LIBRARY 45.Lb libcurses 46.Sh SYNOPSIS 47.In curses.h 48.Ft bool 49.Fn has_mouse "void" 50.Ft int 51.Fn getmouse "MEVENT *event" 52.Ft int 53.Fn ungetmouse "MEVENT *event" 54.Ft mmask_t 55.Fn mousemask "mmask_t newmask" "mmask_t *oldmask" 56.Ft bool 57.Fn wenclose "const WINDOW *win" "int y" "int x" 58.Ft bool 59.Fn mouse_trafo "int *y" "int *x" "bool to_screen" 60.Ft bool 61.Fn wmouse_trafo "const WINDOW *win" "int *y" "int *x" "bool to_screen" 62.Ft int 63.Fn mouseinterval "int erval" 64.Sh DESCRIPTION 65This is the curses interface to mouse events. 66Mouse events are reported via the 67.Dv KEY_MOUSE 68value in the 69.Xr wgetch 3 70input stream. 71.Pp 72The 73.Fn has_mouse 74function returns true if the mouse support has been initialised for the 75terminal, otherwise false. 76.Pp 77The 78.Fn getmouse 79function reads a mouse event. 80The 81.Fa x 82and 83.Fa y 84values are screen relative and the state mask will have exactly one bit set 85to represent the event type. 86The 87.Fn ungetmouse 88function behave like 89.Xr ungetch 3 90and pushes the mouse event into the input stream. 91.Pp 92The 93.Fn mousemask 94function sets the mouse events to be reported. 95By default, there are no mouse events reported. 96It returns a mask indicating which of the specified mouse events can be 97reported, zero indicating a failure. 98If oldmask is given, it is filled with the previous mouse event mask. 99.Pp 100The 101.Fn wenclose 102function returns true if the screen relative 103.Fa x 104and 105.Fa y 106co-ordinates are enclosed by the window 107.Fa win , 108otherwise false. 109.Pp 110The 111.Fn wmouse_trafo 112function transforms the 113.Fa x 114and 115.Fa y 116co-ordinates from screen relative to window relative or vice versa 117depending on the value of 118.Fa to_screen . 119If the co-ordinates are not enclosed by the window 120.Fa win 121then false is returned, otherwise the 122.Fa x 123and 124.Fa y 125values are transformed and true is returned. 126The 127.Fn mouse_trainfo 128function calls 129.Fn wmouse_trainfo 130using 131.Va stdscr 132for 133.Fa win . 134.Pp 135The 136.Fn mouseinterval 137function sets the maximum time that can elapse between press and release 138events, which determins a click. 139The value is in thousands of seconds. 140The default value is one fifth of a second. 141The returned value is the old value. 142.Sh RETURN VALUES 143Unless otherwise noted, the functions that return an int will return one of 144the following values: 145.Pp 146.Bl -tag -width ERR -compact 147.It Er OK 148The function completed successfully. 149.It Er ERR 150An error occurred in the function. 151.El 152.Sh SEE ALSO 153.Xr wsmouse 4 154.Sh STANDARDS 155These functions are ncurses extensions to the Curses library. 156.Sh HISTORY 157The mouse functions were added in 158.Nx 10.0 . 159.Sh BUGS 160There is currently no actual mouse support, 161.Fn has_mouse 162will always return false. 163