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