Only xclick can catch callback execution.
[scilab.git] / scilab / modules / graphics / help / en_US / interaction / xgetmouse.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Serge Steer
5  * Copyright (C) 2008 - INRIA - Vincent COUVERT
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="xgetmouse">
15     <refnamediv>
16         <refname>xgetmouse</refname>
17         <refpurpose>get the mouse events and current position</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[rep [,win]]=xgetmouse([sel])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>sel</term>
28                 <listitem>
29                     <para>
30                         boolean vector <literal>[getmotion, getrelease]</literal>. default
31                         value is <literal>[%t, %f]</literal>
32                     </para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>rep</term>
37                 <listitem>
38                     <para>vector of size 3, [x,y,ibutton].</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>win</term>
43                 <listitem>
44                     <para>number of the figure where the event occurred.</para>
45                 </listitem>
46             </varlistentry>
47         </variablelist>
48     </refsection>
49     <refsection>
50         <title>Description</title>
51         <para>
52           Despite <literal>xclick</literal>, <literal>xgetmouse</literal> does not prevent callback menu to be executed.
53         </para>
54         <para>
55             If the mouse pointer is located in the current graphics window, <literal>xgetmouse</literal> returns
56             in <literal>rep</literal> the current pointer position (x,y) and the value <literal>ibutton</literal>.
57
58             The <literal>ibutton</literal> value indicates the event type:
59         </para>
60         <variablelist>
61             <varlistentry>
62                 <term>ibutton==0</term>
63                 <listitem>
64                     <para>Left mouse button has been pressed</para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>ibutton==1</term>
69                 <listitem>
70                     <para>Middle mouse button has been pressed</para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>ibutton==2</term>
75                 <listitem>
76                     <para>Right mouse button has been pressed</para>
77                     <para/>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>ibutton==3</term>
82                 <listitem>
83                     <para>Left mouse button has been clicked</para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>ibutton==4</term>
88                 <listitem>
89                     <para>Middle mouse button has been clicked</para>
90                 </listitem>
91             </varlistentry>
92             <varlistentry>
93                 <term>ibutton==5</term>
94                 <listitem>
95                     <para>Right mouse button has been clicked</para>
96                     <para/>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>ibutton==10</term>
101                 <listitem>
102                     <para>Left mouse button has been double-clicked</para>
103                 </listitem>
104             </varlistentry>
105             <varlistentry>
106                 <term>ibutton==11</term>
107                 <listitem>
108                     <para>Middle mouse button has been double-clicked</para>
109                 </listitem>
110             </varlistentry>
111             <varlistentry>
112                 <term>ibutton==12</term>
113                 <listitem>
114                     <para>Right mouse button has been double-clicked</para>
115                     <para/>
116                 </listitem>
117             </varlistentry>
118             <varlistentry>
119                 <term>ibutton==-5</term>
120                 <listitem>
121                     <para>Left mouse button has been released</para>
122                 </listitem>
123             </varlistentry>
124             <varlistentry>
125                 <term>ibutton==-4</term>
126                 <listitem>
127                     <para>Middle mouse button has been released</para>
128                 </listitem>
129             </varlistentry>
130             <varlistentry>
131                 <term>ibutton==-3</term>
132                 <listitem>
133                     <para>Right mouse button has been released</para>
134                     <para/>
135                 </listitem>
136             </varlistentry>
137             <varlistentry>
138                 <term>ibutton==-1</term>
139                 <listitem>
140                     <para>pointer has moved</para>
141                     <para/>
142                 </listitem>
143             </varlistentry>
144             <varlistentry>
145                 <term>ibutton &gt; =32</term>
146                 <listitem>
147                     <para>key with ascii code ascii(ibutton) has been pressed</para>
148                 </listitem>
149             </varlistentry>
150             <varlistentry>
151                 <term>ibutton &lt; =-32</term>
152                 <listitem>
153                     <para>key with ascii code ascii(-ibutton)   has been released</para>
154                     <para/>
155                 </listitem>
156             </varlistentry>
157             <varlistentry>
158                 <term>ibutton &gt; =1000+32</term>
159                 <listitem>
160                     <para>key with ascii code ascii(ibutton-1000) has been pressed while CTRL
161                         key pressed
162                     </para>
163                 </listitem>
164             </varlistentry>
165             <varlistentry>
166                 <term>ibutton==-1000</term>
167                 <listitem>
168                     <para>graphic window has been closed</para>
169                 </listitem>
170             </varlistentry>
171         </variablelist>
172         <para>
173             WARNING: In previous versions of Scilab (&lt;5.0), the user could give a flag to precise if the mouse click event queue had to be cleared when entering xgetmouse.
174             This option has been removed in Scilab 5.1.
175         </para>
176     </refsection>
177     <refsection>
178         <title>Examples</title>
179         <programlisting role="example"><![CDATA[
180 //  rectangle selection
181 clf();  // erase/create window
182 a=gca();a.data_bounds=[0 0;100 100];//set user coordinates
183 xtitle(" drawing a rectangle ") //add a title
184 show_window(); //put the window on the top
185
186 [b,xc,yc]=xclick(); //get a point
187 xrect(xc,yc,0,0) //draw a rectangle entity
188 r=gce();// the handle of the rectangle
189 rep=[xc,yc,-1];first=%f;
190
191 while rep(3)==-1 do // mouse just moving ...
192   rep=xgetmouse();
193   xc1=rep(1);yc1=rep(2);
194   ox=min(xc,xc1);
195   oy=max(yc,yc1);
196   w=abs(xc-xc1);h=abs(yc-yc1);
197   r.data=[ox,oy,w,h]; //change the retangle origin, width a height
198   first=%f;
199 end
200  ]]></programlisting>
201     </refsection>
202     <refsection role="see also">
203         <title>See Also</title>
204         <simplelist type="inline">
205             <member>
206                 <link linkend="locate">locate</link>
207             </member>
208             <member>
209                 <link linkend="xclick">xclick</link>
210             </member>
211             <member>
212                 <link linkend="seteventhandler">seteventhandler</link>
213             </member>
214         </simplelist>
215     </refsection>
216 </refentry>