From d55eff9600e2e07a9ccb08828f0fc48662182a1a Mon Sep 17 00:00:00 2001 From: William McBrine Date: Thu, 28 Dec 2006 10:35:05 +0000 Subject: [PATCH] Documentation for the rest of the ncurses mouse interface. --- pdcurses/mouse.c | 107 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 32 deletions(-) diff --git a/pdcurses/mouse.c b/pdcurses/mouse.c index a6407ee2..46db4194 100644 --- a/pdcurses/mouse.c +++ b/pdcurses/mouse.c @@ -14,7 +14,7 @@ #include #include -RCSID("$Id: mouse.c,v 1.38 2006/12/28 09:39:55 wmcbrine Exp $"); +RCSID("$Id: mouse.c,v 1.39 2006/12/28 10:35:05 wmcbrine Exp $"); /*man-start************************************************************** @@ -40,42 +40,57 @@ RCSID("$Id: mouse.c,v 1.38 2006/12/28 09:39:55 wmcbrine Exp $"); int ungetmouse(MEVENT *event); PDCurses Description: - Classic PDCurses mouse interface: mouse_set(), mouse_on(), - mouse_off(), request_mouse_pos(), map_button(), - wmouse_position(), getmouse(), and getbmap(). These functions - are intended to be based on Sys V mouse functions; however, - those are undocumented. + As of PDCurses 3.0, there are two separate mouse interfaces: the + classic interface, which is based on the undocumented Sys V + mouse functions; and an ncurses-compatible interface. Both are + active at all times, and you can mix and match functions from + each, though it's not recommended. The ncurses interface is + essentially an emulation layer built on top of the classic + interface; it's here to allow easier porting of ncurses apps. - mouse_set(), mouse_on() and mouse_off() are analagous to - attrset(), attron() and attroff(). These functions set the - mouse button events to trap. The button masks used in these - functions are defined in curses.h and can be or'ed together. + The classic interface: mouse_set(), mouse_on(), mouse_off(), + request_mouse_pos(), map_button(), wmouse_position(), + getmouse(), and getbmap(). An application using this interface + would start by calling mouse_set() or mouse_on() with a non-zero + value, often ALL_MOUSE_EVENTS. Then it would check for a + KEY_MOUSE return from getch(). If found, it would call + request_mouse_pos() to get the current mouse status. + + mouse_set(), mouse_on() and mouse_off() are analagous to + attrset(), attron() and attroff(). These functions set the + mouse button events to trap. The button masks used in these + functions are defined in curses.h and can be or'ed together. They are the group of masks starting with BUTTON1_RELEASED. - request_mouse_pos() requests curses to fill in the Mouse_status + request_mouse_pos() requests curses to fill in the Mouse_status structure with the current state of the mouse. - map_button() enables the specified mouse action to activate the - Soft Label Keys if the action occurs over the area of the screen - where the Soft Label Keys are displayed. The mouse actions are + map_button() enables the specified mouse action to activate the + Soft Label Keys if the action occurs over the area of the screen + where the Soft Label Keys are displayed. The mouse actions are defined in curses.h in the group that starts with BUTTON_RELEASED. - wmouse_position() determines if the current mouse position is - within the window passed as an argument. If the mouse is - outside the current window, -1 is returned in the y and x - arguments; otherwise the y and x coordinates of the mouse - (relative to the top left corner of the window) are returned in + wmouse_position() determines if the current mouse position is + within the window passed as an argument. If the mouse is + outside the current window, -1 is returned in the y and x + arguments; otherwise the y and x coordinates of the mouse + (relative to the top left corner of the window) are returned in y and x. - getmouse() returns the current status of the trapped mouse + getmouse() returns the current status of the trapped mouse buttons as set by mouse_set() or mouse_on(). - getbmap() returns the current status of the button action used - to map a mouse action to the Soft Label Keys as set by the + getbmap() returns the current status of the button action used + to map a mouse action to the Soft Label Keys as set by the map_button() function. - Functions emulating ncurses: mouseinterval(), wenclose(), - wmouse_trafo(), mouse_trafo(). + The ncurses interface: mouseinterval(), wenclose(), + wmouse_trafo(), mouse_trafo(), mousemask(), nc_getmouse(), and + ungetmouse(). A typical application using this interface would + start by calling mousemask() with a non-zero value, often + ALL_MOUSE_EVENTS. Then it would check for a KEY_MOUSE return + from getch(). If found, it would call nc_getmouse() to get the + current mouse status. mouseinterval() sets the timeout for a mouse click. On all current platforms, PDCurses receives mouse button press and @@ -85,24 +100,49 @@ RCSID("$Id: mouse.c,v 1.38 2006/12/28 09:39:55 wmcbrine Exp $"); waiting, it will wait for the timeout interval, then check again for a release. A press followed by a release is reported as BUTTON_CLICKED; otherwise it's passed through as BUTTON_PRESSED. - The default timeout is 100ms; valid values are 0 (no clicks + The default timeout is 150ms; valid values are 0 (no clicks reported) through 1000ms. In x11, the timeout can also be set via the clickPeriod resource. The return value from mouseinterval() is the old timeout. To check the old value - without setting a new one, call it with a parameter of -1. + without setting a new one, call it with a parameter of -1. Note + that although there's no classic equivalent for this function + (apart from the clickPeriod resource), the value set applies in + both interfaces. - wenclose() reports whether the given screen-relative y, x + wenclose() reports whether the given screen-relative y, x coordinates fall within the given window. - wmouse_trafo() converts between screen-relative and window- - relative coordinates. A to_screen parameter of TRUE means to - convert from window to screen; otherwise the reverse. The - function returns FALSE if the coordinates aren't within the - window, or if any of the parameters are NULL. The coordinates + wmouse_trafo() converts between screen-relative and window- + relative coordinates. A to_screen parameter of TRUE means to + convert from window to screen; otherwise the reverse. The + function returns FALSE if the coordinates aren't within the + window, or if any of the parameters are NULL. The coordinates have been converted when the function returns TRUE. mouse_trafo() is the stdscr version of wmouse_trafo(). + mousemask() is nearly equivalent to mouse_set(), but instead of + OK/ERR, it returns the value of the mask after setting it. (This + isn't necessarily the same value passed in, since the mask could + be altered on some platforms.) And if the second parameter is a + non-null pointer, mousemask() stores the previous mask value + there. Also, since the ncurses interface doesn't work with + PDCurses' BUTTON_MOVED events, mousemask() filters them out. + + nc_getmouse() returns the current mouse status in an MEVENT + struct. This is equivalent to ncurses' getmouse(), renamed to + avoid conflict with PDCurses' getmouse(). But if you define + NCURSES_MOUSE_VERSION (preferably as 2) before including + curses.h, it defines getmouse() to nc_getmouse(), along with a + few other redefintions needed for compatibility with ncurses + code. nc_getmouse() calls request_mouse_pos(), which (not + getmouse()) is the classic equivalent. + + ungetmouse() is the mouse equivalent of ungetch(). However, + PDCurses doesn't maintain a queue of mouse events; only one can + be pushed back, and it can overwrite or be overwritten by real + mouse events. + Portability X/Open BSD SYS V mouse_set - - 4.0 mouse_on - - 4.0 @@ -116,6 +156,9 @@ RCSID("$Id: mouse.c,v 1.38 2006/12/28 09:39:55 wmcbrine Exp $"); wenclose - - - wmouse_trafo - - - mouse_trafo - - - + mousemask - - - + nc_getmouse - - - + ungetmouse - - - **man-end****************************************************************/