dcb955709581abd218cd8d213894dab8bb1a2cc5
[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             If the mouse pointer is located in the current graphics window, <literal>xgetmouse</literal> returns
53             in <literal>rep</literal> the current pointer position (x,y) and the value <literal>ibutton</literal>.
54             
55             The <literal>ibutton</literal> value indicates the event type:
56         </para>
57         <variablelist>
58             <varlistentry>
59                 <term>ibutton==0</term>
60                 <listitem>
61                     <para>Left mouse button has been pressed</para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>ibutton==1</term>
66                 <listitem>
67                     <para>Middle mouse button has been pressed</para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>ibutton==2</term>
72                 <listitem>
73                     <para>Right mouse button has been pressed</para>
74                     <para/>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>ibutton==3</term>
79                 <listitem>
80                     <para>Left mouse button has been clicked</para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>ibutton==4</term>
85                 <listitem>
86                     <para>Middle mouse button has been clicked</para>
87                 </listitem>
88             </varlistentry>
89             <varlistentry>
90                 <term>ibutton==5</term>
91                 <listitem>
92                     <para>Right mouse button has been clicked</para>
93                     <para/>
94                 </listitem>
95             </varlistentry>
96             <varlistentry>
97                 <term>ibutton==10</term>
98                 <listitem>
99                     <para>Left mouse button has been double-clicked</para>
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>ibutton==11</term>
104                 <listitem>
105                     <para>Middle mouse button has been double-clicked</para>
106                 </listitem>
107             </varlistentry>
108             <varlistentry>
109                 <term>ibutton==12</term>
110                 <listitem>
111                     <para>Right mouse button has been double-clicked</para>
112                     <para/>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>ibutton==-5</term>
117                 <listitem>
118                     <para>Left mouse button has been released</para>
119                 </listitem>
120             </varlistentry>
121             <varlistentry>
122                 <term>ibutton==-4</term>
123                 <listitem>
124                     <para>Middle mouse button has been released</para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>ibutton==-3</term>
129                 <listitem>
130                     <para>Right mouse button has been released</para>
131                     <para/>
132                 </listitem>
133             </varlistentry>
134             <varlistentry>
135                 <term>ibutton==-1</term>
136                 <listitem>
137                     <para>pointer has moved</para>
138                     <para/>
139                 </listitem>
140             </varlistentry>
141             <varlistentry>
142                 <term>ibutton &gt; =32</term>
143                 <listitem>
144                     <para>key with ascii code ascii(ibutton) has been pressed</para>
145                 </listitem>
146             </varlistentry>
147             <varlistentry>
148                 <term>ibutton &lt; =-32</term>
149                 <listitem>
150                     <para>key with ascii code ascii(-ibutton)   has been released</para>
151                     <para/>
152                 </listitem>
153             </varlistentry>
154             <varlistentry>
155                 <term>ibutton &gt; =1000+32</term>
156                 <listitem>
157                     <para>key with ascii code ascii(ibutton-1000) has been pressed while CTRL
158                         key pressed
159                     </para>
160                 </listitem>
161             </varlistentry>
162             <varlistentry>
163                 <term>ibutton==-1000</term>
164                 <listitem>
165                     <para>graphic window has been closed</para>
166                 </listitem>
167             </varlistentry>
168         </variablelist>
169         <para>
170             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.
171             This option has been removed in Scilab 5.1.
172         </para>
173     </refsection>
174     <refsection>
175         <title>Examples</title>
176         <programlisting role="example"><![CDATA[ 
177 //  rectangle selection
178 clf();  // erase/create window
179 a=gca();a.data_bounds=[0 0;100 100];//set user coordinates
180 xtitle(" drawing a rectangle ") //add a title
181 show_window(); //put the window on the top
182
183 [b,xc,yc]=xclick(); //get a point
184 xrect(xc,yc,0,0) //draw a rectangle entity
185 r=gce();// the handle of the rectangle
186 rep=[xc,yc,-1];first=%f;
187
188 while rep(3)==-1 do // mouse just moving ...
189   rep=xgetmouse();
190   xc1=rep(1);yc1=rep(2);
191   ox=min(xc,xc1);
192   oy=max(yc,yc1);
193   w=abs(xc-xc1);h=abs(yc-yc1);
194   r.data=[ox,oy,w,h]; //change the retangle origin, width a height
195   first=%f;
196 end
197  ]]></programlisting>
198     </refsection>
199     <refsection role="see also">
200         <title>See Also</title>
201         <simplelist type="inline">
202             <member>
203                 <link linkend="locate">locate</link>
204             </member>
205             <member>
206                 <link linkend="xclick">xclick</link>
207             </member>
208             <member>
209                 <link linkend="seteventhandler">seteventhandler</link>
210             </member>
211         </simplelist>
212     </refsection>
213 </refentry>