ncurses 4.1
[ncurses.git] / Ada95 / html / curs_mouse.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
3 <PRE>
4        <STRONG>getmouse</STRONG>,  <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG> - mouse interface through
5        curses
6
7
8 </PRE>
9 <H2>SYNOPSIS</H2><PRE>
10        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
11
12        <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG>
13
14        <STRONG>typedef</STRONG> <STRONG>struct</STRONG>
15        <STRONG>{</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>
19        <STRONG>}</STRONG>
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>
26
27
28 </PRE>
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.
33
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
41        mouse event mask.
42
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.
46
47        Here are the mouse event type masks:
48
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
69        movement
70
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
81        event type.
82
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.
87
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.
93
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.
99
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.
104
105
106
107 </PRE>
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.
111
112
113 </PRE>
114 <H2>PORTABILITY</H2><PRE>
115        These calls were designed for  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>,  and  are  not
116
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.
123
124        The  order  of the <STRONG>MEVENT</STRONG> structure members is not guaran-
125        teed.  Additional fields may be added to the structure  in
126        the future.
127
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>).
134
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
138        gloves.
139
140
141 </PRE>
142 <H2>BUGS</H2><PRE>
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
146        the string read.
147
148        Mouse events under xterm will not be detected correctly in
149        a window with its keypad bit off.
150
151
152 </PRE>
153 <H2>SEE ALSO</H2><PRE>
154        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>.
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172 </PRE>
173 </BODY>
174 </HTML>