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