2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
4 <STRONG>getmouse</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG> - mouse interface through
10 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
12 <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG>
14 <STRONG>typedef</STRONG> <STRONG>struct</STRONG>
16 <STRONG>short</STRONG> <STRONG>id;</STRONG> <EM>/*</EM> <EM>ID</EM> <EM>to</EM> <EM>distinguish</EM> <EM>multiple</EM> <EM>devices</EM> <EM>*/</EM>
17 <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG> <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM>
18 <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG> <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM>
20 <STRONG>MEVENT;</STRONG>
21 <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
22 <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*event);</STRONG>
23 <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <STRONG>newmask,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*oldmask);</STRONG>
24 <STRONG>bool</STRONG> <STRONG>wenclose(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x)</STRONG>
25 <STRONG>int</STRONG> <STRONG>mouseinterval(int</STRONG> <STRONG>erval)</STRONG>
29 <H2>DESCRIPTION</H2><PRE>
30 These functions provide an interface to mouse events from
31 <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>. Mouse events are represented by <STRONG>KEY_MOUSE</STRONG>
32 pseudo-key values in the <STRONG>wgetch</STRONG> input stream.
34 To make mouse events visible, use the <STRONG>mousemask</STRONG> function.
35 This will set the mouse events to be reported. By
36 default, no mouse events are reported. The function will
37 return a mask to indicate which of the specified mouse
38 events can be reported; on complete failure it returns 0.
39 If oldmask is non-NULL, this function fills the indicated
40 location with the previous value of the given window's
43 As a side effect, setting a zero mousemask may turn off
44 the mouse pointer; setting a nonzero mask may turn it on.
45 Whether this happens is device-dependent.
47 Here are the mouse event type masks:
49 l l _ _ l l. <EM>Name</EM> <EM>Description</EM> BUTTON1_PRESSED mouse
50 button 1 down BUTTON1_RELEASED mouse button 1 up
51 BUTTON1_CLICKED mouse button 1 clicked
52 BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
53 BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
54 BUTTON2_PRESSED mouse button 2 down
55 BUTTON2_RELEASED mouse button 2 up
56 BUTTON2_CLICKED mouse button 2 clicked
57 BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
58 BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
59 BUTTON3_PRESSED mouse button 3 down
60 BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
61 BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
62 BUTTON4_PRESSED mouse button 4 down
63 BUTTON4_RELEASED mouse button 4 up
64 BUTTON4_CLICKED mouse button 4 clicked
65 BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
66 BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
67 BUTTON_SHIFT shift was down during button state change
68 BUTTON_CTRL control was down during button state change
69 BUTTON_ALT alt was down during button state change
70 ALL_MOUSE_EVENTS report all button state changes
71 REPORT_MOUSE_POSITION report mouse movement
73 Once a class of mouse events have been made visible in a
74 window, calling the <STRONG>wgetch</STRONG> function on that window may
75 return <STRONG>KEY_MOUSE</STRONG> as an indicator that a mouse event has
76 been queued. To read the event data and pop the event off
77 the queue, call <STRONG>getmouse</STRONG>. This function will return <STRONG>OK</STRONG> if
78 a mouse event is actually visible in the given window, <STRONG>ERR</STRONG>
79 otherwise. When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited
80 as y and x in the event structure coordinates will be
81 screen-relative character-cell coordinates. The returned
82 state mask will have exactly one bit set to indicate the
85 The <STRONG>ungetmouse</STRONG> function behaves analogously to <STRONG>ungetch</STRONG>.
86 It pushes a <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and
87 associates with that event the given state data and
88 screen-relative character-cell coordinates.
90 The <STRONG>wenclose</STRONG> function tests whether a given pair of
91 screen-relative character-cell coordinates is enclosed by
92 a given window, returning TRUE if it is and FALSE other-
93 wise. It is useful for determining what subset of the
94 screen windows enclose the location of a mouse event.
96 The <STRONG>mouseinterval</STRONG> function sets the maximum time (in thou-
97 sands of a second) that can elapse between press and
98 release events in order for them to be recognized as a
99 click. This function returns the previous interval value.
100 The default is one fifth of a second.
102 Note that mouse events will be ignored when input is in
103 cooked mode, and will cause an error beep when cooked mode
104 is being simulated in a window by a function such as <STRONG>get-</STRONG>
105 <STRONG>str</STRONG> that expects a linefeed for input-loop termination.
110 <H2>RETURN VALUE</H2><PRE>
111 All routines return the integer <STRONG>ERR</STRONG> upon failure or <STRONG>OK</STRONG>
112 upon successful completion.
114 These calls were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>, and are not
115 found in SVr4 curses, 4.4BSD curses, or any other previous
118 The feature macro <STRONG>NCURSES_MOUSE_VERSION</STRONG> is provided so the
119 preprocessor can be used to test whether these features
120 are present (its value is 1). NOTE: THIS INTERFACE IS
121 EXPERIMENTAL AND IS SUBJECT TO CHANGE WITHOUT NOTICE! If
122 the interface is changed, the value of <STRONG>NCURSES_MOUSE_VER-</STRONG>
123 <STRONG>SION</STRONG> will be incremented.
125 The order of the <STRONG>MEVENT</STRONG> structure members is not guaran-
126 teed. Additional fields may be added to the structure in
129 Under <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG>, these calls are implemented using
130 either xterm's built-in mouse-tracking API or Alessandro
131 Rubini's gpm server. If you are using something other
132 than xterm there is no gpm daemon running on your machine,
133 mouse events will not be visible to <STRONG><A HREF="ncurses.3x.html">ncurses(3X)</A></STRONG> (and the
134 <STRONG>wmousemask</STRONG> function will always return <STRONG>0</STRONG>).
136 The z member in the event structure is not presently used.
137 It is intended for use with touch screens (which may be
138 pressure-sensitive) or with 3D-mice/trackballs/power
144 Mouse events under xterm will not in fact be ignored dur-
145 ing cooked mode, if they have been enabled by <STRONG>wmousemask</STRONG>.
146 Instead, the xterm mouse report sequence will appear in
149 Mouse events under xterm will not be detected correctly in
150 a window with its keypad bit off.
154 <H2>SEE ALSO</H2><PRE>
155 <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>.