[src/trunk]: src/lib/libcurses Add missing man page for curses mouse functions.

[roy <roy%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7957a8276ce1
branches:  trunk
changeset: 1008466:7957a8276ce1
user:      roy <roy%NetBSD.org@localhost>
date:      Mon Mar 23 15:32:56 2020 +0000

description:
Add missing man page for curses mouse functions.

diffstat:

 lib/libcurses/curses_mouse.3 |  161 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 161 insertions(+), 0 deletions(-)

diffs (165 lines):

diff -r b7e529500284 -r 7957a8276ce1 lib/libcurses/curses_mouse.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libcurses/curses_mouse.3      Mon Mar 23 15:32:56 2020 +0000
@@ -0,0 +1,161 @@
+.\"    $NetBSD: curses_mouse.3,v 1.1 2020/03/23 15:32:56 roy 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"
+.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 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.