86915b177e45f917319c3b7f7b9daf99c9b1e956
[scilab.git] / scilab / modules / graphics / help / en_US / rubberbox.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
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-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="rubberbox">
14     <refnamediv>
15         <refname>rubberbox</refname>
16         <refpurpose>Rubberband box for rectangle selection</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>[final_rect,btn]=rubberbox()
21             [final_rect,btn]=rubberbox(initial_rect)
22             [final_rect,btn]=rubberbox(edition_mode)
23             [final_rect,btn]=rubberbox(initial_rect, edition_mode)
24         </synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>initial_rect</term>
31                 <listitem>
32                     <para>vector with two or four entries. With four entries it gives the
33                         initial rectangle defined by [x_min, y_max, width, height], with
34                         two entries width and height are supposed to be 0.
35                     </para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>edition_mode</term>
40                 <listitem>
41                     <para>
42                         a boolean, if edition_mode is <literal>%t</literal> button press selects the first corner, release
43                         selects the opposite corner. If edition_mode is <literal>%f</literal>, a button press or
44                         click selects the first corner, a click is requested to select the
45                         opposite corner. The default value is %f.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>final_rect</term>
51                 <listitem>
52                     <para>a rectangle defined by [x_min, y_max, width, height]</para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>btn</term>
57                 <listitem>
58                     <para>an integer, the number of the mouse button clicked</para>
59                 </listitem>
60             </varlistentry>
61         </variablelist>
62     </refsection>
63     <refsection>
64         <title>Description</title>
65         <para>
66             <literal>rubberbox(initial_rect)</literal>  tracks a rubberband box in
67             the current graphic window, following the mouse. When a button is clicked <literal>rubberbox</literal> returns the final
68             rectangles definition in <literal>final_Rect</literal>. If the argument
69             <literal>initial_rect</literal> is not specified, a click is needed to fix the initial
70             corner position.
71         </para>
72     </refsection>
73     <refsection>
74         <title>Examples</title>
75         <programlisting role="example"><![CDATA[ 
76 clf
77 plot2d()
78 a = gca();
79 db = a.data_bounds;
80 x0 = (db(1)*2+db(2))/3;
81 dx = (db(2)-db(1))/3;
82 y0 = (db(3)+db(4)*2)/3;
83 dy = (db(4)-db(3))/3;
84 disp(gettext("With an initial starting corner:"))
85 r = rubberbox([x0 y0])
86 disp(gettext("With an initial box:"))
87 r = rubberbox([x0-dx/4 y0+dy/5 2*dx dy])
88 disp(gettext("In press -- drag -- release mode selection:"))
89 r = rubberbox(%t)
90 disp(gettext("In starting click -- drag -- stopping click mode selection:"))
91 r = rubberbox()
92  ]]></programlisting>
93     </refsection>
94     <refsection role="see also">
95         <title>See Also</title>
96         <simplelist type="inline">
97             <member>
98                 <link linkend="xrect">xrect</link>
99             </member>
100             <member>
101                 <link linkend="xrects">xrects</link>
102             </member>
103             <member>
104                 <link linkend="xclick">xclick</link>
105             </member>
106             <member>
107                 <link linkend="xgetmouse">xgetmouse</link>
108             </member>
109             <member>
110                 <link linkend="dragrect">dragrect</link>
111             </member>
112         </simplelist>
113     </refsection>
114 </refentry>