<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Djalel Abdemouche
 * Copyright (C) 2008 - INRIA - Jean-Baptiste Silvy
 *
 * 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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="arc_properties" xml:lang="en">
    <refnamediv>
        <refname>arc properties</refname>
        <refpurpose>description of the Arc entity properties</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The Arc entity is a leaf of the graphics entities hierarchy. This
            entity defines the parameters for ellipses and part of ellipses and the
            filled ones.
        </para>
        <variablelist>
            <varlistentry>
                <term>parent:</term>
                <listitem>
                    <para>This field contains the handle of the parent. The parent of
                        the arc 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>arc</literal> handles currently do not have any
                        <literal>children</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>thickness:</term>
                <listitem>
                    <para>This property is a positive real specifying the line 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>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>line_mode:</term>
                <listitem>
                    <para>This property allows to display or not the line representing
                        the arc. The value must be <literal>"on"</literal> or
                        <literal>"off"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fill_mode:</term>
                <listitem>
                    <para>
                        If <literal>fill_mode</literal> property value is
                        <literal>"on" </literal>, the arc is filled with the
                        <literal>background</literal> color.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>foreground:</term>
                <listitem>
                    <para>
                        This field contains the default <literal>foreground</literal>
                        property value used to draw the outside of the arc. It 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 arc. It 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, the width and the height of the inclosing rectangle as well
                        as the boundary angles of the sector. It is the matrix in user coordinates
                        <literal>[xleft,yup,[zup],width,height,a1,a2]</literal> where
                        <literal>a1</literal> and <literal>a2</literal> are the sector
                        boundary angles in degree.
                    </para>
                    <para>
                        <emphasis role="bold">Warning:</emphasis> in Scilab versions
                        up to 4.1.2 <literal>a1</literal> and <literal>a2</literal> were given in
                        degree/64.
                    </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>. If <literal>"on"</literal> the arc is
                        drawn, If <literal>"off"</literal> the arc is not displayed on the
                        screen.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arc_drawing_method:</term>
                <listitem>
                    <para>This field controls the kind of discretization used to render
                        the arc. Its value must be either <literal>"nurbs"</literal> or
                        <literal>"lines"</literal>. If <literal>"nurbs"</literal> is
                        selected then the arc is rendered using nurbs curves and surfaces.
                        This results in the display of a perfect ellipse part whatever the
                        view point is. If <literal>"lines"</literal> is selected then the
                        arc is approximated with a constant number of lines. This reduce
                        drawing time but some sharp edges may appear upon zooming. The use
                        of <literal>"lines"</literal> value is discouraged and should only
                        be used if a loss in framerate is noticed when using
                        <literal>"nurbs"</literal> value.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state:</term>
                <listitem>
                    <para>
                        This field contains the <literal>clip_state</literal> property
                        value for the arc. Clip_state value should be :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> this means that the arc is not
                                clipped
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> this means that the arc is
                                clipped outside the Axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal> this means that the arc is clipped
                                outside the arc 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 arc 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 arc
                        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];

xarc(-1.5,1.5,3,3,0,360*64)

arc=get("hdl"); //get handle on current entity (here the arc entity)
arc.fill_mode="on";
arc.foreground=5;
arc.data(:,[3 6])=[2 270*64];
xfarc(-.5,1,.4,.6,0,360*64);
arc.visible="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="xarc">xarc</link>
            </member>
            <member>
                <link linkend="xarcs">xarcs</link>
            </member>
            <member>
                <link linkend="xfarc">xfarc</link>
            </member>
            <member>
                <link linkend="xfarcs">xfarcs</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>
