<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Jean-Baptiste Silvy
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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">
    <refnamediv>
        <refname>event handler functions</refname>
        <refpurpose>
            Prototype of functions which may be used as event handler.
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>event_handler_function(h,x,y,ibut)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                    <para>window number if the event occurred in an axe with a figure type parent. (DEPRECATED)</para>
                    <para>handle of the axe's parent where the event occurred.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>X coordinate in pixels of the mouse pointer when the events occurred.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>Y coordinate in pixels of the mouse pointer when the events occurred.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut</term>
                <listitem>
                    <para>number corresponding to the event type.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            When the event handler mode is enable, Scilab will call the specified event handler
            function each time an event occurs in the graphic window. The event handler function
            must comply with the above prototype. Each time an event occurred, the function is called
            and its four parameters are set accordingly to the window number, mouse position and
            type of event.
        </para>
        <para>
            The <literal>ibut</literal> parameter takes one of the following value depending on event type:
        </para>
        <variablelist>
            <varlistentry>
                <term>ibut==0</term>
                <listitem>
                    <para>Left mouse button has been pressed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==1</term>
                <listitem>
                    <para>Middle mouse button has been pressed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==2</term>
                <listitem>
                    <para>Right mouse button has been pressed</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==3</term>
                <listitem>
                    <para>Left mouse button has been clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==4</term>
                <listitem>
                    <para>Middle mouse button has been clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==5</term>
                <listitem>
                    <para>Right mouse button has been clicked</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==10</term>
                <listitem>
                    <para>Left mouse button has been double-clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==11</term>
                <listitem>
                    <para>Middle mouse button has been double-clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==12</term>
                <listitem>
                    <para>Right mouse button has been double-clicked</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==-5</term>
                <listitem>
                    <para>Left mouse button has been released</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==-4</term>
                <listitem>
                    <para>Middle mouse button has been released</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==-3</term>
                <listitem>
                    <para>Right mouse button has been released</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==-1</term>
                <listitem>
                    <para>mouse pointer has moved</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut &gt; =32</term>
                <listitem>
                    <para>key with ascii code ascii(ibut) has been pressed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut &lt; =-32</term>
                <listitem>
                    <para>key with ascii code ascii(-ibut)   has been released</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut &gt; =1000+32</term>
                <listitem>
                    <para>key with ascii code ascii(ibut-1000) has been pressed while CTRL
                        key pressed
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==-1000</term>
                <listitem>
                    <para>graphic window has been closed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibut==-10000</term>
                <listitem>
                    <para>Unmanaged event; it could be a drag and drop or a fast click and move</para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            For example, let say that the name of the event handler function is fooHandler
            for window number 0. A left click in the window at position [100,150] (in pixels)
            will be equivalent as calling fooHandler( 0, 100, 150, 3 ).
        </para>
        <para>
            See <link linkend="figure_properties">figure_properties</link> or <link linkend="seteventhandler">seteventhandler</link> for information on
            how to specify the event_handler name.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
function my_eventhandler(win,x,y,ibut)
  if ibut==-1000 then return,end
  [x,y]=xchange(x,y,'i2f')
  gcf().info_message = msprintf('Event code %d at mouse position is (%f,%f)',ibut,x,y);
endfunction

plot2d()
fig = gcf() ;
fig.event_handler = 'my_eventhandler' ;
fig.event_handler_enable = "on" ;
//now:
//   -  move the mouse over the graphic window
//   -  press and release keys shifted or not with Ctrl pressed or not
//   -  press button, wait a little release
//   -  press and release button
//   -  double-click button

fig.event_handler_enable = "off" ; //suppress the event handler
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="figure_properties">figure_properties</link>
            </member>
            <member>
                <link linkend="seteventhandler">seteventhandler</link>
            </member>
            <member>
                <link linkend="xgetmouse">xgetmouse</link>
            </member>
            <member>
                <link linkend="xclick">xclick</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
