.\"	$NetBSD: curses_mouse.3,v 1.2 2020/03/23 16:14:20 wiz Exp $
.\"
.\" Copyright (c) 2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Roy Marples.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\"
.Dd March 22, 2020
.Dt CURSES_MOUSE 3
.Os
.Sh NAME
.Nm has_mouse ,
.Nm getmouse ,
.Nm ungetmouse ,
.Nm mousemask ,
.Nm wenclose ,
.Nm mouse_trafo ,
.Nm wmouse_trafo ,
.Nm mouseinterval
.Nd Curses mouse interface
.Sh LIBRARY
.Lb libcurses
.Sh SYNOPSIS
.In curses.h
.Ft bool
.Fn has_mouse "void"
.Ft int
.Fn getmouse "MEVENT *event"
.Ft int
.Fn ungetmouse "MEVENT *event"
.Ft mmask_t
.Fn mousemask "mmask_t newmask" "mmask_t *oldmask"
.Ft bool
.Fn wenclose "const WINDOW *win" "int y" "int x"
.Ft bool
.Fn mouse_trafo "int *y" "int *x" "bool to_screen"
.Ft bool
.Fn wmouse_trafo "const WINDOW *win" "int *y" "int *x" "bool to_screen"
.Ft int
.Fn mouseinterval "int erval"
.Sh DESCRIPTION
This is the curses interface to mouse events.
Mouse events are reported via the
.Dv KEY_MOUSE
value in the
.Xr wgetch 3
input stream.
.Pp
The
.Fn has_mouse
function returns true if the mouse support has been initialised for the
terminal, otherwise false.
.Pp
The
.Fn getmouse
function reads a mouse event.
The
.Fa x
and
.Fa y
values are screen relative and the state mask will have exactly one bit set
to represent the event type.
The
.Fn ungetmouse
function behave like
.Xr ungetch 3
and pushes the mouse event into the input stream.
.Pp
The
.Fn mousemask
function sets the mouse events to be reported.
By default, there are no mouse events reported.
It returns a mask indicating which of the specified mouse events can be
reported, zero indicating a failure.
If oldmask is given, it is filled with the previous mouse event mask.
.Pp
The
.Fn wenclose
function returns true if the screen relative
.Fa x
and
.Fa y
co-ordinates are enclosed by the window
.Fa win ,
otherwise false.
.Pp
The
.Fn wmouse_trafo
function transforms the
.Fa x
and
.Fa y
co-ordinates from screen relative to window relative or vice versa
depending on the value of
.Fa to_screen .
If the co-ordinates are not enclosed by the window
.Fa win
then false is returned, otherwise the
.Fa x
and
.Fa y
values are transformed and true is returned.
The
.Fn mouse_trainfo
function calls
.Fn wmouse_trainfo
using
.Va stdscr
for
.Fa win .
.Pp
The
.Fn mouseinterval
function sets the maximum time that can elapse between press and release
events, which determins a click.
The value is in thousands of seconds.
The default value is one fifth of a second.
The returned value is the old value.
.Sh RETURN VALUES
Unless otherwise noted, the functions that return an int will return one of
the following values:
.Pp
.Bl -tag -width ERR -compact
.It Er OK
The function completed successfully.
.It Er ERR
An error occurred in the function.
.El
.Sh SEE ALSO
.Xr wsmouse 4
.Sh STANDARDS
These functions are ncurses extensions to the Curses library.
.Sh HISTORY
The mouse functions were added in
.Nx 10.0 .
.Sh BUGS
There is currently no actual mouse support,
.Fn has_mouse
will always return false.