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
 .\"***************************************************************************
 '\" 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            *
 .\"                                                                          *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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 ""
 .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
 .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>
 .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
 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
 .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
 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
 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
 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
 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
 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,
 .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.
 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.
 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
 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
 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.
 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.
 \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
 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.
 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.
 .PP
 The order of the \fBMEVENT\fR structure members is not guaranteed.
 Additional fields may be added to the structure in the future.