<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 *
 * 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="rubberbox">
    <refnamediv>
        <refname>rubberbox</refname>
        <refpurpose>rubberband box for rectangle selection</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            [final_rect, btn] = rubberbox()
            [final_rect, btn] = rubberbox(initial_rect)
            [final_rect, btn] = rubberbox(edition_mode)
            [final_rect, btn] = rubberbox(initial_rect, edition_mode)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>initial_rect</term>
                <listitem>
                    <para>
                        a vector with two or four entries. With four entries it
                        gives the initial rectangle defined by <literal>[x_min,
                            y_max, width, height]
                        </literal>
                        (where
                        <literal>x_min</literal> and <literal>y_max</literal>
                        are coordinates of initial corner position, with two
                        entries width and height are supposed to be 0.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>edition_mode</term>
                <listitem>
                    <para>
                        a boolean, if <varname>edition_mode</varname> is
                        <constant>%t</constant> button press selects the first
                        corner, release selects the opposite corner. If
                        <varname>edition_mode</varname> is
                        <constant>%f</constant>, a button press or click selects
                        the first corner, a click is requested to select the
                        opposite corner. The default value is
                        <constant>%f</constant>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>final_rect</term>
                <listitem>
                    <para>
                        a rectangle defined by <literal>[x_min, y_max, width, height]</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>btn</term>
                <listitem>
                    <para>an integer, the number of the mouse button clicked.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <code>rubberbox(initial_rect)</code> tracks a rubberband box in
            the current graphic window, following the mouse. When a button is
            clicked <function>rubberbox</function> returns the final
            rectangles definition in <varname>final_Rect</varname>. If the
            argument <varname>initial_rect</varname> is not specified, a click
            is needed to fix the initial corner position.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
clf
plot2d()
a = gca();
db = a.data_bounds;
x0 = (db(1)*2+db(2))/3;
dx = (db(2)-db(1))/3;
y0 = (db(3)+db(4)*2)/3;
dy = (db(4)-db(3))/3;
xtitle(msprintf("With an initial starting corner: x0 = %0.2f, y0 = %0.2f",x0,y0))
r = rubberbox([x0 y0])
]]></programlisting>
        <programlisting role="example"><![CDATA[
clf
plot2d()
a = gca();
db = a.data_bounds;
x0 = (db(1)*2+db(2))/3;
dx = (db(2)-db(1))/3;
y0 = (db(3)+db(4)*2)/3;
dy = (db(4)-db(3))/3;
xtitle(msprintf("With an initial box: x0 = %0.2f, y0 = %0.2f, width = %0.2f, height = %0.2f,",x0-dx/4,y0+dy/5,2*dx,dy))
r = rubberbox([x0-dx/4 y0+dy/5 2*dx dy])
]]></programlisting>
        <programlisting role="example"><![CDATA[
clf
plot2d()
a = gca();
db = a.data_bounds;
x0 = (db(1)*2+db(2))/3;
dx = (db(2)-db(1))/3;
y0 = (db(3)+db(4)*2)/3;
dy = (db(4)-db(3))/3;
xtitle("In press -- drag -- release mode selection:")
r = rubberbox(%t)
]]></programlisting>
        <programlisting role="example"><![CDATA[
clf
plot2d()
a = gca();
db = a.data_bounds;
x0 = (db(1)*2+db(2))/3;
dx = (db(2)-db(1))/3;
y0 = (db(3)+db(4)*2)/3;
dy = (db(4)-db(3))/3;
xtitle("In starting click -- drag -- stopping click mode selection:")
r = rubberbox()
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="xrect">xrect</link>
            </member>
            <member>
                <link linkend="xrects">xrects</link>
            </member>
            <member>
                <link linkend="xclick">xclick</link>
            </member>
            <member>
                <link linkend="xgetmouse">xgetmouse</link>
            </member>
            <member>
                <link linkend="dragrect">dragrect</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
