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 BUT-
51 TON1_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 BUTTON2_CLICKED
56 mouse button 2 clicked BUTTON2_DOUBLE_CLICKED mouse
57 button 2 double clicked BUTTON2_TRIPLE_CLICKED mouse
58 button 2 triple clicked BUTTON3_PRESSED mouse button 3
59 down BUTTON3_RELEASED mouse button 3 up BUTTON3_CLICKED
60 button 3 triple clicked BUTTON4_PRESSED mouse button 4
61 down BUTTON4_RELEASED mouse button 4 up BUTTON4_CLICKED
62 mouse button 4 clicked BUTTON4_DOUBLE_CLICKED mouse
63 button 4 double clicked BUTTON4_TRIPLE_CLICKED mouse
64 button 4 triple clicked BUTTON_SHIFT shift was down dur-
65 ing button state change BUTTON_CTRL control was down
66 during button state change BUTTON_ALT alt was down
67 during button state change ALL_MOUSE_EVENTS report all
68 button state changes REPORT_MOUSE_POSITION report mouse
71 Once a class of mouse events have been made visible in a
72 window, calling the <STRONG>wgetch</STRONG> function on that window may
73 return <STRONG>KEY_MOUSE</STRONG> as an indicator that a mouse event has
74 been queued. To read the event data and pop the event off
75 the queue, call <STRONG>getmouse</STRONG>. This function will return <STRONG>OK</STRONG> if
76 a mouse event is actually visible in the given window, <STRONG>ERR</STRONG>
77 otherwise. When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited
78 as y and x in the event structure coordinates will be
79 screen-relative character-cell coordinates. The returned
80 state mask will have exactly one bit set to indicate the
83 The <STRONG>ungetmouse</STRONG> function behaves analogously to <STRONG>ungetch</STRONG>.
84 It pushes a <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and
85 associates with that event the given state data and
86 screen-relative character-cell coordinates.
88 The <STRONG>wenclose</STRONG> function tests whether a given pair of
89 screen-relative character-cell coordinates is enclosed by
90 a given window, returning TRUE if it is and FALSE other-
91 wise. It is useful for determining what subset of the
92 screen windows enclose the location of a mouse event.
94 The <STRONG>mouseinterval</STRONG> function sets the maximum time (in thou-
95 sands of a second) that can elapse between press and
96 release events in order for them to be recognized as a
97 click. This function returns the previous interval value.
98 The default is one fifth of a second.
100 Note that mouse events will be ignored when input is in
101 cooked mode, and will cause an error beep when cooked mode
102 is being simulated in a window by a function such as <STRONG>get-</STRONG>
103 <STRONG>str</STRONG> that expects a linefeed for input-loop termination.
108 <H2>RETURN VALUE</H2><PRE>
109 All routines return the integer <STRONG>ERR</STRONG> upon failure or <STRONG>OK</STRONG>
110 upon successful completion.
114 <H2>PORTABILITY</H2><PRE>
115 These calls were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and are not
117 The feature macro <STRONG>NCURSES_MOUSE_VERSION</STRONG> is provided so the
118 preprocessor can be used to test whether these features
119 are present (its value is 1). NOTE: THIS INTERFACE IS
120 EXPERIMENTAL AND IS SUBJECT TO CHANGE WITHOUT NOTICE! If
121 the interface is changed, the value of <STRONG>NCURSES_MOUSE_VER-</STRONG>
122 <STRONG>SION</STRONG> will be incremented.
124 The order of the <STRONG>MEVENT</STRONG> structure members is not guaran-
125 teed. Additional fields may be added to the structure in
128 Under <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, these calls are implemented using
129 either xterm's built-in mouse-tracking API or Alessandro
130 Rubini's gpm server. If you are using something other
131 than xterm there is no gpm daemon running on your machine,
132 mouse events will not be visible to <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> (and the
133 <STRONG>wmousemask</STRONG> function will always return <STRONG>0</STRONG>).
135 The z member in the event structure is not presently used.
136 It is intended for use with touch screens (which may be
137 pressure-sensitive) or with 3D-mice/trackballs/power
143 Mouse events under xterm will not in fact be ignored dur-
144 ing cooked mode, if they have been enabled by <STRONG>wmousemask</STRONG>.
145 Instead, the xterm mouse report sequence will appear in
148 Mouse events under xterm will not be detected correctly in
149 a window with its keypad bit off.
153 <H2>SEE ALSO</H2><PRE>
154 <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>.