<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Serge Steer
 * Copyright (C) 2008 - INRIA - Vincent COUVERT
 *
 * 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="xgetmouse">
    <refnamediv>
        <refname>xgetmouse</refname>
        <refpurpose>get the mouse events and current position</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>[rep [,win]]=xgetmouse([sel])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>sel</term>
                <listitem>
                    <para>
                        boolean vector <literal>[getmotion, getrelease]</literal>. default
                        value is <literal>[%t, %f]</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rep</term>
                <listitem>
                    <para>vector of size 3, [x,y,ibutton].</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>win</term>
                <listitem>
                    <para>number of the figure where the event occurred.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Despite <literal>xclick</literal>, <literal>xgetmouse</literal> does not prevent callback menu to be executed.
        </para>
        <para>
            If the mouse pointer is located in the current graphics window, <literal>xgetmouse</literal> returns
            in <literal>rep</literal> the current pointer position (x,y) and the value <literal>ibutton</literal>.

            The <literal>ibutton</literal> value indicates the event type:
        </para>
        <variablelist>
            <varlistentry>
                <term>ibutton==0</term>
                <listitem>
                    <para>Left mouse button has been pressed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==1</term>
                <listitem>
                    <para>Middle mouse button has been pressed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==2</term>
                <listitem>
                    <para>Right mouse button has been pressed</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==3</term>
                <listitem>
                    <para>Left mouse button has been clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==4</term>
                <listitem>
                    <para>Middle mouse button has been clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==5</term>
                <listitem>
                    <para>Right mouse button has been clicked</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==10</term>
                <listitem>
                    <para>Left mouse button has been double-clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==11</term>
                <listitem>
                    <para>Middle mouse button has been double-clicked</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==12</term>
                <listitem>
                    <para>Right mouse button has been double-clicked</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==-5</term>
                <listitem>
                    <para>Left mouse button has been released</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==-4</term>
                <listitem>
                    <para>Middle mouse button has been released</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==-3</term>
                <listitem>
                    <para>Right mouse button has been released</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==-1</term>
                <listitem>
                    <para>pointer has moved</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton &gt; =32</term>
                <listitem>
                    <para>key with ascii code ascii(ibutton) has been pressed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton &lt; =-32</term>
                <listitem>
                    <para>key with ascii code ascii(-ibutton)   has been released</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton &gt; =1000+32</term>
                <listitem>
                    <para>key with ascii code ascii(ibutton-1000) has been pressed while CTRL
                        key pressed
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ibutton==-1000</term>
                <listitem>
                    <para>graphic window has been closed</para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            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.
            This option has been removed in Scilab 5.1.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
//  rectangle selection
clf();  // erase/create window
a=gca();a.data_bounds=[0 0;100 100];//set user coordinates
xtitle(" drawing a rectangle ") //add a title
show_window(); //put the window on the top

[b,xc,yc]=xclick(); //get a point
xrect(xc,yc,0,0) //draw a rectangle entity
r=gce();// the handle of the rectangle
rep=[xc,yc,-1];first=%f;

while rep(3)==-1 do // mouse just moving ...
  rep=xgetmouse();
  xc1=rep(1);yc1=rep(2);
  ox=min(xc,xc1);
  oy=max(yc,yc1);
  w=abs(xc-xc1);h=abs(yc-yc1);
  r.data=[ox,oy,w,h]; //change the rectangle origin, width a height
  first=%f;
end
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="locate">locate</link>
            </member>
            <member>
                <link linkend="xclick">xclick</link>
            </member>
            <member>
                <link linkend="seteventhandler">seteventhandler</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
