81dee1c34c7d4a613e6a4e64a0e7d73770ac5657
[scilab.git] / scilab / modules / graphics / help / en_US / interaction / event_handler_functions.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 - Jean-Baptiste Silvy
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <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="eventhandlerfunctions">
14     <refnamediv>
15         <refname>event handler functions</refname>
16         <refpurpose>
17             Prototype of functions which may be used as event handler.
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>event_handler_function(win,x,y,ibut)</synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>win</term>
29                 <listitem>
30                     <para>window number where the event had occurred.</para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>x</term>
35                 <listitem>
36                     <para>X coordinate in pixels of the mouse pointer when the events occurred.</para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>y</term>
41                 <listitem>
42                     <para>Y coordinate in pixels of the mouse pointer when the events occurred.</para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>ibut</term>
47                 <listitem>
48                     <para>number corresponding to the event type.</para>
49                 </listitem>
50             </varlistentry>
51         </variablelist>
52     </refsection>
53     <refsection>
54         <title>Description</title>
55         <para>
56             When the event handler mode is enable, Scilab will call the specified event handler
57             function each time an event occures in the graphic window. The event handler function
58             must comply with the above prototype. Each time an event occurred, the function is called
59             and its four parameters are set accordingly to the window number, mouse position and
60             type of event.
61         </para>
62         <para>
63             The <literal>ibut</literal> parameter takes one of the following value depending on event type:
64         </para>
65         <variablelist>
66             <varlistentry>
67                 <term>ibut==0</term>
68                 <listitem>
69                     <para>Left mouse button has been pressed</para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>ibut==1</term>
74                 <listitem>
75                     <para>Middle mouse button has been pressed</para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>ibut==2</term>
80                 <listitem>
81                     <para>Right mouse button has been pressed</para>
82                     <para/>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>ibut==3</term>
87                 <listitem>
88                     <para>Left mouse button has been clicked</para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>ibut==4</term>
93                 <listitem>
94                     <para>Middle mouse button has been clicked</para>
95                 </listitem>
96             </varlistentry>
97             <varlistentry>
98                 <term>ibut==5</term>
99                 <listitem>
100                     <para>Right mouse button has been clicked</para>
101                     <para/>
102                 </listitem>
103             </varlistentry>
104             <varlistentry>
105                 <term>ibut==10</term>
106                 <listitem>
107                     <para>Left mouse button has been double-clicked</para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>ibut==11</term>
112                 <listitem>
113                     <para>Middle mouse button has been double-clicked</para>
114                 </listitem>
115             </varlistentry>
116             <varlistentry>
117                 <term>ibut==12</term>
118                 <listitem>
119                     <para>Right mouse button has been double-clicked</para>
120                     <para/>
121                 </listitem>
122             </varlistentry>
123             <varlistentry>
124                 <term>ibut==-5</term>
125                 <listitem>
126                     <para>Left mouse button has been released</para>
127                 </listitem>
128             </varlistentry>
129             <varlistentry>
130                 <term>ibut==-4</term>
131                 <listitem>
132                     <para>Middle mouse button has been released</para>
133                 </listitem>
134             </varlistentry>
135             <varlistentry>
136                 <term>ibut==-3</term>
137                 <listitem>
138                     <para>Right mouse button has been released</para>
139                     <para/>
140                 </listitem>
141             </varlistentry>
142             <varlistentry>
143                 <term>ibut==-1</term>
144                 <listitem>
145                     <para>mouse pointer has moved</para>
146                     <para/>
147                 </listitem>
148             </varlistentry>
149             <varlistentry>
150                 <term>ibut &gt; =32</term>
151                 <listitem>
152                     <para>key with ascii code ascii(ibut) has been pressed</para>
153                 </listitem>
154             </varlistentry>
155             <varlistentry>
156                 <term>ibut &lt; =-32</term>
157                 <listitem>
158                     <para>key with ascii code ascii(-ibut)   has been released</para>
159                     <para/>
160                 </listitem>
161             </varlistentry>
162             <varlistentry>
163                 <term>ibut &gt; =1000+32</term>
164                 <listitem>
165                     <para>key with ascii code ascii(ibut-1000) has been pressed while CTRL
166                         key pressed
167                     </para>
168                 </listitem>
169             </varlistentry>
170             <varlistentry>
171                 <term>ibut==-1000</term>
172                 <listitem>
173                     <para>graphic window has been closed</para>
174                 </listitem>
175             </varlistentry>
176         </variablelist>
177         <para>
178             For example, let say that the name of the event handler function is fooHandler
179             for window number 0. A left click in the window at position [100,150] (in pixels)
180             will be equivalent as calling fooHandler( 0, 100, 150, 3 ).
181         </para>
182         <para>
183             See <link linkend="figure_properties">figure_properties</link> or <link linkend="seteventhandler">seteventhandler</link> for information on
184             how to specify the event_handler name.
185         </para>
186     </refsection>
187     <refsection>
188         <title>Examples</title>
189         <programlisting role="example"><![CDATA[ 
190 function my_eventhandler(win,x,y,ibut)
191   if ibut==-1000 then return,end
192   [x,y]=xchange(x,y,'i2f')
193   xinfo(msprintf('Event code %d at mouse position is (%f,%f)',ibut,x,y))
194 endfunction
195
196 plot2d()
197 fig = gcf() ;
198 fig.event_handler = 'my_eventhandler' ;
199 fig.event_handler_enable = "on" ;
200 //now:
201 //   -  move the mouse over the graphic window
202 //   -  press and release keys shifted or not with Ctrl pressed or not
203 //   -  press button, wait a little release
204 //   -  press and release button
205 //   -  double-click button
206
207 fig.event_handler_enable = "off" ; //suppress the event handler
208  ]]></programlisting>
209     </refsection>
210     <refsection role="see also">
211         <title>See Also</title>
212         <simplelist type="inline">
213             <member>
214                 <link linkend="figure_properties">figure_properties</link>
215             </member>
216             <member>
217                 <link linkend="seteventhandler">seteventhandler</link>
218             </member>
219             <member>
220                 <link linkend="xgetmouse">xgetmouse</link>
221             </member>
222             <member>
223                 <link linkend="xclick">xclick</link>
224             </member>
225         </simplelist>
226     </refsection>
227 </refentry>