<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Djalel Abdemouche
 *
 * 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="rectangle_properties">
    <refnamediv>
        <refname>rectangle properties</refname>
        <refpurpose>description of the Rectangle
            entity properties
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The Rectangle entity is a leaf of the graphics entities hierarchy. This
            entity defines the parameters for rectangles and filled rectangles.
        </para>
        <variablelist>
            <varlistentry>
                <term>parent: </term>
                <listitem>
                    <para>This field contains the handle of the parent. The parent of the
                        rectangle entity should be of the type <literal>"Axes"</literal> or
                        <literal>"Compound"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>children: </term>
                <listitem>
                    <para>
                        This property contains a vector with the <literal>children</literal> of
                        the handle. However, <literal>rectangle</literal> handles currently do not
                        have any <literal>children</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_mode: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_mode</literal> property
                        value for the polyline. Its value should be <literal>"on"</literal> (marks
                        drawn) or <literal>"off"</literal> (no marks drawn).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_style: </term>
                <listitem>
                    <para>
                        The <literal>mark_style</literal> property value is used to select the
                        type of mark to use when <literal>mark_mode</literal> property is
                        <literal>"on"</literal>. The value should be an integer in [0 14] which
                        stands for: dot, plus, cross, star, filled diamond, diamond, triangle
                        up, triangle down, diamond plus, circle, asterisk, square, triangle
                        right, triangle left and pentagram.
                        The figure below shows the aspects of the marks
                        depending on the <literal>mark_style</literal> and the
                        <literal>mark_foreground</literal> and
                        <literal>mark_background</literal> properties.
                    </para>
                    <para>
                        <inlinemediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/marks.svg"/>
                            </imageobject>
                        </inlinemediaobject>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size_unit: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_size_unit</literal>
                        property value. If <literal>mark_size_unit</literal> is set to
                        <literal>"point"</literal>, then the <literal>mark_size</literal> value is
                        directly given in points. When <literal>mark_size_unit</literal> is set to
                        <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed relative
                        to the font size array: therefore, its value should be an integer in
                        [0 5] with stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
                        <link linkend="xrect">xrect</link> and pure scilab functions use
                        <literal>tabulated</literal> mode as default ; when using <link linkend="plot">plot</link>
                        function, the <literal>point</literal> mode is automatically enabled.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size: </term>
                <listitem>
                    <para>
                        The <literal>mark_size</literal> property is used to select the type of
                        size of the marks when <literal>mark_mode</literal> property is
                        <literal>"on"</literal>. Its value should be an integer in [0 5] which
                        stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_foreground: </term>
                <listitem>
                    <para>
                        This field contains the <literal>mark_foreground</literal> property
                        value which is the marks' edge color. Its value should be a color
                        index (relative to the current color_map) or 0 for transparent edge.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_background: </term>
                <listitem>
                    <para>
                        This field contains the <literal>mark_background</literal> property
                        value which is the marks' face color. Its value should be a color
                        index (relative to the current color_map) or 0 for transparent face.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_mode: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>line_mode</literal> property
                        value for the rectangle. Its value should be <literal>"on" </literal>(line
                        drawn) or <literal>"off"</literal> (no line drawn).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fill_mode: </term>
                <listitem>
                    <para>
                        If <literal>fill_mode</literal> property value is <literal>"on" </literal>,
                        the rectangle is filled with the foreground color, the
                        <literal>mark_mode</literal> must also have the value <literal>"off"</literal>. if
                        not and the value's property is <literal>"off"</literal> only the shape of
                        the rectangle is drawn using the foreground color.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_style: </term>
                <listitem>
                    <para>
                        The <literal>line_style</literal> property value should be an integer in
                        [1 8]. 1 stands for solid, the other value stands for a selection of
                        dashes (see <link linkend="axes_properties">getlinestyle</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>thickness: </term>
                <listitem>
                    <para>This property is a positive real specifying the rectangle width
                        in pixels. The displayed width is actually determined by rounding the supplied width
                        to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
                        value is considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>foreground: </term>
                <listitem>
                    <para>This field contains the color used to draw the outline of the
                        rectangle. Its value should be a color index (relative to the current
                        colormap).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>background: </term>
                <listitem>
                    <para>This field contains the color used to fill the rectangle. Its
                        value should be a color index (relative to the current colormap).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>data: </term>
                <listitem>
                    <para>This property is to return the coordinates of the upper-left point
                        of the rectangle and its width and height in user coordinates. The result is the matrix
                        <literal>[xleft,yup,[zup],width,height]</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>visible: </term>
                <listitem>
                    <para>
                        This field contains the <literal>visible</literal> property value for
                        the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .
                        By default, the rectangle is visible, the value's property is
                        <literal>"on"</literal>. If <literal>"off"</literal> the rectangle is not drawn on
                        the screen.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state: </term>
                <listitem>
                    <para>
                        This field contains the <literal>clip_state</literal> property value for
                        the rectangle. It should be :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> this means that the rectangle is not
                                clipped.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> this means that the rectangle is
                                clipped outside the Axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal> this means that the rectangle is clipped
                                outside the rectangle given by property clip_box.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_box: </term>
                <listitem>
                    <para>
                        This field is to determinate the <literal>clip_box</literal> property.
                        By Default its value should be an empty matrix if clip_state is "off".
                        Other cases the vector <literal>[x,y,w,h]</literal> (upper-left point width
                        height) defines the portions of the rectangle to display, however
                        <literal>clip_state</literal> property value will be changed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data: </term>
                <listitem>
                    <para>This field can be use to store any scilab variable in the
                        rectangle data structure, and to retrieve it.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
a=get("current_axes");//get the handle of the newly created axes
a.data_bounds=[-2,-2;2,2];

xrect(-1,1,2,2)

r=get("hdl");//get handle on current entity (here the rectangle entity)
r.type
r.parent.type
r.foreground=13;
r.line_style=2;
r.fill_mode="on";
r.background=color('red');
r.clip_box=[-1 1;1 1];
r.data(:,[3 4])=[1/2 1/2];
r.data(:,[1 2])=[1/2 1/2];
r.clip_state="off"
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
            <member>
                <link linkend="xrect">xrect</link>
            </member>
            <member>
                <link linkend="xfrect">xfrect</link>
            </member>
            <member>
                <link linkend="xrects">xrects</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>line_style value 0 is obsolete, use 1 instead (both are equivalent for SOLID). Using value 0 will produce an error in Scilab 5.4.1.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
