ncurses 5.5

[ncurses.git] / man / curs_mouse.3x

diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index b15507629b92f7d76e0b5dbc7d8096172c70f221..865fab1ad88fd6f4faf1a8e92df1d951c9157fd3 100644 (file)
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2002,2003 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2003,2005 Free Software Foundation, Inc.              *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
@@ -27,13 +27,17 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_mouse.3x,v 1.24 2003/12/27 18:47:54 tom Exp $
+.\" $Id: curs_mouse.3x,v 1.28 2005/05/15 16:18:19 tom Exp $
 .TH curs_mouse 3X ""
+.na
+.hy 0
 .SH NAME
 \fBgetmouse\fR, \fBungetmouse\fR,
 \fBmousemask\fR, \fBwenclose\fR,
 \fBmouse_trafo\fR, \fBwmouse_trafo\fR,
 \fBmouseinterval\fR - mouse interface through curses
+.ad
+.hy
 .SH SYNOPSIS
 .nf
 \fB#include <curses.h>
@@ -85,7 +89,7 @@ As a side effect, setting a zero mousemask may turn off the mouse pointer;
 setting a nonzero mask may turn it on.
 Whether this happens is device-dependent.
 .PP
-Here are the mouse event type masks:
+Here are the mouse event type masks which may be defined:
 .PP
 .TS
 l l
@@ -97,26 +101,37 @@ 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   shift was down during button state change
 BUTTON_CTRL    control was down during button state change
 BUTTON_ALT     alt was down during button state change
 ALL_MOUSE_EVENTS       report all button state changes
 REPORT_MOUSE_POSITION  report mouse movement
+_
 .TE
 .PP
 Once a class of mouse events have been made visible in a window,
@@ -172,8 +187,9 @@ successful.
 The \fBmouseinterval\fR function sets the maximum time (in thousands of a
 second) that can elapse between press and release events for them to
 be recognized as a click.
-Use \fBmouseinterval(-1)\fR to disable click resolution.
+Use \fBmouseinterval(0)\fR to disable click resolution.
 This function returns the previous interval value.
+Use \fBmouseinterval(-1)\fR to obtain the interval without altering it.
 The default is one sixth of a second.
 .PP
 Note that mouse events will be ignored when input is in cooked mode, and will
@@ -181,11 +197,28 @@ cause an error beep when cooked mode is being simulated in a window by a
 function such as \fBgetstr\fR that expects a linefeed for input-loop
 termination.
 .SH RETURN VALUE
-\fBgetmouse\fR, \fBungetmouse\fR and \fBmouseinterval\fR
+\fBgetmouse\fR and \fBungetmouse\fR
 return the integer \fBERR\fR upon failure or \fBOK\fR
 upon successful completion.
-\fBmousemask\fR returns the
-mask of reportable events.
+.RS
+.TP 5
+\fBgetmouse\fP
+returns an error.
+If no mouse driver was initialized, or
+if the mask parameter is zero,
+.TP 5
+\fBungetmouse\fP
+returns an error if the FIFO is full.
+.RE
+.PP
+\fBmousemask\fR
+returns the mask of reportable events.
+.PP
+\fBmouseinterval\fR
+returns the previous interval value, unless
+the terminal was not initialized.
+In that case, it returns the maximum interval value (166).
+.PP
 \fBwenclose\fR and \fBwmouse_trafo\fR
 are boolean functions returning \fBTRUE\fR or \fBFALSE\fR depending
 on their test result.
@@ -194,9 +227,22 @@ These calls were designed for \fBncurses\fR(3X), and are not found in SVr4
 curses, 4.4BSD curses, or any other previous version of curses.
 .PP
 The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor
-can be used to test whether these features are present (its value is 1).
+can be used to test whether these features are present.
 If the interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fR will be
 incremented.
+These values for \fBNCURSES_MOUSE_VERSION\fR may be
+specified when configuring ncurses:
+.RS
+.TP 3
+1
+has definitions for reserved events.
+The mask uses 28 bits.
+.TP 3
+2
+adds definitions for button 5,
+removes the definitions for reserved events.
+The mask uses 29 bits.
+.RE
 .PP
 The order of the \fBMEVENT\fR structure members is not guaranteed.
 Additional fields may be added to the structure in the future.